---

SA_ Sector Engine System Calls

Init and Cleanup
SECOBID	SA_AllocObject (int maintype, int subtype)
void	SA_FreeObject (SECOBID obj)
SECOBID	SA_FindObject (SECOBID obj)
void	SA_SetEventObject (SECOBID obj, GALOBJ storyobject)
SECOBID	SA_GetEventObject (SECOBID obj)
int	SA_StartObjectInSpace (SECOBID ob, SECOBID pspace)
void	SA_LeaveObject (SECOBID pobj)
void	SA_KillObject (SECOBID pobj, int reason, SECOBID pkiller)
Synchronous Actions
int	SA_FlyObjectIntoContainer (SECOBID ob, SECOBID container)
int	SA_FlyObjectBeforeContainer (SECOBID ob, SECOBID container)
int	SA_FlyBigShipBeforeDockPos (SECOBID ob, SECOBID container, int x, int y, int z)
int	SA_ClearObjectFromCarrier (SECOBID ob, SECOBID cob)
int	SA_ClearObjectFromHangar (SECOBID ob, SECOBID cob)
int	SA_WarpObjectAway (SECOBID ob, SECOBID gateob)
int	SA_AvoidObjectCollision (SECOBID ob)
int	SA_CaptureObject (SECOBID ob, SECOBID victim)
int	SA_AttackObject (SECOBID ob, SECOBID victim,...)
int	SA_AttackObjectBig (SECOBID ob, SECOBID victim,...)
int	SA_EscortObject (SECOBID ob, SECOBID dstob, int xoffset, int yoffset, int zoffset, int precision)
int	SA_StopObjectTurret (SECOBID ob, int turretid, int reason)
int	SA_TurnToObject (SECOBID ob, SECOBID victim,...)
int	SA_TurretTurnToObject (SECOBID ob, SECOBID target, int turretid, int minturntime, int maxturntime)
int	SA_StartInHangar (SECOBID pob, SECOBID pcontainer)
int	SA_Idle (SECOBID pob, int delay)
int	SA_FollowObject (SECOBID pobj1, SECOBID pobj2, int precision)
int	SA_RotateToAngles (SECOBID ob, FIXED alpha, FIXED beta,...)
int	SA_MovePos (SECOBID pob, int x, int y, int z, int precision)
Get and Set Object Data
int	SA_GetMainType (SECOBID pob)
int	SA_GetSubType (SECOBID pob)
int	SA_GetType (SECOBID pob)
int	SA_GetPosX (SECOBID pobj)
int	SA_GetPosY (SECOBID pobj)
int	SA_GetPosZ (SECOBID pobj)
void	SA_SetPos (SECOBID pob, int x, int y, int z)
void	SA_SetSafePos (SECOBID pobj,...)
void	SA_SetRelativePos (SECOBID pobj, SECOBID refobj, int x, int y, int z)
FIXED	SA_GetRotAlpha (SECOBID pobj)
FIXED	SA_GetRotBeta (SECOBID pobj)
FIXED	SA_GetRotGamma (SECOBID pobj)
array	SA_GetRotationMatrix (SECOBID pobj)
void	SA_SetRot (SECOBID pob, FIXED alpha, FIXED beta, FIXED gamma)
FIXED	SA_GetDirX (SECOBID pobj)
FIXED	SA_GetDirY (SECOBID pobj)
FIXED	SA_GetDirZ (SECOBID pobj)
void	SA_SetDirection (SECOBID ob, FIXED dx, FIXED dy, FIXED dz)
int	SA_GetBody (SECOBID objid)
int	SA_GetCompBody (SECOBID objid)
int	SA_GetCutID (SECOBID pobj)
int	SA_GetObjectTextID (SECOBID objid)
int	SA_GetSize (SECOBID pob)
int	SA_GetTotalSize (SECOBID pob)
int	SA_GetMass (SECOBID pob)
int	SA_SetMass (SECOBID pob, int newmass)
int	SA_GetSpeed (SECOBID pob)
int	SA_GetMaxSpeed (SECOBID pob)
int	SA_SetSpeed (SECOBID pobj, int speed)
int	SA_GetDesiredSpeed (SECOBID pobj)
int	SA_SetDesiredSpeed (SECOBID pobj, int speed)
void	SA_SetExtraSpeed (SECOBID pobj, int percent)
int	SA_GetAcceleration (SECOBID pob)
void	SA_SetGlide (SECOBID pobj, int gx, int gy, int gz)
FIXED	SA_GetStepX (SECOBID pob)
FIXED	SA_GetStepY (SECOBID pob)
FIXED	SA_GetStepZ (SECOBID pob)
void	SA_SetExtraRotSpeed (SECOBID pobj, int percent)
int	SA_GetCount (SECOBID pware)
void	SA_SetCount (SECOBID pware, int num)
void	SA_SetLight (SECOBID psun, int r, int g, int b)
int	SA_GetShield (SECOBID pobj)
int	SA_GetMaxShield (SECOBID pobj)
int	SA_SetShield (SECOBID pobj, int shield)
int	SA_SetMaxAvoidShield (SECOBID pobj, int shield)
int	SA_GetLaser (SECOBID pobj,...)
int	SA_GetMaxLaser (SECOBID pobj,...)
int	SA_GetLaserPosition (SECOBID plaser)
int	SA_SetLaser (SECOBID pobj, int laser,...)
int	SA_GetHull (SECOBID pobj)
int	SA_GetMaxHull (SECOBID pobj)
int	SA_SetHull (SECOBID pobj, int hull)
int	SA_GetStrength (SECOBID pobj)
int	SA_GetNumCockpits (SECOBID pship)
BOOL	SA_MoveObjectIntoContainer (SECOBID pob, SECOBID pcontainer)
BOOL	SA_MoveLaserIntoContainer (SECOBID pob, SECOBID pcontainer, int position)
SECOBID	SA_FindObjectTypeInContainer (SECOBID pcontainer, int obtype,...)
SECOBID	SA_FindObjectSubTypeInContainer (SECOBID pcontainer, int obtype, int obsubtype,...)
SECOBID	SA_GetEnvironment (SECOBID pobj)
SECOBID	SA_GetDestination (SECOBID pobj)
BOOL	SA_IsEnemy (SECOBID ob, SECOBID ob2)
int	SA_GetRelation (SECOBID pobj1, SECOBID pobj2)
int	SA_SetRelation (SECOBID pobj1, SECOBID pobj2, int relation)
int	SA_SetGroupRelation (SECOBID pobj1, int group, int relation)
void	SA_SetGroup (SECOBID pobj, int group)
Data from ObjectDB / ShipDB
int	SA_GetNumSubTypes (int maintype)
int	SA_GetTypeGSubType (int maintype, int subtype)
int	SA_GetTypeMaxSpeed (int maintype, int subtype)
int	SA_GetTypeAcceleration (int maintype, int subtype)
int	SA_GetTypeMaxHull (int maintype, int subtype)
FIXED	SA_GetTypeStepX (int maintype, int subtype)
FIXED	SA_GetTypeStepY (int maintype, int subtype)
FIXED	SA_GetTypeStepZ (int maintype, int subtype)
int	SA_GetTypeTextID (int maintype, int subtype)
int	SA_GetTypeBody (int maintype, int subtype)
int	SA_GetTypeCompBody (int maintype, int subtype)
int	SA_GetShipTypeMaxExtraSpeed (int subtype)
int	SA_GetShipTypeMaxExtraRotSpeed (int subtype)
int	SA_GetShipTypeCockpitBody (int subtype)
int	SA_GetShipTypeMaxShieldType (int subtype)
int	SA_GetShipTypeMaxNumShields (int subtype)
int	SA_GetShipTypeMaxRocketType (int subtype)
int	SA_GetShipTypeMaxNumRockets (int subtype)
int	SA_GetShipTypeTradeContainerSize (int subtype)
int	SA_GetShipTypeMaxTradeContainerSize (int subtype)
int	SA_GetShipTypeMaxTKClass (int subtype)
int	SA_GetShipTypePowerGeneration (int subtype)
int	SA_GetShipTypeDockBaySize (int subtype)
int	SA_GetShipTypeNumCockpits (int subtype)
int	SA_GetShipTypeNumTurrets (int subtype)
int	SA_GetShipTypeNumLasersInTurret (int subtype, int turretid)
int	SA_GetMaxShipTypeLasers (int subtype)
int	SA_GetShipTypeTurretIDFromCockpitID (int subtype, int cockpitid)
int	SA_GetShipTypeTurretIDFromLaserPos (int subtype, int laserpos)
int	SA_GetShipTypeLaserPosFromTurretID (int subtype, int turretid)
int	SA_GetShipTypeTurretLaserMask (int subtype, int turretid)
int	SA_GetShipTypeCockpitTextID (int subtype, int cockpit)
int	SA_GetShipTypeTurretTextID (int subtype, int turretid)
int	SA_GetTypeTK (int maintype, int subtype)
int	SA_GetLaserTypeEnergyMax (int subtype)
int	SA_GetLaserTypeRange (int subtype)
int	SA_GetShieldTypeEnergyMax (int subtype)
int	SA_GetRocketTypeRange (int subtype)
int	SA_GetRocketTypeMaxDamage (int subtype)
int	SA_GetTypeDefaultRace (int maintype, int subtype)
Statistics
int	SA_GetLaserFired ()
int	SA_GetMissileFired ()
int	SA_GetLaserHits ()
int	SA_GetMissileHits ()
int	SA_GetTotalDistance ()
Other Syscalls
int	SA_ForceMove (SECOBID pob,...)
int	SA_StartAllShipsFromHangar (SECOBID pob)
int	SA_FireOnObject (SECOBID ob, SECOBID victim, int turretid)
SECOBID	SA_ShootMissileOnObject (SECOBID ob, SECOBID victim,...)
SECOBID	SA_FindNearestEnemy (SECOBID ob,...)
SECOBID	SA_FindNearestEnemyByStrength (SECOBID ob, int minstrength, int maxstrength,...)
BOOL	SA_IsTargetInFiringRangeOfTurret (SECOBID ob, SECOBID a_target, int a_turretid)
BOOL	SA_CollisionObject (SECOBID ob)
array	SA_GetCollisionObjects (SECOBID pobj)
int	SA_Distance (SECOBID pobj1, SECOBID obj2)
int	SA_MaxDistance (SECOBID pobj1, SECOBID obj2)
BOOL	SA_CheckDistances (SECOBID pobj)
void	SA_DoObjectSound (SECOBID pobj, int effect, int volume)
BOOL	SA_IsSafePos (SECOBID pobj, int xoff, int yoff, int zoff, int radius)
void	SA_OpenHangarDoors (SECOBID ob)
void	SA_SetHangarDoors (SECOBID ob, int state)
int	SA_ObjectTypeFromBody (int body)
int	SA_ObjectTypeFromCut (int cut)

---

Detailed Description

These system calls control the behaviour of Sector Objects, i.e. space ships, light sources (suns), scenes and pilot instrument features. Sector objects (SECOBID) only exist for all objects in the sector, in which the player currently is, while galaxy objects (GALOBJ) exist for all objects in the game. To get the SECOBID for a GALOBJ, the function GetObjectID() in the galaxy object is used. If the SECOBID is given and a galaxy object representation exists (always the case for ships and stations), the system call SA_GetEventObject() can be used to retrieve the galaxy object.
Most of the calls to get and set object data can also be done via functions in the Galaxy Objects, like OBJ_SHIP instances.

---

Function Documentation

SECOBID SA_AllocObject (  int    maintype, int    subtype )

Allocates a sector object. The object is not configured yet. Position, rotation, light parameters must be set and the object must be placed either in space (SA_StartObjectInSpace()) or moved into another object (SA_MoveObjectIntoContainer()).

int SA_AttackObject (  SECOBID    ob, SECOBID    victim, ...    )

Attack object victim. This function blocks until the target is in firing range or is destroyed. The optional third parameter is the minFlyTime. Returns SACMDFINISH_NORMAL The victim is firing range SACMDFINISH_NOAIM The victim was destroyed

int SA_AttackObjectBig (  SECOBID    ob, SECOBID    victim, ...    )

Attack object victim. This function blocks until the target is in firing range or is destroyed. The difference to SA_AttackObject() is that the object does not have to rotate in the direction to the target to be able to shoot at the target (big ships with rotating lasers!) The optional third parameter is the minFlyTime. Returns SACMDFINISH_NORMAL The victim is firing range SACMDFINISH_NOAIM The victim was destroyed

int SA_AvoidObjectCollision (  SECOBID    ob )

Tries to fly Object obj away from any potential obstacles. The function blocks until the action is finished. Returns: SACMDFINISH_WRONGPARAM Invalid paramters given SACMDFINISH_NORMAL The object has moved away far enough. SACMDFINISH_NOAIM The other object has been destroyed.

int SA_CaptureObject (  SECOBID    ob, SECOBID    victim )

Try to reach the position of victim, as with SA_AttackObject(), but returns only if the exact position is reached. This function should only be used with immovable targets. The target also should have collision detection turned off. This function blocks until the target is reached or is destroyed. Returns SACMDFINISH_NORMAL The victim has been reached and SA_MoveObjectIntoContainer() should be used to catch the victim SACMDFINISH_NOAIM The victim was destroyed

BOOL SA_CheckDistances (  SECOBID    pobj )

Checks if any other object is in the radius (actually octahedron) of this object. This is only a rough check.

int SA_ClearObjectFromCarrier (  SECOBID    ob, SECOBID    cob )

Fly a ship that has just started from a carrier ship away from that carrier.

int SA_ClearObjectFromHangar (  SECOBID    ob, SECOBID    cob )

Fly a ship that has just started from a station away from that station.

BOOL SA_CollisionObject (  SECOBID    ob )

Returns TRUE if the object is in danger of colliding with another object, or FALSE if not.

int SA_Distance (  SECOBID    pobj1, SECOBID    obj2 )

Exact distance between the centers of two objects.

void SA_DoObjectSound (  SECOBID    pobj, int    effect, int    volume )

Plays sound effect effect at location of object. The volume is currently ignored.

int SA_EscortObject (  SECOBID    ob, SECOBID    dstob, int    xoffset, int    yoffset, int    zoffset, int    precision )

Escort another ship in a certain (relative) distance to that ship. xoffset, yoffset and zoffset are relative to the target ship's coordinate system.

SECOBID SA_FindNearestEnemy (  SECOBID    ob, ...    )

Returns the nearest enemy ship or 0 if there is no enemy, optionally within a certain distance.

SECOBID SA_FindNearestEnemyByStrength (  SECOBID    ob, int    minstrength, int    maxstrength, ...    )

Returns the nearest enemy ship within a certain range of "strength".

SECOBID SA_FindObject (  SECOBID    obj )

Checks if sector object obj does still exist.

SECOBID SA_FindObjectSubTypeInContainer (  SECOBID    pcontainer, int    obtype, int    obsubtype, ...    )

Find next object of sector type (obtype, obsubtype) in container pcontainer, starting from last found object prevobj (optional fourth parameter) or beginning, if prevobj is NULL or not specified.

SECOBID SA_FindObjectTypeInContainer (  SECOBID    pcontainer, int    obtype, ...    )

Find next object of sector type obtype in container pcontainer, starting from last found object prevobj (optional third parameter) or beginning, if prevobj is NULL or not specified.

int SA_FireOnObject (  SECOBID    ob, SECOBID    victim, int    turretid )

Fires laser on victim, if there is enough energy available.

int SA_FlyBigShipBeforeDockPos (  SECOBID    ob, SECOBID    container, int    x, int    y, int    z )

Flies a big ship to the rendezvous position of container, given in x, y and z.

int SA_FlyObjectBeforeContainer (  SECOBID    ob, SECOBID    container )

Fly object to the rendezvous position of container. This is a safe position in front of the hangar doors from which the ship may make its final approach with SA_FlyObjectIntoContainer().

int SA_FlyObjectIntoContainer (  SECOBID    ob, SECOBID    container )

Short range maneouver to get a ship into a station or factory. Collision checks are no longer done as the path to the station is believed to be clear (no starts from the station are allowed during the landing). Returns completion codes: SACMDFINISH_WRONGPARAM Invalid parameters given SACMDFINISH_NOAIM Destination destroyed SACMDFINISH_NORMAL Docked. The ship should now be moved into the dock with SA_LandObjectInContainer().

int SA_FollowObject (  SECOBID    pobj1, SECOBID    pobj2, int    precision )

pobj1 follows pobj2.

int SA_ForceMove (  SECOBID    pob, ...    )

This disables any control of the ship by the sector engine. It is used to allow objects being moved along a predefined path with constant speed. Use the optional second parameter to switch on or off.

void SA_FreeObject (  SECOBID    obj )

Frees a sector object allocated with SA_AllocObject().

int SA_GetAcceleration (  SECOBID    pob )

Get maximal acceleration.

int SA_GetBody (  SECOBID    objid )

Gets the 3D-Body ID used by a sector object. If the object has no body or the object does not exist, the function returns -1, as 0 is a valid body number.

array SA_GetCollisionObjects (  SECOBID    pobj )

Returns an array of sector object IDs of all potential collision partners, or NULL if there is no such object. The system call allocates the array.

int SA_GetCompBody (  SECOBID    objid )

Gets the 3D-Body ID used to display in the ship menus.by a sector object. If the object has no body or the object doesn't exist, the function returns -1, as 0 is a valid body number.

int SA_GetCount (  SECOBID    pware )

Get the quantity of a ware object (main type SSTYPE_W_*).

int SA_GetCutID (  SECOBID    pobj )

Gets cut ID of pobj.

int SA_GetDesiredSpeed (  SECOBID    pobj )

Gets the desired speed.

SECOBID SA_GetDestination (  SECOBID    pobj )

Returns the destination object of pobj (ship, camera or missile).

FIXED SA_GetDirX (  SECOBID    pobj )

Gets the x coordinate of the direction vector.

FIXED SA_GetDirY (  SECOBID    pobj )

Gets the y coordinate of the direction vector.

FIXED SA_GetDirZ (  SECOBID    pobj )

Gets the z coordinate of the direction vector.

SECOBID SA_GetEnvironment (  SECOBID    pobj )

Gets the environment (container) object of pobj.

SECOBID SA_GetEventObject (  SECOBID    obj )

Gets the galaxy object (story object) used for notifications about the sector object obj.

int SA_GetHull (  SECOBID    pobj )

Gets the hull strength of pobj..

int SA_GetLaser (  SECOBID    pobj, ...    )

Get currently remaining total laser energy. The second parameter is the turret ID.

int SA_GetLaserFired (    )

Number of laser shots fired.

int SA_GetLaserHits (    )

Number of laser hits.

int SA_GetLaserPosition (  SECOBID    plaser )

Find mount position of a specific laser plaser in the ship.

int SA_GetLaserTypeEnergyMax (  int    subtype )

Gets the maximal energy in MW of a laser subtype.

int SA_GetLaserTypeRange (  int    subtype )

Gets the bullet range of a laser subtype in units.

int SA_GetMainType (  SECOBID    pob )

Returns sector main type of an object.

int SA_GetMass (  SECOBID    pob )

Returns the mass of the object. Default value is the total size of pob.

int SA_GetMaxHull (  SECOBID    pobj )

Gets the maximum hull strength of pobj..

int SA_GetMaxLaser (  SECOBID    pobj, ...    )

Get maximum total laser energy of object. The second parameter is the turret ID.

int SA_GetMaxShield (  SECOBID    pobj )

Gets the maximum total shield of object pobj.

int SA_GetMaxShipTypeLasers (  int    subtype )

Gets the total number of laser mount positions of the ship subtype.

int SA_GetMaxSpeed (  SECOBID    pob )

Get the current maximum speed of a ship object, including speed gained from a speed upgrade via SA_SetExtraSpeed().

int SA_GetMissileFired (    )

Number of missiles fired.

int SA_GetMissileHits (    )

Number of missile hits.

int SA_GetNumCockpits (  SECOBID    pship )

Returns the number of cockpits in the ship.

int SA_GetNumSubTypes (  int    maintype )

Gets the number of subtypes of maintype.

int SA_GetObjectTextID (  SECOBID    objid )

Gets the index to the text-database for the name of an object. You can use the function SE_ReadText(TPG_OBJDESC, id) to get the actual string.

int SA_GetPosX (  SECOBID    pobj )

Gets the current position of an object in 3D space (x coordinate).

int SA_GetPosY (  SECOBID    pobj )

Gets the current position of an object in 3D space (y coordinate).

int SA_GetPosZ (  SECOBID    pobj )

Gets the current position of an object in 3D space (z coordinate).

int SA_GetRelation (  SECOBID    pobj1, SECOBID    pobj2 )

Get the friend/foe relation of pobj1 towards pobj2. Return values are REL_FRIEND pobj1 considers pobj2 a friend REL_ENEMY pobj1 considers pobj2 a foe REL_NEUTRAL pobj1 is neutral towards pobj2 If the group of pobj2 is a computer controlled object, the relation is stored in the relation entry of pobj1. If pobj2 is a player, the relation information is stored in pobj2. In this case pobj2's relation towards pobj1 is the player's choice! If pobj1 and pobj2 are both computer controlled objects, pobj1 may have a different opinion of pobj2 than pobj2 does have of pobj1. Note that this relation has exactly 3 defined states. If the relation is -1, a ship will probably attack or a station won't let a ship dock.

int SA_GetRocketTypeMaxDamage (  int    subtype )

Gets the maximal damage of a rocket subtype.

int SA_GetRocketTypeRange (  int    subtype )

Gets the range of a rocket subtype in units.

FIXED SA_GetRotAlpha (  SECOBID    pobj )

Gets the current rotation of an object in 3D space (alpha).

array SA_GetRotationMatrix (  SECOBID    pobj )

Returns the rotation matrix as array.

FIXED SA_GetRotBeta (  SECOBID    pobj )

Gets the current rotation of an object in 3D space (beta).

FIXED SA_GetRotGamma (  SECOBID    pobj )

Gets the current rotation of an object in 3D space (gamma).

int SA_GetShield (  SECOBID    pobj )

Gets the current total shield of object pobj.

int SA_GetShieldTypeEnergyMax (  int    subtype )

Gets the maximal energy in MW of a shield subtype.

int SA_GetShipTypeCockpitBody (  int    subtype )

Gets the cockpit body of the ship subtype.

int SA_GetShipTypeCockpitTextID (  int    subtype, int    cockpit )

Gets the text ID of the cockpit of the ship subtype. You can get the cockpit name via SE_ReadText(TPG_COCKPITS, id). The function GetCockpitName() in the ship GALOBJ does the same.

int SA_GetShipTypeDockBaySize (  int    subtype )

Gets the dock bay size of the ship subtype.

int SA_GetShipTypeLaserPosFromTurretID (  int    subtype, int    turretid )

Gets the absolute laser index from the turret ID of the ship subtype.

int SA_GetShipTypeMaxExtraRotSpeed (  int    subtype )

Gets the maximum extra rotation speed that can be added to SA_GetTypeStepX(), Y and Z using ship upgrades.

int SA_GetShipTypeMaxExtraSpeed (  int    subtype )

Gets the maximum extra speed that can be added to SA_GetTypeMaxSpeed() using ship upgrades.

int SA_GetShipTypeMaxNumRockets (  int    subtype )

Gets the number of rocket slots of the ship subtype.

int SA_GetShipTypeMaxNumShields (  int    subtype )

Gets the number of shield slots of the ship subtype.

int SA_GetShipTypeMaxRocketType (  int    subtype )

Gets the maximal rocket subtype of the ship subtype.

int SA_GetShipTypeMaxShieldType (  int    subtype )

Gets the maximal shield subtype of the ship subtype.

int SA_GetShipTypeMaxTKClass (  int    subtype )

Gets the maximal Transport Class (TC) of the ship subtype.

int SA_GetShipTypeMaxTradeContainerSize (  int    subtype )

Gets the maximal cargo bay size with maximal number of cargo bay extension upgrades.

int SA_GetShipTypeNumCockpits (  int    subtype )

Gets the number of cockpits of the ship subtype.

int SA_GetShipTypeNumLasersInTurret (  int    subtype, int    turretid )

Gets the number of lasers in turret turretid of the ship subtype.

int SA_GetShipTypeNumTurrets (  int    subtype )

Gets the number of turrets of the ship subtype.

int SA_GetShipTypePowerGeneration (  int    subtype )

Gets the power of the ship's power generator in MW.

int SA_GetShipTypeTradeContainerSize (  int    subtype )

Gets the cargo bay size without any cargo bay extension upgrades.

int SA_GetShipTypeTurretIDFromCockpitID (  int    subtype, int    cockpitid )

Gets the turret ID from Cockpit ID of the ship subtype.

int SA_GetShipTypeTurretIDFromLaserPos (  int    subtype, int    laserpos )

Gets the turret ID from the absolute laser index of the ship subtype.

int SA_GetShipTypeTurretLaserMask (  int    subtype, int    turretid )

Gets the laser mask for the turret turretid of the ship subtype.

int SA_GetShipTypeTurretTextID (  int    subtype, int    turretid )

Gets the text ID of the turret of the ship subtype. You can get the turret name via SE_ReadText(TPG_COCKPITS, id). The function GetTurretName() in the ship GALOBJ does the same.

int SA_GetSize (  SECOBID    pob )

Get size of an object in units.

int SA_GetSpeed (  SECOBID    pob )

Get the current speed of a ship object.

FIXED SA_GetStepX (  SECOBID    pob )

x coordinate of rotation speed.

FIXED SA_GetStepY (  SECOBID    pob )

y coordinate of rotation speed.

FIXED SA_GetStepZ (  SECOBID    pob )

z coordinate of rotation speed.

int SA_GetStrength (  SECOBID    pobj )

Evaluates a relative tactical strength of an object based on its lasers and shields.

int SA_GetSubType (  SECOBID    pob )

Returns sector sub type of an object.

int SA_GetTotalDistance (    )

Total way traveled in km.

int SA_GetTotalSize (  SECOBID    pob )

Get size of object including subinstances.

int SA_GetType (  SECOBID    pob )

Returns Main- and Subtype of this object as TYPECODE(maintype, subtype).

int SA_GetTypeAcceleration (  int    maintype, int    subtype )

Gets the acceleration of object maintype/subtype in units/s².

int SA_GetTypeBody (  int    maintype, int    subtype )

Gets 3D body of object maintype/subtype.

int SA_GetTypeCompBody (  int    maintype, int    subtype )

Gets 3D body used in computer menus of object maintype/subtype.

int SA_GetTypeDefaultRace (  int    maintype, int    subtype )

Gets the ID of the default race of object maintype/subtype (ship or station).

int SA_GetTypeGSubType (  int    maintype, int    subtype )

Gets the galaxy subtype of sector maintype/subtype.

int SA_GetTypeMaxHull (  int    maintype, int    subtype )

Gets maximum hull strength of object maintype/subtype.

int SA_GetTypeMaxSpeed (  int    maintype, int    subtype )

Gets maximum speed of object maintype/subtype in units/s.

FIXED SA_GetTypeStepX (  int    maintype, int    subtype )

Rotation speed X of object maintype/subtype.

FIXED SA_GetTypeStepY (  int    maintype, int    subtype )

Rotation speed Y of object maintype/subtype.

FIXED SA_GetTypeStepZ (  int    maintype, int    subtype )

Rotation speed Z of object maintype/subtype.

int SA_GetTypeTextID (  int    maintype, int    subtype )

Gets the index to the text database for the name of a type (maintype/subtype). You can use the function SE_ReadText(TPG_OBJDESC, id) to get the actual string.

int SA_GetTypeTK (  int    maintype, int    subtype )

Gets the ware type Transport Class (TC) of object maintype/subtype.

int SA_Idle (  SECOBID    pob, int    delay )

Ship flies in a random direction for delay milliseconds.

BOOL SA_IsEnemy (  SECOBID    ob, SECOBID    ob2 )

Returns whether the object ob2 is an enemy to ob.

BOOL SA_IsSafePos (  SECOBID    pobj, int    xoff, int    yoff, int    zoff, int    radius )

Returns whether there is enough space at the given relative position to pobj.

BOOL SA_IsTargetInFiringRangeOfTurret (  SECOBID    ob, SECOBID    a_target, int    a_turretid )

Is the target in firing range for turret?

void SA_KillObject (  SECOBID    pobj, int    reason, SECOBID    pkiller )

Kills an object, with explosion. pkiller can be NULL. (See Reason for death).

void SA_LeaveObject (  SECOBID    pobj )

Remove object from Sector.

int SA_MaxDistance (  SECOBID    pobj1, SECOBID    obj2 )

Approximate Distance between two objects. This is actually less than the exact distance, as only the maximum of the differences of the x, y and z coordinates is returned (hence the name MAXdistance).

BOOL SA_MoveLaserIntoContainer (  SECOBID    pob, SECOBID    pcontainer, int    position )

Move laser object pob into the container (ship) and assign a specific mount position to it. The number of mount positions can be obtained by SA_GetMaxShipTypeLasers().

BOOL SA_MoveObjectIntoContainer (  SECOBID    pob, SECOBID    pcontainer )

Move object pob into the container object pcontainer.

int SA_MovePos (  SECOBID    pob, int    x, int    y, int    z, int    precision )

Ship flies to a specific absolute position in space, within a radius of precision around the target location. All parameters are in units.

int SA_ObjectTypeFromBody (  int    body )

Finds an object TYPECODE from a body.

int SA_ObjectTypeFromCut (  int    cut )

Finds an object TYPECODE from a cut.

void SA_OpenHangarDoors (  SECOBID    ob )

Opens the hangar doors of station ob.

int SA_RotateToAngles (  SECOBID    ob, FIXED    alpha, FIXED    beta, ...    )

Rotates the ship object to angles alpha, beta and optional gamma.

void SA_SetCount (  SECOBID    pware, int    num )

Set the number of units of a ware object.

int SA_SetDesiredSpeed (  SECOBID    pobj, int    speed )

Sets the desired speed.

void SA_SetDirection (  SECOBID    ob, FIXED    dx, FIXED    dy, FIXED    dz )

Sets the direction vector of the object.

void SA_SetEventObject (  SECOBID    obj, GALOBJ    storyobject )

Sets a galaxy object for notifications (callbacks) from the sector engine.

void SA_SetExtraRotSpeed (  SECOBID    pobj, int    percent )

Sets the extra rotation speed of the object which is added to SA_GetTypeStepX(), Y and Z.

void SA_SetExtraSpeed (  SECOBID    pobj, int    percent )

Sets the extra speed of the object which is added to SA_GetTypeMaxSpeed().

void SA_SetGlide (  SECOBID    pobj, int    gx, int    gy, int    gz )

Sets a glide speed of (gx, gy, gz) for the object.

void SA_SetGroup (  SECOBID    pobj, int    group )

Sets the group of pobj. group may be any of: G_PLAYER G_NEUTRAL G_ARGON G_XENON G_SPLIT G_PARANID G_BORON G_TELADI

int SA_SetGroupRelation (  SECOBID    pobj1, int    group, int    relation )

Set the relation of pobj towards a group group (see SA_SetGroup()). relation may take the values: REL_FRIEND pobj1 considers pobj2 a friend REL_ENEMY pobj1 considers pobj2 a foe REL_NEUTRAL pobj1 is neutral towards pobj2

void SA_SetHangarDoors (  SECOBID    ob, int    state )

Sets the hangar doors state of the station ob. Valid states are DOORSTATUS_OPEN, DOORSTATUS_CLOSED, DOORSTATUS_OPENING and DOORSTATUS_CLOSING.

int SA_SetHull (  SECOBID    pobj, int    hull )

Sets the hull strength of pobj.

int SA_SetLaser (  SECOBID    pobj, int    laser, ...    )

Sets the laserenergy. The third parameter is the turret ID.

void SA_SetLight (  SECOBID    psun, int    r, int    g, int    b )

Set the RGB color of the sun psun.

int SA_SetMass (  SECOBID    pob, int    newmass )

Sets the mass of the object.

int SA_SetMaxAvoidShield (  SECOBID    pobj, int    shield )

Sets a parameter which determines when a ship will try to evade another ship because of that ship's total shield.

void SA_SetPos (  SECOBID    pob, int    x, int    y, int    z )

Set the absolute position of object pob in space.

int SA_SetRelation (  SECOBID    pobj1, SECOBID    pobj2, int    relation )

Set the relation of pobj1 towards pobj2. relation may take the values: REL_FRIEND pobj1 considers pobj2 a friend REL_ENEMY pobj1 considers pobj2 a foe REL_NEUTRAL pobj1 is neutral towards pobj2

void SA_SetRelativePos (  SECOBID    pobj, SECOBID    refobj, int    x, int    y, int    z )

Set position of object relative to other object. The coords are FIXED parts relative to the coordinate system and size of the referred object.

void SA_SetRot (  SECOBID    pob, FIXED    alpha, FIXED    beta, FIXED    gamma )

Set the rotation of an object as fixed rotation angles alpha, beta and gamma. The fixed values must be between 0x00000 and 0x10000.

void SA_SetSafePos (  SECOBID    pobj, ...    )

Sets pobj to a safe position in space, so that it does not collide with any other object. If coordinates are given, the object is placed as near to those coordinates as possible. You can give a parameter otherobj instead of the coordinates, so the object is placed around that sector object.

int SA_SetShield (  SECOBID    pobj, int    shield )

Distributes a given number of energy to all shields.

int SA_SetSpeed (  SECOBID    pobj, int    speed )

Sets the current speed.

SECOBID SA_ShootMissileOnObject (  SECOBID    ob, SECOBID    victim, ...    )

Shoot a missile onto victim if one is available. The third optional parameter is the missile subtype. Returns the missile object or 0 not available.

int SA_StartAllShipsFromHangar (  SECOBID    pob )

All ships in starting position start immediately. This call is used before the current sector is deactivated, to allow all ships starting from a station to be in a defined state when the sector representations of all stations and ships are removed. Using this function during normal operation will make all ships collide!

int SA_StartInHangar (  SECOBID    pob, SECOBID    pcontainer )

Set ship pob on the start list of hangar pcontainer. Blocks until the ship is started or the start has been cancelled. Returns SACMDFINISH_NORMAL Ship has started and is flying away from hangar SACMDFINISH_LANDED Ship is still docked.

int SA_StartObjectInSpace (  SECOBID    ob, SECOBID    pspace )

Places an object in the space object. The object is placed at position (0, 0, 0) and should be positioned with SA_SetPos() or SA_SetSafePos().

int SA_StopObjectTurret (  SECOBID    ob, int    turretid, int    reason )

Stops the current command execution of synchronous system calls which then return the return code reason. Reason should normally be SACMDFINISH_STOPPED to signal abnormal termination. The system call itself returns immediately.

int SA_TurnToObject (  SECOBID    ob, SECOBID    victim, ...    )

Used to turn an immovable object in the direction of victim. Returns if the direction is reached. Example use are orbital lasers.

int SA_TurretTurnToObject (  SECOBID    ob, SECOBID    target, int    turretid, int    minturntime, int    maxturntime )

Turns turret to object.

int SA_WarpObjectAway (  SECOBID    ob, SECOBID    gateob )

Warp the ship out of the current sector.

---