Script Object

The Script Object API enables manipulation of objects via ForceScript.

Naming of objects

TFE introduces the ability to name objects, so that they can be referenced by the scripting system. Names may be up to 32 characters and are case insensitive like sector names.

Objects are named in the .O file as shown here:

/* 006 SEWERBUG.WAX  */
CLASS: SPRITE  DATA:  3 X: 232.00 Y: 0.00  Z: 264.00 PCH: 0.00  YAW: 0.00  ROL: 0.00  DIFF: 1
 SEQ
  LOGIC:     SEWER1
  NAME: sewer-creature2
 SEQEND

/* 007 REMOTE.WAX    */
CLASS: SPRITE  DATA:  2 X: 280.00 Y: 0.00  Z: 232.00 PCH: 0.00  YAW: 0.00  ROL: 0.00  DIFF: 1
 SEQ
  LOGIC:     REMOTE
  NAME: cool-remote
 SEQEND

/* 008 MOUSEBOT.3DO  */
CLASS: 3D      DATA:  2 X: 256.00 Y: 0.00  Z: 232.00 PCH: 0.00  YAW: 0.00  ROL: 0.00  DIFF: 1
 SEQ
  LOGIC:     MOUSEBOT
  NAME: mouse4
 SEQEND

Getting objects by name

To get objects by their name, use the methods in the Level Script API.

• getObject
• getObjectsByName

Once an object has been gotten by name, the script can do things with it.

Example:

Object mb1 = level.getObject("mousebot1");

if (mb1.exists())
{
    // Get the mousebot's position and move it eastwards by 20 units
    float pos = mb1.position;
    mb1.position = { pos.x + 20, pos.y, pos.z };
}

Object Properties

sector

• Get only
• Gets the object's current sector (Sector)
• Usage example: Sector troopSector = my_trooper.sector

position

• Get or set
• Gets or sets the object's position (float3)
• Usage example: move the object to coordinates x20, y80, z-350

myObj.position = {20, 80, -350};

yaw

• Get or set
• Gets or sets the object's yaw (float)
• Usage example: myObj.yaw = 120.0;

radius

• Get or set
• Gets or sets the object's radius / world width (float)
• Usage example: myObj.radius = 1.5;

worldWidth

• Get or set
• Gets or sets the object's radius / world width (float)
• Usage example: myObj.worldWidth = 1.5; // this is the same as radius

height

• Get or set
• Gets or sets the object's height / world height (float)
• Usage example: myObj.height = 9.5;

worldHeight

• Get or set
• Gets or sets the object's height / world height (float)
• Usage example: myObj.worldHeight = 9.5; // this is the same as height

Object Methods

exists()

• Returns true if the object exists, otherwise returns false
• Usage example:

Object trooper = level.getObject("stormtrooper3");

if (trooper.exists())
{
   ...
   ...
}

It is always wise to check if an object exists before doing something with it. Objects will often stop existing in Dark Forces (eg. killed enemies, destroyed scenery, ammo items that have been picked up)

isPlayer()

• returns true if the object is the player, otherwise returns false

matchPosition(Object)

• moves the object to the same position as another object
• usage example:

Object target = level.getObject("spirit7");
Object ds = level.getObject("deathstar_plans");

// move the death star plans to the same position as the spirit marker
if (ds.exists())
{
    ds.matchPosition(target);
}

matchPosition(string)

• moves the object to the same position as another object by name
• usage example:

// does the same as the above example, but uses the object's name
ds.matchPosition("spirit7");