This record describes API changes in 1.9 Beta 2.

Ship Classes

<Wreck> element

In API 50 there are two new options for the <Wreck> element:

<ShipClass ...>

noItems="true" means that items on the ship (including installed items) are not added to the wreck.

noInstalledItems="true" means that installed armor and devices are not added to the wreck.

Station Types

Placing Weapons on Segments

Some stations consist of a central object plus one or more satellite objects. In API 50 you can identify station satellites by ID and place weapons/devices on satellites.


<StationType unid="..."
      <Station id="wall1"  type="..." ... segment="true"/>

      <Device segmentID="wall1" ... />

In the example above, we create a station with a single satellite (wall1). We also place a device on the satellite. We use this technique for Sung Citadels.


Adjusting Item Frequency

In API 50 you can adjust the frequency of item spawning by system criteria. Any type may have an <ItemEncounterDesc> element:

<Type unid=...>
         criteria=         "* +commonwealth;" 
         frequency=        "common" 
         systemCriteria=   "+commonwealthSpace;"

         criteria=         "* +commonwealth;" 
         frequency=        "rare" 
         systemCriteria=   "+aresSpace;"

         criteria=         "* +commonwealth;" 
         frequency=        "notRandom" 

The directives above adjust the frequency of items globally. When generating random items, we adjust the frequency of an item if it matches one ore more of the directives above. The adjustment happens as follows:

  • First we check the systemCriteria. Any directives that do not match the system criteria are discarded.
  • If no directives match the current system, then we enable any directives with no system criteria (the last directive, in the example above).
  • For all enabled directives, we match the item against the criteria. We adjust the frequency appropriately.

In the example above, imagine a laser cannon in Commonwealth Space. The laser cannon is common intrinsically (rate = 20). We match the first directive because we're in Commonwealth Space. We do not match the second directive (not in Ares Space). The third directive is ignored because it is a default directive (no systemCriteria defined).

A laser cannon matches the item criteria of the first directive. But frequency="common" means that we don't change anything. We leave the laser cannon frequency alone.

Now imagine a laser cannon in Ares Space. We don't match the first directive (let's say) but we do match the second directive. We match the item criteria and thus we need to adjust to rare.

Adjustments are a multiplication of the rate:

                 Common     Uncommon  Rare      Very Rare
---------------- --------- --------- --------- ---------
Common   (20)     20        10         4         1
Uncommon (10)     10         5         2         -
Rare      (4)      4         2         1         -
Very Rare (1)      1         -         -         -

The laser cannon is intrinsically common, but we adjust to rare. Lookup up in the table above we end up with a frequency rate of 4 (rare).

Lastly, consider a laser cannon in some system outside of both Commonwealth and Ares Space. We don't match either of the two directives above, so we default to the final directive. In that case, the frequency is set to notRandom which means the laser cannon does not appear.

NOTE: You may use the new function (sysGetItemFrequency ...) to compute the frequency rate for a given item in a given system.

Weapon Items

Fading Damage

Starting in API 50 you can create a weapon whose damage decreases with the age of the projectile. For example:

<ItemType unid="..."
      damage=           "kinetic:10d20; radiation:7"
      damageAtMaxRange= "kinetic:1d20; radiation:1"

The new parameter, damageAtMaxRange= lets you specify the damage done when the projectile is at its maximum range. At intermediate ranges, we scale the damage linearly.

Attract and Repel Special Damage

Previous API allow you to specify momentum damage, which pushes and object when hit by a projectile:

<ItemType unid="&itRecoillessCannon;"
      damage="kinetic:1d6+1; momentum:1"

The momentum special damage can be a number from 1 to 7, corresponding to increasing force.

Starting in API 50 we introduce repel special damage, which is the same as momentum but that uses a different, larger scale from 1 to 100.

In addition, we introduce attract special damage, which pulls an object towards the direction where it's hit. attract special damage also uses the same scale from 1 to 100.

The new scale is an exponential scale with the following formula:

F = 10 · (5^(x/10) - 1)

x = Value of attract or repel special damage (1-100)
F = Force in meganewtons

The following table shows how much mass (in tons) you can accelerate to 10% light-speed given a certain attract/repel value. Lower masses will be accelerated more, higher masses less (proportionally in both cases).

                    TONS TO
VALUE      FORCE      10% c
 10           40          1
 20          240          8
 30        1,200         40
 40        6,200        210
 50       31,000      1,000
 60      160,000      5,200
 70      780,000     26,000
 80    3,900,000    130,000
 90   20,000,000    650,000
100   98,000,000  3,300,000

damage="kinetic:1d6+1; repel:20"

If an 8-ton mass is hit by the above damage, the mass will be accelerated to 10% of light-speed. A 16-ton mass will accelerate to 5% c, and a 4-ton mass will accelerate to 20% c.

You can convert the old momentum values using the following table:

                TONS TO
 1          250       8     repel:20
 2        1,000      33     repel:29
 3        2,250      75     repel:34
 4        4,000     133     repel:37
 5        6,250     208     repel:40
 6        9,000     300     repel:42
 7       12,250     409     repel:44

The old momentum special damage will continue to work unchanged. The engine will convert the values to the new scale appropriately. You do not need to change any existing mods and you can continue to use momentum if you find it easier.


  • Added noWMDHint="true" to suppress "use WMD weapon" warning.
  • Added noMiningHint="true" to suppress "use mining weapon" warning.

Mission Types

  • Added failureOnReturnToSystem="xx". If the player leaves the mission system for more than xx ticks, then on return to the mission system, the mission will fail (and not before).

System Types

  • We now support <EncounterOverrides> inside <SystemType>.
  • We now support <StargateTable> inside <TopologyCreator>.


  • Added shape="sword" to <Ray> effect.


  • Starting in API 50, we show a warning if an entity is redefined.
  • <ArmorLimits> now allow for an explicit mass= level (instead of a mass class).

Optional Libraries

When using a library, you can now specify how you use the library. For example:

<TranscendenceExtension ...>
   <Library unid="&unidCorporateHierarchyVol01;" usage="required"/>


Usage can be one of the following:

  • dependency: This means that you require the library, but if the library is not installed (perhaps because it is paid DLC), then the extension will not be offered to the player.
  • optional: This means that the library is not required for the extension, the extension will work (and should be offered) even if the library is not installed.
  • required: This means that the library is required and the player will see an error if the library cannot be found.



  • Starting in API 50, custom properties take precedence over engine properties. This is strictly for backwards compatibility purposes. There is no special benefit to overriding engine properties.
  • Added 'allowEnemyDocking property to stations.
  • Added 'canBeHitByFriends property to objects.
  • Added 'destroyWhenEmpty property to station objects.
  • Added 'expireTime property to mission types.
  • Added 'startingSystem to player ship objects.
  • Added 'stdChallengeRating property to systems.
  • Added 'stdTreasureValue property to systems.
  • Added 'subordinateID property to stations.
  • Added 'wreckTypeName property to ship classes.


  • (objAddOverlay...) now takes a 3D position as a list: (angle radius Z).
  • Added (objCanDestroyTarget obj target).
  • uiIsKeyPressed supports more keys.
  • objGetData, itmGetData, etc. now support the special value "*" to return all data for the object.


  • Starting in 1.9 Beta 2, if there's an error in a struct, we report it in debug mode. E.g., { a:(error 'WTF) } -> error (in debug mode)
  • In criteria, +unid:{xxx} now takes entities. E.g., +unid:itLaserCannon;.
  • Added +launches:{unid} special attribute. {unid} can be a number of an entity.