This record describes API changes and additions in 1.8 Alpha 2.

Items

Ammo Magazines

In API 37 you can define a single item (a magazine) which contains multiple rounds of ammo for a given weapon. The number of rounds left in the magazine is tracked with charges. Example:

<ItemType unid="..."
     name=       "1701 ammo[ magazine]"
     ...
     ammoCharges=       "true"
     charges=           "30"
     massBonusPerCharge="1"
     noSaleIfUsed      ="true"
     >
     ...
</ItemType>

The above defines an ammo magazine that contains 30 rounds (when new). Each time the weapon fires, a round is consumed (i.e., a charge is consumed). When all charges are consumed, the item is destroyed.

The ammoCharges="true" parameter is required to define this as a magazine.

Note also the new noSaleIfUsed="true" parameter. This checks to see if the magazine has full charges or not. If not, it has no value and thus not available to buy or sell.

Item Enhancements

Starting in API 37, all special damage types (such as EMP) can be conferred by enhancements.

Shields with Non-Regenerating HPs

Shields now support a flag allowing for charges to be non-regenerating HPs:

<Shields
   hitPoints=     "100"
   regen=         "10"
    
   hasNonRegenHP= "true"
   maxCharges=    "100"
   />

In the example above, the shield has 100 regenerating hit points and up to 100 non-regenerating hit points. Non-regenerating hit points can be added by setting the charges on the shield (by whatever method, usually by consuming some resource).

When damage, a shield loses regenerating hit points first. But once all regenerating hit points are lost, the shield starts losing non-regenerating hit points (which are not automatically restored).

Weapon Failure Modes

Damaged and overheating weapons fail in certain ways. Sometimes they misfire; other times they damage the ship. Prior to API 37, the chance of failure was hardcoded. Now it is possible to specify specific probabilities for each failure mode. For example:

<Weapon ...
   ...
   <OverheatFailure>
      <Failure type="noFailure"   chance="25"/>
      <Failure type="jammed"      chance="25"/>
      <Failure type="safeMode"    chance="25"/>
      <Failure type="explosion"   chance="25"/>
   </OverheatFailure>
</Weapon>

The following failure modes are supported:

  • noFailure: The weapon fires normally.
  • explosion: The weapon explodes and damages the ship.
  • heatDamage: The weapon is damaged.
  • jammed: The weapon does not fire.
  • misfire: The weapon fires in a random direction.
  • safeMode: The weapon disables itself and must be manually enabled.

The <OverheatFailure> element defines the failure modes when a weapon overheats. You can also use the <DamageFailure> element to define the failure mode for damaged weapons (using the same list of failure modes).

Fragmentation Radius

By default, fragmentation weapons will detonate when they get within 4 light-seconds of an active, enemy object. In API 37, you can control this radius by specifying a fragmentRadius= parameter (in light-seconds).

Ships

Ship Docking Ports

In API 37 you may specify ship docking ports using polar coordinates (posAngle=... posRadius=... posZ=...). This allows port positions to rotate along with the ship.

Default Ship Size

You may specify the size= parameter on a <ShipClass> to specify the size of a ship in meters. Starting in API 37, if you do not specify a size, the size is computed from the image size and the standard exponential scale.

Hull Value

The hullValue= parameter, which specifies the price of the ship's hull, has been moved to the ship class (instead of the <PlayerSettings>).

Sections

API 37 introduces a method for creation composite ships: ships composed of multiple, independent sections. For example the Balin dragon in Part II uses this technique.

To define a ship with multiple sections, use the <Interior> element to define objects attached to the ship. For example:

<Interior>
   <Section id="tail" class="..." posAngle="180" posRadius="20"/>
</Interior>

The above will create a secondary object (at the given position) and attach it to the main ship with a connection (using objAddConnection). The secondary objects are ships of the given class.

You can also create multiple sections and attach them to other sections. For example:

<Interior>
   <Section id="torso" class="..." posAngle="180" posRadius="20"/>
   <Section id="tail"  class="..." posAngle="180" posRadius="10" attachTo="torso"/>
</Interior>

Stations

Station Rotation Images

In API 37 you can specify image variants for different station rotations. For example:

<StationType ...>
   ...
   <Image>
      <RotationTable>
         <Image rotation="0"   imageID="&rsStationR0;" .../>
         <Image rotation="30"  ... />
         ...
         <Image rotation="330"/>
      </RotationTable>
   </Image>
</StationType>

The above table specifies a different image for the station at different rotations. You can then create a station at a particular rotation:

<SystemType>
...
   <Station type="..."  rotation="60"/>
...
</SystemType>

You can also set the rotation of a station via the 'rotation property. Station rotation affects station ports (they rotate appropriately).

Lastly, when specifying ports positions, we assume the station is rotated to angle 0. Nevertheless, sometimes it is helpful to specify port positions based on a different rotation (e.g., if you don't have a station image at 0 rotation).

In those cases you can specify the parameter rotation= in <DockingPorts> to indicate that the docking port positions described are for the given rotation. (This is particularly useful when using Cartessian coordinates to specify port positions.)

Overlays and Docking

Overlays can now add dock screens to a station. If an overlay implements the <GetDockScreen> event, they can return a screen to show when docking with the station.

Overlays also get an <OnObjDocked> event when a ship docks at a station with the overlay. The event gets the following data:

  • gSource: The station that the overlay is on.
  • aOverlayID: The overlay being called.
  • aObjDocked: The object docking with the station.

Removing Overlays

Some damage overlays may affect stations. Because stations are able to repair some damage, we've added a way for them to automatically remove some damage overlays.

Stations now call <OnRemoveAtDockServices> on any overlay attached to the station to remove it.

Challenge Rating

In API 37 we introduce a challenge rating that allows specifying station defenders in terms of the system level. See: Station Defender Reference.

Sovereigns

Relationships

In API 37 you may specify a relationship to an alignment. For example:

<Sovereign ...
   ...
   <Relationships>
      <Relationship alignment="empire"    disposition="friend" mutual="true"/>
   </Relationships>
   ...
</Sovereign>

This allows you to define relationships to groups of sovereigns as opposed to individual sovereigns.

<OnUpdate>

Sovereigns now have an <OnUpdate> event, which is called once every 30 ticks.

Effects

<ParticlePattern> effect

The <ParticleComet> effect has one major advantage over <ParticleSystem>: The particles are on fixed paths and thus require no instance data to paint. For example, no matter how many Lamplighter shots are being painted, we only need a single <ParticleComet> object. This improves both performance and memory use.

In API 37, we've generalized the <ParticleComet> effect and renamed it to <ParticlePattern>. Currently there are only two styles implemented: comet and jet, but eventually we will implement more.

In addition, <ParticlePattern> takes a <ParticleEffect> sub-element (just like <ParticleSystem>) to define how to paint each particle.

System Creation

<SystemType> Enhancements

The <SystemType> element defines the contents of a system. In API 37 we've added the following improvements:

The <Orbitals> directive positions one or more objects on an orbit. The angle= parameter defines where in the orbit to place the object. One of the values for angle= is equidistant, which places multiple objects evenly distributed around the orbit (at equal angles to each other).

In API 37, you can specify the angle of the first such object: angle="equidistant:n", where n is an angle. This allows for more control over the placement of objects.

<EncounterType> Elements

Traditionally, a <StationType> element defines both a station and the encounter rules for that station, such as level frequency, location criteria, etc.

Sometimes, however, we want to use the encounter rules to define an encounter but create a ship instead (e.g., a CSC). In previous APIs, this could be done by specifying a <StationType> element with a <Ships> child element.

In API 37 we are renaming this latter type of element to <EncounterType> to avoid the implication that this is related to stations. For example:

<EncounterType unid="..."
      name=        "CSC Encounter"
      sovereign=   "&svCommonwealthFleet;"
      ...
      />
   <Encounter
      levelFrequency="..."
      locationCriteria="..."
      />

   <Ships>
      <Ship count="1" class="&scCSCTaskForce;" orders="hold"/>
      ...
   </Ships>
</EncounterType>

The above is identical to the old method except the element is called <EncounterType>.

In this new version, we also support arbitrary creation of stations in an encounter type. For example:

<EncounterType unid="..."
      ...
      />
   <Encounter
      ...
      />

   <EncounterGroup>
      <Orbitals ...>
         <Station .../>
      </Orbitals>
   </EncounterGroup>
</EncounterType>

The <EncounterGroup> element accepts any sub-element that can be used to create a system in a <SystemType> element. This allows encounters that create multiple stations in various configurations.

Station Names

You may now specify a <Names> structure when creating a station in a <SystemType> definition.

System Limits

Encounters can be limited using the parameter unique="inSystem", but there is currently no way to limit spawning of a station to any number other than 1 (unique). In API 37 there is a new parameter: maxInSystem=, which limit the number of stations of the given type that can be spawned in a given system.

Language

Noun Article Syntax

The engine needs to compose noun phrases for items, ships, and stations. For example, we might describe "a barrel of organic acid" or "the freighter Kobayashi Maru". Traditionally we've used parameters to specify whether a noun should use definite or indefinite articles (or no article).

In API 37 you can specify a noun's article in the name itself:

name=":the Kobayashi Maru"
name=":an elixir of life"
name=": Starton Eridani"

The colon (:) indicates that we're specifying an article. Next we specify the article and indicate the end of the article with a space. Note that to specify no article you need to a space between the colon and the name.

Language Block Improvements

See: Guidelines for Language Elements

XML

XML Inheritance

Starting in API 37 we will always keep XML around for all extensions. This means you no longer need to specify the usesXML= parameter to call the XML functions (such as typGetXML).

In addition, we've radically enhanced the implementation of inheritance so that, for the most part, inheritance is syntactic. That is, when a type inherits from another type, we inherit XML elements and attributes from the base class.

The actual XML elements inherited depend on the type.

Obsolete Types

In API 37 you can mark any type as obsolete at a certain version. For example:

<StationType unid="..."
      obsolete="37"
      ...
      />
</StationType>

The above example indicates that the station type is obsolete in API 37. This means that any new games started with extensions that are at least at version 37, will not get this type.

Any saved games that use the type, and any new games that have extensions that might use the type, will continue to include the obsolete type.

TLisp

  • Added 'destiny property for objects.
  • Added 'sovereign property for objects (you may get and set the property).
  • Added 'sovGetName function.
  • Added 'subordinates property for stations. It returns a list of all subordinates of a station.
  • Added 'superior property for stations. For a subordinate, it returns the controlling station.
  • Added (sysHitTest source pos [options]) to determine whether an object is at the given position.
  • objGetOverlays can now accept an overlay type instead of a criteria. In that case, we return all overlays of the given type.
  • fmtNumber function now takes an option type parameter which can format a number as either an integer, a speed (as a fraction of light-speed), or a measure of power (MWs or GWs).
  • Added +inherit:{unid} special attribute to select types that inherit from a certain UNID.
  • Added 'installDeviceUpgradeOnly property. Any trading object return True for this property if devices are installed only as part of an upgrade.
  • Added 'rotation property for stations. See Station Rotation Images above.
  • Added +isShipEncounter:true and +isStationEncounter:true special attributes to find types that are ship or station encounters. See <EncounterType> Elements above.
  • Added 'namePattern property. It returns a struct with two fields: pattern is the name pattern for the object; flags contains the name flags. Use with fmtNoun.
  • objCommunicate function now takes a communications message ID.
0xabcdef 17 Jul 2017:

This API spec is incomplete. See this ticket.

george moromisato 12 Sep 2017:

Added info on sections and DamageFailure. Thanks!

0xabcdef 13 Sep 2017:

How are Section class objects defined? Are they ShipClasses or StationTypes?

george moromisato 13 Sep 2017:

They are ShipClasses; I've edited the text to specify that.