User Tools

Site Tools


modding:xml:spaceobject

This is an old revision of the document!


A SpaceObject is a meta-DesignType. You can't make something that is just a SpaceObject, but all ShipClasses and StationTypes are considered SpaceObjects for various funtions and other similarities.

Criteria

These codes are used in various functions that need to check for or list spaceobjects.

Criteria is here as of 1.7a

G         Stargates only
G:xyz;    Stargate with ID 'xyz'
s         Include ships
t         Include stations (including planets)
T         Include structure-scale stations
T:xyz;    Include stations with attribute 'xyz'
A         Active objects only (i.e., objects that can attack)
B:xyz;    Only objects with attribute 'xyz'
D:xyz;    Only objects with data 'xyz'
E         Enemy objects only
F         Friendly objects only
H         Only objects whose base = source
M         Manufactured objects only (i.e., no planets or asteroids)
N         Return only the nearest object to the source
N:nn;     Return only objects within nn light-seconds
NN:nn;    Return only nearest object if it's within nn light seconds (just combination of two above codes)
O:abc;    Ships whose order is abc [docked, patrol, escort etc...]
P         only objects visible to source
J         only objects from a given sovereign
K         only objects that cannot attack
R:nn;     Return only objects greater than nn light-seconds away
V         Include Virtual objects
Z         Exclude player
z         Only include player
b         Beam Objects
m         Missile Objects
X         Objects targeting Source
S:d       returns objects sorted by distance (in ascending order)
S:D       returns objects sorted by distance (in descending order)
I:angle   returns only objects that intersect a line from the source at the given angle
+xyz;     Include objects with the given attribute
-xyz;     Exclude objects with the given attribute
+unid:UNID                   Return ships of type UNID. 
+isPlayerClass:true/false    Filter based on presence of PlayerSettings in object's type, ships only.
+data:attribute              Checks if (objGetData theObject 'attribute) is non-nil
-data:attribute              Checks if (objGetData theObject 'attribute) is nil

Note: Virtual stations are not searched by default through t; therefore you should use V as well if searching for a virtual station.

Functions

Functions starting with 'obj' work on any SpaceObject. Due to the generic nature of SpaceObjects this is likely the largest set of functions in tScript.

Events

SpaceObjects also take the lion's share of event definitions in the game.

<CanDockAsPlayer>

<GetDockScreen>

Identical format to getglobaldockscreen

<OnAttacked>

<OnAttackedByPlayer>

<OnCreate>

For systems, stations, ships, at object creation.

<OnCreateOrders>

<OnDamage>

Populated variables:

  • 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 an object is hit by a weapon. The event must return the number of hit points of damage to do to the object. For example, imagine an object 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. (why is this. Does anyone know)

<OnDestroy>

Populated variables:

  • 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.

<OnDockObjAdj>

<OnEnteredGate>

Populated variables:

  • gSource: station object
  • aGateObj: gate object
  • aGateObj: The gate that was entered (1.07)
  • aDestNodeID: The destination node (1.07)
  • aDestEntryPoint: The destination entry point label (1.07)

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

<OnEnteredSystem>

<OnEventHandlerInit>

<OnLoad>

<OnMining>

For asteroids.

<OnOrderChanged>

<OnOrdersCompleted>

<OnPlayerEnteredSystem>

<OnPlayerLeftSystem>

<OnRandomEncounter>

Todo: check both this and designtype version and find difference?

<OnTranslateMessage>

Registered SpaceObject Events

All <OnObj*> events let an object know that something happenned to another object to which events it has previously registered.

After calling (objRegisterForEvents receiver object), receiver gets these events for object. Both must be live spaceObjects

<OnObjDestroyed>

Populated variables:

  • aObjDestroyed: the object that was destroyed.
  • aDestroyer: the object that caused the destruction.
  • aOrderGiver: the object that controls aDestroyer (in case aDestroyer is an auton or something).
  • aDestroyReason: One of: (damage, runningOutOfFuel, radiationPoisoning, self, disintegration, weaponMalfunction, ejecta, explosion, shatter, playerCreatedExplosion, enteredStargate, custom).
  • aWreckObj: the wreck left behind the destroyed object.
  • gSource: the object that holds the event.

Is triggerred when an object A has registered for object B events and object B is destroyed. <OnDestroy> is fired on object B, and <OnObjDestroyed> is fired on object A.

0.99c: 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.

See example on earth slaver.

<OnObjDocked>

Populated variables:

  • aObjdocked: the ship that initiated docking.
  • aDockTarget: the object that was docked with.
  • gSource: the object that holds the event.

This was primarily used before <OnOrdersCompleted>.

<OnObjEnteredGate>

Populated variables:

  • aObj: the ship that used the gate.
  • gSource: the object that holds the event.
  • aGateObj: The gate that was entered (1.07)
  • aDestNodeID: The destination node (1.07)
  • aDestEntryPoint: The destination entry point label (1.07)

<OnObjJumped>

Populated variables:

  • aObj: the ship that jumped.
  • gSource: the object that holds the event.
  • (return): ignored

<OnObjJumpPosAdj>

Populated variables:

  • aObj: the ship that jumped.
  • gSource: the object that holds the event.
  • (return): if a vector is returned, change aObj's position to it

Appears to be used to prevent the player from bypassing the heretic quarentine with a jumpdrive.

<OnObjReconned>

Populated variables:

  • aObj: the object that was reconned by the player.
  • gSource: the object that holds the event.

Registered System Events

George's Explination

First, you need to call:

(objRegisterForSystemEvents obj distance)

obj is the object that you want to receive OnSystemWeaponFire distance is the radius (in light-seconds) of the area (centered on obj) that you want to watch for events.

You will then get called at OnSystemWeaponFire whenever a ship or a station fires a weapon (I believe it will also include calls to sysCreateWeaponFire, but only if objSource is not Nil). The parameters to OnSystemWeaponFire are:

aWeaponObj is the object that fired the weapon. aWeaponUNID is the UNID of the weapon being fired. aWeaponPos is the position where the shot originated.

You will also get called at OnSystemExplosion if there are any ships that explode. The parameters are:

aExplosionObj is the ship that exploded. aExplosionUNID is the UNID of the explosion (look in StdExplosions.xml). aExplosionPos is the position of the explosion.

<OnSystemExplosion>

events called at any ships that explode. The parameters are: Populated variables:

  • aExplosionObj is the ship that exploded.
  • aExplosionUNID is the UNID of the explosion (look in StdExplosions.xml).
  • aExplosionPos is the position of the explosion.

<OnSystemObjAttacked>

(New in 1.07)
Populated variables:

  • gSource : the object getting the event
  • aObjAttacked : the object that was attacked
  • aCause : the missile object that hit
  • aAttacker : the object that fired the missile
  • aOrderGiver : the object that ordered the missile to be fired (e.g., if aAttacker is an auton)
  • aHitPos : where it hit
  • aHitDir : the direction from which the hit came
  • aDamageHP : damage hit points
  • aDamageType : damage type
  • aWeaponType : unid of the weapon used

<OnSystemObjDestroyed>

(New in 1.07)
Populated variables:

  • gSource : the object receiving the event
  • aObjDestroyed : the object that was destroyed
  • aDestroyer : the object that fired the missile that destroyed
  • aOrderGiver : the object that ordered the missile to be fired.
  • aWreckObj : the resulting wreck (if any)
  • aDestroyReason : the cause of the destruction (damage, disintegration, etc.)

<OnSystemWeaponFire>

You will then get called at OnSystemWeaponFire whenever a ship or a station fires a weapon (I believe it will also include calls to sysCreateWeaponFire, but only if objSource is not Nil). The parameters to OnSystemWeaponFire are:

Populated variables:

  • aWeaponObj: is the object that fired the weapon.
  • aWeaponUNID: is the UNID of the weapon being fired.
  • aWeaponPos: is the position where the shot originated.
modding/xml/spaceobject.1463780509.txt.gz · Last modified: 2016/05/20 21:41 by rpc