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 ...>
...
<Wreck
noInstalledItems="true"
noItems="true"
/>
...
</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.
Example:
<StationType unid="..."
...
<Satellites>
<Station id="wall1" type="..." ... segment="true"/>
</Satellites>
<Devices>
<Device segmentID="wall1" ... />
</Devices>
</StationType>
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.
Items
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=...>
<ItemEncounterDesc>
<Frequency
criteria= "* +commonwealth;"
frequency= "common"
systemCriteria= "+commonwealthSpace;"
/>
<Frequency
criteria= "* +commonwealth;"
frequency= "rare"
systemCriteria= "+aresSpace;"
/>
<Frequency
criteria= "* +commonwealth;"
frequency= "notRandom"
/>
</ItemEncounterDesc>
</Type>
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="..."
...
<Weapon
damage= "kinetic:10d20; radiation:7"
damageAtMaxRange= "kinetic:1d20; radiation:1"
...
</Weapon>
</ItemType>
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;"
...
<Weapon
damage="kinetic:1d6+1; momentum:1"
...
</Weapon>
</ItemType>
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
Example: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
MOMENTUM FORCE 10% c NEW VALUE
----------------------------------------------
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.
Miscellaneous
- 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>
.
Effects
- Added
shape="sword"
to<Ray>
effect.
Miscellaneous
- Starting in API 50, we show a warning if an entity is redefined.
<ArmorLimits>
now allow for an explicitmass=
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"/>
</TranscendenceExtension>
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.
TLisp
Properties
- 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.
Functions
(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.
Miscellaneous
- 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.