New in Version 0.99

This article describes all of the changes and additions to the modding system in version 0.99.

Adventure Extensions

Adventure extensions are a new kind of mod that allow you to create your own stand-alone adventures with your own star system topology. At the beginning of a game, the player is asked to choose from the list of installed adventures. You can create an adventure extension the same way you create any extension. There are a few major differences:

The root element is <TranscendenceAdventure>
The extension must have a <AdventureDesc> element (see Transcendence.xml for an example).
The extension must have a <SystemTopology> element (see Transcendence.xml for an example).
Any design types (or design type overrides) included in an adventure are only applied if the user chooses that adventure.

Design Types

Starting with 0.99, design types such as ShipClass, ItemType, and StationType have been unified. In general, anything with an UNID is considered a "design type" and some functions will work with any design type. For example, the function (typGetStaticData) works with any design type. [previously you had to use (staGetStaticData) to get static data for a StationType and (shpGetStaticData) to get static data for a ShipClass.]

All design types support the following events:

<OnGlobalSystemCreated>
(no parameters)

This event is called after a system is created (right after <OnCreate> for the system). You may use this event to create new objects in the system or to otherwise alter the system. Remember that there is no guarantee that other systems have been created at this point.

Look at Huari.xml for an example of how this event is used.

<OnGlobalTopologyCreated>
(no parameters)

This event is called at the beginning of the game right after the complete system topology has been generated. You may use this event to explore the topology and add data to topology nodes that may later be used inside systems. Remember that no systems have been created yet. You can only call functions that work on topology nodes.

For an example of how this event is used, look at Huari.xml.

StationType

The StationType element has a few new attributes:

noFriendlyTarget="true | false"

When set to true, the station will not be hit by any weapon fired by a friend.

unique="inSystem | inUniverse | false"

Previously, the unique attribute for a station specified that only one instance of the station would ever be encountered (this was used for the CSC encounters). Now you may use the keyword inSystem to specify that at most one instance of the station should be created per system.

The StationType element has the following new and modified events:

<GetExplosionType> Event
gSource = station object

This event is called when a station explodes. The event must return the UNID of an explosion definitions (see StdExplosions.xml) or Nil (if no special explosion is desired).

<OnDamage> Event
gSource = station object
aAttacker = object that attacked
aHitPos = vector position of hit
aHitDir = angle direction from which hit came
aDamageHP = hit points of damage
aDamageType = type of damage

This event is called when a station is hit by a weapon. The event must return the number of hit points of damage to do to the station. For example, imagine a station that takes half damage from the player (but full damage from all others). The event could check aAttacker and return half of aDamageHP if it is the player and full aDamageHP otherwise.

The event should avoid affecting other objects and should not destroy the station (e.g., by calling objDestroy). If necessary, the event could return a very large number to insure that the station is destroyed.

<OnEnteredGate>
gSource = station object
aGateObj = gate object

Version 0.99 uses aGateObj instead of aGate (as in previous versions) to be consistent with <OnObjEnteredGate>.

ShipClass

The ShipClass element has the following changes:

noArticle="true | false"
definiteArticle="true | false"

The above attributes are now honored in ShipClass. They are used to help compose a noun phrase from the ship class name.

<AISettings>
ignoreShieldsDown="true|false"

An enemy ship with the ignoreShieldsDown attribute set to true in <AISettings> will not retreat when its shields drop. This attribute has no effect on ships without shields.

<Devices>

The <Devices> element for a ShipClass now accepts random configurations such as <Table>. Look at scArcoVaughnHeavyRaider in CentauriWarlords.xml for an example.

<Names>

The <Names> element now honors all the attributes for noun phrases (e.g., noArticle). This allows for more variety in named ships.

<OnDestroy> Event
gSource = ship object
aDestroyer = object that caused destruction
aWreckObj = ship wreck left behind

The <OnDestroy> event now includes the aWreckObj parameter that allows you to access the wreck left behind by a ship. This parameter is sometimes Nil if the ship left no wreck.

<OnObjDestroyed> Event
gSource = object called
aObjDestroyed = object destroyed
aDestroyer = object that caused destruction
aWreckObj = ship wreck left behind

The <OnObjDestroyed> event now includes the aWreckObj parameter that allows you to access the wreck left behind by a ship. This parameter is sometimes Nil if the ship left no wreck.

<PlayerSettings>
shipScreen="{unid} | {screen-name}"

A player ship may specify a custom ship screen. This allows the modder to override the screen that comes up when the player presses the [S] key.

ItemType

<Armor>
hpBonus="{damage bonus by type}"

<Shields>
hpBonus="{damage bonus by type}"

Both armor and shield items have a new way of specifying resistance to certain damage types. Rather than specifying an absolute resistance value (which varies by level) you may now specify a percent bonus above or below the standard resistance for armor or shields of that level. This makes it easier to compare armor and shields across levels. See StdArmor.xml and StdShields.xml for examples.

If the hpBonus attribute is omitted, then we default to the standard resistance values for the level.

<OnAIUpdate> Event
gSource = object that carries the item
gItem = the item

The OnAIUpdate event for an item is called once every 30 ticks on every non-player ship that carries the item. Use this event to implement special behaviors. For example, an <OnAIUpdate> event on an armor patch item allows a non-player ship to use the armor patch when it is damaged.

Use this event sparingly because it will impact performance.

<OnUpdate> Event
gSource = object that carries the item
gItem = the item

The OnUpdate event for an item is called once every 30 ticks on every object that carries the item. Use this event sparingly because it will impact performance.

<Weapon>
interaction="{percent}"

The interaction attribute for a weapon specifies how a missile or bullet interacts when hit by another missile or bullet. For example, when bullet A hits bullet B, we compare the interaction value of the the two and take the highest value. The result is the percent chance that the two bullets will hit each other. If an interaction attribute is no specified, the weapon defaults to an interaction of 100.

<Weapon>
hitPoints="{hit points}"

This attribute specifies the number of hit points that a missile or bullet has in flight. By default a missile or bullet has 0 hit points (i.e., it can be destroyed by any hit).

Functions

Version 0.99 includes the following new functions (use the (help) command to get argument lists):

(envHasAttribute)
(filter)
(find)
(itmGetData)
(itmGetGlobalData)
(itmGetStaticData)
(itmGetTypes)
(itmSetCharges)
(itmSetCount)
(itmSetDamaged)
(itmSetData)
(itmSetGlobalData)
(max)
(min)
(objFireItemEvent)
(objGetImageDesc)
(objGetLevel)
(objGetMass)
(objGetObjByID)
(objGetVel)
(objIsDockedAt)
(objMatches)
(plyGetGenome)
(seededRandom)
(shpGetClassName)
(shpGetDataField)
(shpGetImageDesc)
(shpGetMaxSpeed)
(shuffle)
(staGetMaxStructuralHitPoints)
(sysAddStargateTopology)
(sysCalcTravelTime)
(sysCreateStargate)
(sysGetEnvironment)
(sysGetNodes)
(sysGetStargateDestinationNode)
(sysGetSystemType)
(sysGetVectorSpeed)
(sysHasAttribute)
(sysVectorAngle vector)
(typGetGlobalData)
(typGetStaticData)
(typIncGlobalData)
(typSetGlobalData)

In addition, the following changes have been made to functions:

All item cursors are gone; instead, all function take and return full item structures.
Deprecated (scrGetItemListCursor) and (itmAtCursor) and (scrRefreshItemListCursor)
(objEnumItems) now iterates over item structures, not item cursors
Added "O:docked;" to (sysFindObject)
Added "O:guard;" to (sysFindObject)
Added %1% replaceable parameters to (plyComposeMessage)
Passing Nil to (objIsAbandoned) returns True--useful when a station has been destroyed
(objGetBuyPrice) returns 0 for items the station is not interested in; it returns Nil for items that are not listed
(add) and (multiply) now take more than 2 arguments
Removed (plyIncreaseDominaRel)
Removed (plyIncreaseOracusRel)
Renamed (itmHasModifier) to (itmHasAttribute)
(sysGetLevel) now takes an optional nodeID
(sysGetName) now takes an optional nodeID
(sysCreateStation) now creates satellites too
Deprecated (shpGetItemCharges)
Renamed (modulus) to (modulo)

Miscelleneous

Version 0.99 includes an extensive overhaul of all design types (ShipClass, ItemType, etc). In particular, this version fixes many of the bugs with overriding design types. In addition, this version includes the following:

<ShipTable> definitions are now supported in extensions.
<EnergyField> definitions are now supported in extensions.
<SpaceEnvironment> definitions are now supported in extensions.
<EffectType> definitions are now supported in extensions.
Dice ranges now use 32-bit values.
<Orbitals> have a new format for the angle attribute. You may specify an angle of the form: "incrementing: range" where range is a dice range that specify the number of degrees to increment. See Eridani.xml for an example of how this is used.