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
    float3 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())
{
   ...
   ...
}

Note: Scripting functions will internally do an exists check before being executed. Therefore it is not necessary for you to check that an object exists in ForceScript before calling methods on it. If you try to manipulate an object (eg. set its position) that doesn't exist, nothing will happen. If you get a property from a non-existent object, a default value will be returned (usually zero).

The exists() function in ForceScript enables you to check for an object's existence so that you can make your script logic conditional on an object's existence. For example, you may want your script to do something only if a certain enemy has been killed, or a certain item has been collected.

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
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");

delete()

• Removes the object from the level
• usage example: ewok2.delete();

addLogic(string)

• Adds a logic to the object. Works with scenery, enemy logics, and pickup items. (Still to do: enable adding a custom logic.)
• usage example:

// turn the table into scenery so it becomes breakable
table.addLogic("scenery");

// add Nava card logic to the object so it can now be picked up
navcard.addLogic("nava");

// add commando logic
com5.addLogic("commando");