Lua Scripting Documentation

Lua Mission Scripting API Documentation for Battlezone Combat Commander version 2.0.185.

Lua Scripting Overview

How to use Lua Mission Scripting:

When you save a Map, if you select the Path tab, and choose "Lua Mission", it will set the Mission Script to use the custom Lua DLL. This runs a custom Lua file that has the same file name as the bzn. So when you save your map as myfoo.bzn with the Path set to Lua Mission, the map will try to load and run myfoo.lua.

This guide lists of all the Mission Lua functions, and a description of what they do. Lua can be used to create both Single Player and Multi Player mission scripts and custom actions. Everything the Stock Mission DLL code does, can also be done in Lua. This means anything the stock missions do, you can do, and much more if you're creative.

List of Data Types:

• Handle: A special Integer number used to ID a GameObject in the world. Considered UserData.
  
• int: A whole number.
  
• Number: A float/long, number with a decimal place.
  
• Bool: Boolean value, true/false. nil is false, anything not nil/false is true.
  
• String: A string of characters, like "foo".
  
• Char: A single character, like 'a'.
  
• Vector: A set of 3 numbers that is used for a Position in 3d space.
  
• Matrix: A set of 4 Vectors, used for a Transform Matrix that has Rotation and Position.
  
• Quaternion: A set of 4 numbers, that represents a Rotation.

How do Lua Functions work?

Typically, a function is broken down into the following:

A function with a Return value and Input Arguments:

ReturnValue FunctionName(Input Argument1, Input Argument2, etc...)

A function with no return value, and input Arguments:

FunctionName(Input Argument1, Input Argument2, etc...)

A function with no Return value or Arguments:

FunctionName()

All Return Values and Arguments are of a specified Data Type. It is strongly recommended that you use the specified Data Type, as the wrong one will either cause the script to fail, or possibly be misinterpreted.

List of Types and Return Values:

DLL Team Slots:

1 = TEAM_SLOT_RECYCLER
2 = TEAM_SLOT_FACTORY
3 = TEAM_SLOT_ARMORY
4 = TEAM_SLOT_TRAINING
5 = TEAM_SLOT_BOMBERBAY
6 = TEAM_SLOT_SERVICE
7 = TEAM_SLOT_TECHCENTER
8 = TEAM_SLOT_COMMTOWER
9 = TEAM_SLOT_BASE4 // Whatever's in base slot #4 (only w/ mods)
10 = TEAM_SLOT_BASE5 // Ditto
11 = TEAM_SLOT_BASE6 // Ditto
12 = TEAM_SLOT_BASE7 // Ditto
13 = TEAM_SLOT_BASE8 // Ditto
14 = TEAM_SLOT_BASE9 // Ditto

Color Strings:

"BLACK"
"DKGREY"
"GREY"
"WHITE"
"BLUE"
"DKBLUE"
"GREEN"
"DKGREEN"
"YELLOW"
"DKYELLOW"
"RED"
"DKRED"
"PURPLE"
"CYAN"
"ALLYBLUE"
"LAVACOLOR"

Audio Categories:

0 = UNKNOWN
1 = UNIT_DLG
2 = MISSION_DLG
3 = INTERFACE
4 = WEAPON
5 = ORDNANCE
6 = EXPLOSION
7 = ENGINE
8 = AMBIENT
9 = MUSIC

TeamColorType List:

0 = DEFAULT // Default
1 = GAMEPREFS // What's set in gameprefs
2 = SERVER // What the server sent us from their gameprefs.
3 = CURRENT // Valid only to GetFFATeamColor().

Team Relationship List:

0 = INVALIDHANDLE, // One or both handles is invalid
1 = SAMETEAM, // Team # for both items is the same
2 = ALLIEDTEAM, // Team # isn't identical, but teams are allied
3 = ENEMYTEAM, // Team # isn't identical, and teams are enemies

Network List Type:

0 = MPVehicles // item must be [0..31]
1 = StratStarting // item must be [0..31]
// For subsequent entries, the 'item' parameter varies by size of list. See GetNetworkListCount() for how to get the list size.
2 = Recyclers
3 = AIPs
4 = Animals
5 = STCTFGoals
6 = IAHumanRecyList
7 = IACPURecyclers
8 = IAAIPs

EntityType Return values:

"CLASS_ID_NONE" // undefined object (default)
"CLASS_ID_CRAFT" // hovering vehicle
"CLASS_ID_VEHICLE" // tracked vehicle
"CLASS_ID_TORPEDO" // miniature vehicle
"CLASS_ID_POWERUP" // power up pod
"CLASS_ID_PERSON" // pilot or soldier
"CLASS_ID_ANIMAL" // animal
"CLASS_ID_STRUCT" // generic building
"CLASS_ID_BUILDING" // important building
"CLASS_ID_SIGN" // mine object
"CLASS_ID_SCRAP" // scrap piece
"CLASS_ID_DEPOSIT" // scrap deposit
"CLASS_ID_BEACON" // nav beacon
"CLASS_ID_PLANT" // plant object
"CLASS_ID_TERRAIN" // terrain object
"CLASS_ID_WEAPON" // weapon object
"CLASS_ID_ORDNANCE" // ordnance object
"CLASS_ID_EXPLOSION" // explosion object
"CLASS_ID_CHUNK" // chunk object
"CLASS_ID_CRASH" // crash object
"CLASS_ID_COLLAPSE" // collapsing object

GOClass Return values:

"CLASS_AIR" // AirCraft.h
"CLASS_ANCHORROCKET" // AnchorRocketClass.h
"CLASS_APC" // APC.h
"CLASS_ARCCANNON" // ArcCannonClass.h
"CLASS_ARMORY" // Armory.h
"CLASS_ARTIFACT" // Artifact.h
"CLASS_ARTILLERY" // Artillery.h
"CLASS_ASSAULTTANK" // AssaultTank.h
"CLASS_ASSAULTHOVER" // AssaultHover.h
"CLASS_BARRACKS" // Barracks.h
"CLASS_BEAM"
"CLASS_BLINK" // BlinkDeviceClass.h
"CLASS_BOID"
"CLASS_BOMBER" // Bomber.h
"CLASS_BOMBERBAY" // BomberBay.h
"CLASS_BOUNCEBOMB"
"CLASS_BUILDING" // BuildingClass.h
"CLASS_BULLET" // BulletClass.h
"CLASS_CANNON" // CannonClass.h
"CLASS_CANNON_MACHINEGUN" // MachineGunClass.h
"CLASS_CANNON_TARGETING" // TargetingGunClass.h
"CLASS_CHARGEGUN" // ChargeGunClass.h
"CLASS_COMMBUNKER" // CommBunker.h
"CLASS_COMMTOWER" // CommTower.h
"CLASS_COMMVEHICLE" // CommVehicle.h
"CLASS_CONSTRUCTIONRIG" // ConstructionRig.h
"CLASS_CONSTRUCTIONRIGT" // ConstructionRigT.h
"CLASS_CRAFT" // CraftClass.h
"CLASS_DAMAGEFIELD" // DamageFieldClass.h
"CLASS_DAYWRECKER" // DayWrecker.h
"CLASS_DEPLOYABLE" // Deployable.h
"CLASS_DEPLOYBUILDING" // DeployBuilding.h
"CLASS_DEPLOYBUILDINGH" // DeployBuildingH.h
"CLASS_DEPOSIT" // Deposit.h
"CLASS_DISPENSER" // DispenserClass.h
"CLASS_EXPLOSION" // ExplosionClass.h
"CLASS_EXTRACTOR" // Extractor.h
"CLASS_FACTORY" // Factory.h
"CLASS_FLAG" // FlagObject.h
"CLASS_FLAREMINE" // FlareMineClass.h
"CLASS_GAMEOBJECT" // GameObjectClass.h
"CLASS_GRENADE" // GrenadeClass.h
"CLASS_GRENADE_LASERPOPPER" // LaserPopperClass.h
"CLASS_GRENADE_POPPER" // PopperClass.h
// "CLASS_GRENADE_RADARPOPPER" // RadarPopperClass.h [Same sig as GRENADE_POPPER, uses that]
"CLASS_HOVER" // HoverCraft.h
"CLASS_HOWITZER" // Howitzer.h
"CLASS_I76BUILDING" // Building.h
"CLASS_JAMMER" // JammerTower.h
"CLASS_JETPACK" // JetPackClass.h
"CLASS_KINGOFHILL" // KingOfHill.h
"CLASS_LAUNCHER" // LauncherClass.h
"CLASS_LAUNCHER_IMAGE" // ImageLauncherClass.h
"CLASS_LAUNCHER_MULTI" // MultiLauncherClass.h
"CLASS_LAUNCHER_RADAR" // RadarLauncherClass.h
"CLASS_LAUNCHER_THERMAL" // ThermalLauncherClass.h
"CLASS_LAUNCHER_TORPEDO" // TorpedoLauncherClass.h
// "CLASS_LEADER_ROUND" // LeaderRoundClass.h [Same sig as CLASS_CANNON_TARGETING, returns that]
"CLASS_LOCKSHELL" // LockShellClass.h
"CLASS_MAGNETGUN" // MagnetGunClass.h
"CLASS_MAGNETSHELL" // MagnetShellClass.h
"CLASS_MINE" // MineClass.h
"CLASS_MINELAYER" // Minelayer.h
"CLASS_MINE_MAGNET" // MagnetMineClass.h
"CLASS_MINE_PROXIMITY" // ProximityMineClass.h
"CLASS_MINE_TRIP" // TripMineClass.h
"CLASS_MINE_WEAPON" // WeaponMineClass.h
"CLASS_MISSILE" // MissileClass.h
"CLASS_MISSILE_IMAGE" // ImageMissileClass.h
"CLASS_MISSILE_LASER" // LaserMissileClass.h
"CLASS_MISSILE_RADAR" // RadarMissileClass.h
"CLASS_MISSILE_THERMAL" // ThermalMissileClass.h
"CLASS_MORPHTANK" // MorphTank.h
"CLASS_MORTAR" // MortarClass.h
"CLASS_MORTAR_REMOTE" // RemoteDetonatorClass.h
"CLASS_MOTIONSENSOR" // MotionSensor.h
"CLASS_NAVBEACON" // NavBeaconClass.h
"CLASS_OBJECTSPAWN" // ObjectSpawn.h
"CLASS_ORDNANCE" // OrdnanceClass.h
"CLASS_PERSON" // PersonClass.h
"CLASS_PLANT" // Plant.h // Power plants, not foliage plants. -GBD
"CLASS_POWERED" // PoweredBuilding.h
"CLASS_POWERUP_CAMERA" // CameraPod.h
"CLASS_POWERUP_MONEY" // MoneyPowerup.h
"CLASS_POWERUP_RELOAD" // ServicePowerup.h
"CLASS_POWERUP_REPAIR" // ServicePowerup.h
"CLASS_POWERUP_SERVICE" // ServicePowerup.h
// "CLASS_POWERUP_WEAPON" // WeaponPowerup.h [Same sig as CLASS_WEAPON, returns that]
"CLASS_PULSESHELL" // PulseShellClass.h
"CLASS_RECYCLER" // Recycler.h
"CLASS_RECYCLERVEHICLE" // RecyclerVehicle.h
"CLASS_RECYCLERVEHICLEH" // RecyclerVehicleH.h
"CLASS_SALVOLAUNCHER" // SalvoLauncherClass.h
"CLASS_SATCHELCHARGE" // SatchelCharge.h
"CLASS_SATCHELPACK" // SatchelPackClass.h
"CLASS_SAV" // SAV.h
"CLASS_SCAVENGER" // Scavenger.h
"CLASS_SCAVENGERH" // ScavengerH.h
"CLASS_SCRAP" // Scrap.h
"CLASS_SEEKER" // SeekerClass.h
"CLASS_SEISMICWAVE" // SeismicWaveClass.h
"CLASS_SERVICE" // ServiceTruck.h
"CLASS_SERVICEH" // ServiceTruckH.h
"CLASS_SHIELDTOWER" // ShieldTower.h
"CLASS_SHIELDUP" // ShieldUpgradeClass.h
"CLASS_SIGN" // BuildingClass.h
"CLASS_SILO" // Silo.h
"CLASS_SNIPERSHELL" // SniperShellClass.h
"CLASS_SPAWNBUOY" // SpawnBuoy.h
"CLASS_SPECIAL" // SpecialItemClass.h
"CLASS_SPECIAL_FORCEFIELD" // ForceFieldClass.h
"CLASS_SPECIAL_IMAGEREFRACT" // ImageRefractClass.h
"CLASS_SPECIAL_RADARDAMPER" // RadarDamperClass.h
"CLASS_SPECIAL_TERRAINEXPOSE" // TerrainExposeClass.h
"CLASS_SPRAYBOMB" // SprayBombClass.h
"CLASS_SPRAYBUILDING" // SprayBuildingClass.h
"CLASS_SUPPLYDEPOT" // SupplyDepot.h
"CLASS_TELEPORTAL" // TelePortalClass.h
"CLASS_TERRAIN" // DummyClass.h
"CLASS_TORPEDO" // TorpedoClass.h
"CLASS_TRACKEDDEPLOYABLE" // TrackedDeployable.h
"CLASS_TRACKEDVEHICLE" // TrackedVehicle.h
"CLASS_TUG" // Tug.h
"CLASS_TURRET" // TurretCraft.h - ibgtow/fbspir (Guntower/gunspires)
"CLASS_TURRETTANK" // TurretTank.h - ivturr/fvturr (vehicle turrets)
"CLASS_WALKER" // Walker.h
"CLASS_WEAPON" // WeaponClass.h
"CLASS_WINGMAN" // Wingman.h
"CLASS_UNKNOWN" // default

Taunt Types:

0 = GameStart
1 = NewHuman
2 = LeftHuman
3 = HumanShipDestroyed
4 = HumanRecyDestroyed
5 = CPURecyDestroyed
6 = Random
7 = Category7 // Custom taunts headers, not used yet, but code supports up to 16 Headers in Taunts.odf.
8 = Category8
9 = Category9
10 = Category10
11 = Category11
12 = Category12
13 = Category13
14 = Category14
15 = Category15

Lua Table List

List of values in the Table. These Tables can be accessed by TableName.VariableName or TableName["VariableName"]. The numerical values can be used instead, and are represented in the table list alongside the table values. These tables are for people who prefer human-readable code formats.

IdentityMatrix

Default Matrix. North Facing with a position of 0, 0, 0.

AiCommand

AI Command Table. Values:

• 0: CMD_NONE
  
• 1: CMD_SELECT
  
• 2: CMD_STOP
  
• 3: CMD_GO
  
• 4: CMD_ATTACK
  
• 5: CMD_FOLLOW
  
• 6: CMD_FORMATION
  
• 7: CMD_PICKUP
  
• 8: CMD_DROPOFF
  
• 9: CMD_UNDEPLOY
  
• 10: CMD_DEPLOY
  
• 11: CMD_NO_DEPLOY
  
• 12: CMD_GET_REPAIR
  
• 13: CMD_GET_RELOAD
  
• 14: CMD_GET_WEAPON
  
• 15: CMD_GET_CAMERA
  
• 16: CMD_GET_BOMB
  
• 17: CMD_DEFEND
  
• 18: CMD_RESCUE
  
• 19: CMD_RECYCLE
  
• 20: CMD_SCAVENGE
  
• 21: CMD_HUNT
  
• 22: CMD_BUILD
  
• 23: CMD_PATROL
  
• 24: CMD_STAGE
  
• 25: CMD_SEND
  
• 26: CMD_GET_IN
  
• 27: CMD_LAY_MINES
  
• 28: CMD_LOOK_AT
  
• 29: CMD_SERVICE
  
• 30: CMD_UPGRADE
  
• 31: CMD_DEMOLISH
  
• 32: CMD_POWER
  
• 33: CMD_BACK
  
• 34: CMD_DONE
  
• 35: CMD_CANCEL
  
• 36: CMD_SET_GROUP
  
• 37: CMD_SET_TEAM
  
• 38: CMD_SEND_GROUP
  
• 39: CMD_TARGET
  
• 40: CMD_INSPECT
  
• 41: CMD_SWITCHTEAM
  
• 42: CMD_INTERFACE
  
• 43: CMD_LOGOFF
  
• 44: CMD_AUTOPILOT
  
• 45: CMD_MESSAGE
  
• 46: CMD_CLOSE
  
• 47: CMD_MORPH_SETDEPLOYED
  
• 48: CMD_MORPH_SETUNDEPLOYED
  
• 49: CMD_MORPH_UNLOCK
  
• 50: CMD_BAILOUT
  
• 51: CMD_BUILD_ROTATE
  
• 52: CMD_CMDPANEL_SELECT
  
• 53: CMD_CMDPANEL_DESELECT

TauntTypes

Taunt Type Categories

• 0: TAUNTS_GameStart
  
• 1: TAUNTS_NewHuman
  
• 2: TAUNTS_LeftHuman
  
• 3: TAUNTS_HumanShipDestroyed
  
• 4: TAUNTS_HumanRecyDestroyed
  
• 5: TAUNTS_CPURecyDestroyed
  
• 6: TAUNTS_Random
  
• 7: TAUNTS_Category7
  
• 8: TAUNTS_Category8
  
• 9: TAUNTS_Category9
  
• 10: TAUNTS_Category10
  
• 11: TAUNTS_Category11
  
• 12: TAUNTS_Category12
  
• 13: TAUNTS_Category13
  
• 14: TAUNTS_Category14
  
• 15: TAUNTS_Category15

DMSubGameTypes

Deathmatch Sub Game Types. Values returned by ivar7.

• 0: DMSubtype_Normal
  
• 1: DMSubtype_KOH
  
• 2: DMSubtype_CTF
  
• 3: DMSubtype_Loot
  
• 4: DMSubtype_RESERVED1
  
• 5: DMSubtype_Race1
  
• 6: DMSubtype_Race2
  
• 7: DMSubtype_Normal2

PreSnipeReturnValues

Values returned by the PreSnipe function.

• 0: PRESNIPE_KILLPILOT
  
• 1: PRESNIPE_ONLYBULLETHIT

PreGetInReturnValues

Values returned by the PreGetIn function.

• 0: PREGETIN_DENY
  
• 1: PREGETIN_ALLOW

PrePickupPowerupReturnValues

Values returned by the PrePickupPowerup function.

• 0: PREPICKUPPOWERUP_DENY
  
• 1: PREPICKUPPOWERUP_ALLOW

RandomizeTypes

Randomize Vehicle Types.

• 0: Randomize_None
  
• 1: Randomize_ByRace
  
• 2: Randomize_Any

TeamRelationshipTypes

Team Relationship Types. Comparable against the GetTeamRelationship function.

• 0: TEAMRELATIONSHIP_INVALIDHANDLE
  
• 1: TEAMRELATIONSHIP_SAMETEAM
  
• 2: TEAMRELATIONSHIP_ALLIEDTEAM
  
• 3: TEAMRELATIONSHIP_ENEMYTEAM

EjectKillRetCodes

Object Ejected/Killed/Sniped return codes. Used in PlayerEjected, ObjectKilled, and ObjectSniped.

• 0: EJECTKILLRETCODES_DOEJECTPILOT
  
• 1: EJECTKILLRETCODES_DORESPAWNSAFEST
  
• 2: EJECTKILLRETCODES_DLLHANDLED
  
• 3: EJECTKILLRETCODES_DOGAMEOVER

Note: as of version 2.0.185 this table strings won't work. Needs to be manually returned via number variables.

Event Hook Functions

The game has several functions that it calls upon certain events. These are optional, and are called by the Game itself, so you don't have to call them yourself. (and doing so would be a bad idea)

function InitialSetup()
...
end

Initial Setup is called first, often before some things are even loaded.

function Start()
...
end

This function is called in the first of the mission script Execute run. It's a good place to setup things, as certain things may not work in InitialSetup yet.

function Load()
...
end

Load is called when you load a game, or when a Resync is loaded.

function Save()
...
end

Save is called when you save a game, or when a Resync is requested.

function AddObject( Handle h )
...
end

This function is called every time a GameObject Class is added to the world. This includes a pass over all pre-placed objects on the map .bzn at the start of the game.
Argument List:

• Handle h: This is the Handle ID of the object being added.

Note: For Battlezone 98 Redux backwards compatibility, this function can also be called "CreateObject".
Note: The function only runs on pre-placed objects on the first map load, not loading from a Saved Game.
Note: Any calls to BuildObject() will immediately trigger this function.
Note: If you call RemoveObject(h) on the added handle within this function, exit the function early, as any other function calls to h will return nil / invalid data.

function DeleteObject( Handle h )
...
end

This function is called every time a GameObject Class is removed from the world.
Argument List:

• Handle h: This is the Handle ID of the object being removed.

Note: This is called after the object is largely removed from the game, so most Get functions won't return a valid value.
Note: Any calls to RemoveObject() will immediately trigger this function.

function AddPlayer( int ID, int Team, bool IsNewPlayer )
...
end

This function is called when a Player Joins the game.
Argument List:

• int ID: This is the DPID number for this player.
  
• int Team: This is the Team number for this player.
  
• bool IsNewPlayer: This bool tells if it is a new player or not.

function DeletePlayer( int ID )
...
end

This function is called when a Player Leaves the game.
Argument List:

• int ID: This is the DPID number for this player.

int PlayerEjected ( Handle DeadObjectHandle )
...
end

This function is called when a Player Ejects.
Argument List:

• Handle DeadObjectHandle: This is the Handle ID for the now Dead object that was ejected out of.

Note: Must return a valid value from EjectKillRetCodes table.
Note: For this to function on Non Player craft, WantBotKillMessages() must be enabled.

int ObjectKilled( Handle DeadObjectHandle, Handle KillersHandle )
...
end

This function is called when a GameObject is Killed by another object.
Argument List:

• Handle DeadObjectHandle: This is the Handle ID for the now Dead object that was just blown up.
  
• Handle KillersHandle: This is the Handle ID for the object that killed this object, if present.

Note: Must return a valid value from EjectKillRetCodes table.
Note: For this to function on Non Player craft, WantBotKillMessages() must be enabled.

int ObjectSniped( Handle DeadObjectHandle, Handle KillersHandle )
...
end

This function is called when a GameObject is Sniped by another object.
Argument List:

• Handle DeadObjectHandle: This is the Handle ID for the now Dead object that was just sniped.
  
• Handle KillersHandle: This is the Handle ID for the object that killed this object, if present.

Note: Must return a valid value from EjectKillRetCodes table.
Note: For this to function on Non Player craft, WantBotKillMessages() must be enabled.

function Update()
...
end

This is the primary function that runs every game turn. This is where most mission logic will run.
Note: In C++ side, this is called Execute().

function PreOrdnanceHit( Handle ShooterHandle, Handle VictimHandle, int OrdnanceTeam, string OrdnanceODF )
...
end

This function is called when an Ordnance hits an Object.
Argument List:

• Handle ShooterHandle: This is the Handle ID of the Shooter.
  
• Handle VictimHandle: This is the Handle ID of the object hit.
  
• int OrdnanceTeam: This is the Team number of the Ordnance, if applicable.
  
• string OrdnanceODF: This is the .ODF file of the Ordnance that hit the VictimHandle.

int PreGetIn( int CurWorld, Handle PilotHandle, Handle EmptyCraftHandle )
...
end

This function is called when a Pilot attempts to enter an Empty craft.
Argument List:

• int CurWorld: The current MP World. If you do anything that effects the world, ensure curWorld is 0 to avoid MP Resyncs.
  
• Handle PilotHandle: Handle ID of the Pilot.
  
• Handle EmptyCraftHandle: Handle ID of the Empty craft.

Note: Must return a valid value from PreGetInReturnCodes table.

int PreSnipe( int CurWorld, Handle ShooterHandle, Handle VictimHandle, int OrdnanceTeam, string OrdnanceODF )
...
end

This function is called when a SniperShell Ordnance hits an Object and would successfully trigger a Snipe.
Argument List:

• int CurWorld: The current MP World. If you do anything that effects the world, ensure curWorld is 0 to avoid MP Resyncs.
  
• Handle ShooterHandle: This is the Handle ID of the Shooter.
  
• Handle VictimHandle: This is the Handle ID of the object hit.
  
• int OrdnanceTeam: This is the Team number of the Ordnance, if applicable.
  
• string OrdnanceODF: This is the .ODF file of the Ordnance that hit the VictimHandle.

Note: Must return a valid value from PreSnipeReturnCodes table.

int PrePickupPowerup( int CurWorld, Handle Me, Handle PowerUpHandle )
...
end

This function is called when a Powerup is attempted to be Picked Up.
Argument List:

• int CurWorld: The current MP World. If you do anything that effects the world, ensure curWorld is 0 to avoid MP Resyncs.
  
• Handle Me: This is the Handle ID of the object picking up the Powerup.
  
• Handle PowerUpHandle: This is the Handle ID of the powerup object.

Note: Must return a valid value from PrePickupPowerupReturnCodes table.

function PostTargetChangedCallback( Handle Craft, Handle PreviousTarget, Handle CurrentTarget )
...
end

This function is called when an object changes Targets.
Argument List:

• Handle Craft: The object that just changed Targets.
  
• Handle PreviousTarget: This is the Handle ID of the previous Target.
  
• Handle CurrentTarget: This is the Handle ID of the new Target.

function PostRun()
...
end

This function is called at the End of the mission, shortly before game returns to the Shell UI.

string GetNextRandomVehicleODF(int Team)
...
end

This function returns the specified team's next respawn ODF.
Argument List:

• int Team: This is the Team number specified for filtering.

function ProcessCommand( int CRC )
...
end

Processes a Command as an input from the user.
Argument List:

• int CRC: This is the CRC of the Command to process.

function SetRandomSeed( int Seed )
...
end

Sets the Random Seed generator to a specific value.
Argument List:

• int Seed: This is the random seed to use.

Math Functions

BZCC uses a Left handed system in it's math and coordinate functions.
Vector/Matrix math functions usually perform the math on each component individually.

number GetRandomFloat(number Max)
number GetRandomFloat(number Min, number Max)

Returns a random number between Min and Max range. If Min is not specified, it uses a Min of 0.
Note: Do NOT use math.random, use this function instead.

number FrontToRadian(Vector V)

Converts a Front Vector into an angle in Radians along the horizontal plane. Returns a value between -pi and pi. North is 0.

number FrontToDegrees(Vector V)

Converts a Front Vector into an angle in Degrees along the horizontal plane. Returns a value between -180 and 180. North is 0.

Vector GetFacingDirection(Vector A, Vector B)

Returns a Front Vector from Position A facing Position B.

Vector GetFacingDirection2D(Vector A, Vector B)

Returns a Front Vector from Position A facing Position B, on the horizontal plane.

Vector:
Vector support the following data / math functions:

vector.x
vector.y
vector.z
-vector
vector + vector
vector - vector
number * vector
vector * number
vector * vector
number / vector
vector / number
vector / vector
vector == vector
vector ~= vector

Vector SetVector(number X, number Y, number Z)

Returns a Vector with the specified Contents.

bool IsNullVector(Vector V)

Returns true if the Vector is extremely close to 0 0 0.

number DotProduct(Vector A, Vector B)

Returns the dot product of the two Vectors.
Equivalent to a.x * b.x + a.y * b.y + a.z * b.z.

Vector CrossProduct(Vector A, Vector B)

Returns the Cross Product of the two Vectors.
Equivalent to SetVector(a.y * b.z - a.z * b.y, a.z * b.x - a.x * b.z, a.x * b.y - a.y * b.x).

Vector Normalize(Vector V)

Returns the vector scaled to unit length.
Equivalent to SetVector(v.x * scale, v.y * scale, v.z * scale) where scale is 1.0f / sqrt(v.x2 + v.y2 + v.z2).

Vector Vector_Transform(Matrix M, Vector V)
Vector Vector_Transform(Matrix M, number Pos_x, number Pos_y, number Pos_z)

Rotates the Vector then adds the Matrix's position.

Vector Vector_TransformInv(Matrix M, Vector V)
Vector Vector_TransformInv(Matrix M, number Pos_x, number Pos_y, number Pos_z)

Inverse rotates the Vector then subtracts the Matrix's position.

Vector Vector_Rotate(Matrix M, Vector V)
Vector Vector_Rotate(Matrix M, number Pos_x, number Pos_y, number Pos_z)

Rotates a Vector by a Matrix.

Vector Vector_RotateInv(Matrix M, Vector V)
Vector Vector_RotateInv(Matrix M, number Pos_x, number Pos_y, number Pos_z)

Inverse rotates a Vector by a Matrix.

Vector Add_Mult_Vectors(Vector A, Vector B, number Mult)

Adds, and Multiplies the Vectors.
Equivalent to SetVector(v1.x + v2.x * Mult, v1.y + v2.y * Mult, v1.z + v2.z * Mult).

number Length(Vector V)

Returns the length of the vector.
Equivalent to sqrt(v.x2 + v.y2 + v.z2).

number LengthSquared(Vector V)

Returns the squared length of the vector.
Equivalent to v.x2 + v.y2 + v.z2.

number Distance2D(Vector A, Vector B)

Returns the 2D distance between vectors a and b.
Equivalent to sqrt((b.x - a.x)2 + (b.z - a.z)2).

number Distance2DSquared(Vector A, Vector B)

Returns the squared 2D distance of the vector.
Equivalent to (b.x - a.x)2 + (b.z - a.z)2.

number Distance3D(Vector A, Vector B)
number Distance3D(Handle A, Handle B)

Returns the 3D distance between vectors/Handles a and b.
Equivalent to sqrt((b.x - a.x)2 + (b.y - a.y)2 + (b.z - a.z)2).

number Distance3DSquared(Vector A, Vector B)
number Distance3DSquared(Handle A, Handle B)

Returns the squared 3D distance of the vector.
Equivalent to (b.x - a.x)2 + (b.y - a.y)2 + (b.z - a.z)2.


Matrix:
Matrix support the following data / math functions:
matrix.right
matrix.right_x
matrix.right_y
matrix.right_z
matrix.up
matrix.up_x
matrix.up_y
matrix.up_z
matrix.front
matrix.front_x
matrix.front_y
matrix.front_z
matrix.posit
matrix.posit_x
matrix.posit_y
matrix.posit_z
matrix * matrix
matrix * vector

Matrix IdentityMatrix

Global value representing the identity matrix.
Equivalent to SetMatrix(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0).

Matrix SetMatrix(Vector right, Vector up, Vector front, Vector Position)
Matrix SetMatrix(number right_x, nubmer right_y, number right_z, number up_x, number up_y, number up_z, number front_x, number front_y, number front_z, number posit_x, number posit_y, number posit_z)

Returns a Matrix with the specified Contents.

Matrix BuildAxisRotationMatrix(number Angle, Vector Position)
Matrix BuildAxisRotationMatrix(number Angle, number axis_x, number axis_y, number axis_z)

Build a matrix representing a rotation by an angle around an axis. The angle is in radians. If no value is given for the angle or an axis component, the default value is zero. The axis must be unit-length (i.e. axis_x2 + axis_y2 + axis_z2 = 1.0 or the resulting matrix will be wrong.

Matrix BuildPositionRotationMatrix(number Pitch, number Yaw, number Roll, Vector Pos)
Matrix BuildPositionRotationMatrix(number Pitch, number Yaw, number Roll, number Pos_X, number Pos_y, number Pos_z)

Build a matrix with the given pitch, yaw, and roll angles and position. The angles are in radians. If no value is given for a component, the default value is zero.

Matrix BuildOrthogonalMatrix(Vector Axis, Vector Heading)

Build a matrix with zero position, its up axis along the specified up vector, oriented so that its front axis points as close as possible to the heading vector. If up is not specified, the default value is the Y axis. If heading is not specified, the default value is the Z axis.

Matrix BuildDirectionalMatrix(Vector Position, Vector Direction)

Build a matrix with the given position vector, its front axis pointing along the direction vector, and zero roll. If position is not specified, the default value is a zero vector. If direction is not specified, the default value is the Z axis.

Matrix Build_Yaw_Matrix(number Angle, Vector Position)
Matrix Build_Yaw_Matrix(number Angle, number Pos_x, number Pos_y, number Pos_z)

Build a matrix with only yaw (Y axis) rotation. The angle is in radians. If no value is given for the angle or an axis component, the default value is zero. The axis must be unit-length (i.e. axis_x2 + axis_y2 + axis_z2 = 1.0 or the resulting matrix will be wrong.

Matrix Interpolate_Matrix(Matrix A, Matrix B, number T)

Interpolate a matrix from two matrices.

Matrix Matrix_Inverse(Matrix M)

Returns the inverse of the Matrix.


Quaternion:
Vector support the following data / math functions:
quaternion.s
quaternion.x
quaternion.y
quaternion.z
quaternion * quaternion

Quaternion SetQuaternion(number s, number x, number y, number z)

Returns a Quaternion with the specified Contents.

Quaternion Interpolate_Quaternion(Quaternion q1, Quaternion q2, number T)

Interpolate a Quaternion from two Quaternions.

Quaternion Normalize_Quaternion(Quaternion q)

Returns the Quaternion scaled to unit length.

Quaternion Q, Vector Pos Matrix_to_QuatPos(Matrix M)

Given a Matrix, returns the Quaternion and Position equivalent.

Quaternion Matrix_to_Quaternion(Matrix M)

Given a Matrix, returns the Quaternion equivalent.

Matrix QuatPos_to_Matrix(Quaternion Q, Vector Pos)
Matrix QuatPos_to_Matrix(Quaternion Q, number Pos_x, number Pos_y, number Pos_z)

Given a Quaternion and Position, returns the Matrix equivalent.

AI Orders

For all of these, the Priority is either 0, or 1.
Setting priority to 0 leaves the unit under the Player's control, and the Unit VO dialog will play as if the Player ordered the unit via the Command Menu.
Setting priority to 1 takes the unit out of the Player's F Slots and squelches Unit VO dialog from the unit while it's not under the Player's control.

Attack(Handle me, Handle him, int Priority = 1)

Orders Handle me to Attack Handle him.

Service(Handle me, Handle him, int Priority = 1)

Orders Handle me to Service Handle him.

Goto(Handle me, Handle him, int Priority = 1)
Goto(Handle me, Matrix Pos, int Priority = 1)
Goto(Handle me, Vector Pos, int Priority = 1)
Goto(Handle me, string Path, int Point = 0, int Priority = 1)

Orders Handle me to Goto the specified location.

Mine(Handle me, Handle him, int Priority = 1)
Mine(Handle me, Matrix Pos, int Priority = 1)
Mine(Handle me, Vector Pos, int Priority = 1)
Mine(Handle me, string Path, int Point = 0, int Priority = 1)

Orders Handle me to Mine the specified location.

Follow(Handle me, Handle him, int Priority = 1)

Orders Handle me to Follow Handle him.

Defend(Handle me, int Priority = 1)

Orders Handle me to Defend it's current location. Equivalent to Hold in the Command Menu,

Defend2(Handle me, Handle him, int Priority = 1)

Orders Handle me to Defend Handle him.

Stop(Handle me, int Priority = 1)

Orders Handle me to Stop.

Patrol(Handle me, string Path, int Proprity = 1)

Orders Handle me to Patrol the specified Path.

Retreat(Handle me, Handle him, int Priority = 1)
Retreat(Handle me, Matrix Pos, int Priority = 1)
Retreat(Handle me, Vector Pos, int Priority = 1)
Retreat(Handle me, string Path, int Point = 0, int Priority = 1)

Orders Handle me to Retreat to the specified Location.
Note: This also sets the Independence of the unit to 0, so it doesn't Attack or do anything else while Retreating.

GetIn(Handle me, Handle him, int Priority = 1)

Orders Handle me to Get In Handle him.

Pickup(Handle me, Handle him, int Priority = 1)

Orders Handle me to Pickup Handle him.

Dropoff(Handle me, Handle him, int Priority = 1)
Dropoff(Handle me, Matrix Pos, int Priority = 1)
Dropoff(Handle me, Vector Pos, int Priority = 1)
Dropoff(Handle me, string Path, int Point = 0, int Priority = 1)

Orders Handle me to Dropoff at the specified Position.

Build(Handle me, string ODF, int Priority = 1)

Orders Handle me to Que the specified ODF for Building.
Note: Construction Rigs/Armories need a Dropoff command, and Recycler/Factory need CMD_DONE in the next call to Update to start construction.

LookAt(Handle me, Handle him, int Priority = 1)

Orders Handle me to Look At Handle him.

AllLookAt(int Team, Handle him, int Priority = 1)

Orders all Craft on the specified Team to Look At Handle him.

FireAt(Handle me, Handle him = 0, bool doAim = false)

Orders me to fire at him. Updates the selected weapons to the current weaponMask setting. Sets me's current Target to him. if doAim is true, and it's a craft/person it ties to AimAt him.

SetCommand(Handle h, int Command, int Priority = 1, Handle Who = 0, Vector Where, int/string Param)
SetCommand(Handle h, int Command, int Priority = 1, Handle Who = 0, Matrix Where, int/string Param)
SetCommand(Handle h, int Command, int Priority = 1, Handle Who = 0, Handle Where, int/string Param)
SetCommand(Handle h, int Command, int Priority = 1, Handle Who = 0, string Path, int/string Param)

Sets the Current Command on the specified Handle.
See ODF Documentation Guide for a list of AI Commands.
Some parameters are only used on specific Commands.
Parameter can be a CRC of a string, or a direct String, and is used as the ODF specified to Build.

int GetCurrentCommand(Handle h)

Returns the specified Handle's current Command.

Handle GetCurrentWho(Handle h)

Returns the specified Handle's current Command's current Who.

Vector GetCurrentCommandWhere(Handle h)

Returns the specified Handle's current Command's current Where Vector.

Audio Functions

int AudioMessage(string filename.wav)

Plays an Audio file on the local machine. Must specify file extension, either .wav or .ogg.
Returns the an integer ID of the Message.
Note: This ques the message for Play with other messages, so other messages played with the same function, including Unit VO Dialog, will finish before it plays this sound.

bool IsAudioMessageDone(int AudioID)

Returns true if the specified AudioMessage() has finished Playing.

StopAudioMessage(int AudioID)

Stops the specified AudioMessage() file.

PreloadAudioMessage(string filename.wav)

Preloads the specified Audio file. Useful for long files such as .ogg files.

PurgeAudioMessage(string filename.wav)

Stops all instances of the specified Audio file.

PreloadMusicMessage(string filename.wav)

Preloads a Music Audio Message.

PurgeMusicMessage(string filename.wav)

Depreciated. Use PurgeAudioMessage() instead.

LoadJukeFile(string GroupName)

Loads a Juke Box the specified GroupName Header from "music.odf".
Note: The Stock music.odf only contains group "mire".

SetMusicIntensity(int Intensity)

Sets the music Intensity. Valid values are 1-3.

int StartSoundEffect(string Filename, Handle h = 0)

Starts the specified Sound Effect, optionally attached to the specified Handle. Uses Audio Category MISSION_DIALOG.
Returns the AudioHandle.

int FindSoundEffect(string Filename, Handle h = 0)

Returns the AudioHandle of the specified Sound, optionally attached to the specified Handle. If Handle is 0 it returns the oldest instance of the sound file.

StopSoundEffect(int AudioHandle)

Stops the oldest instance of the specified AudioHandle.
Note: Not compatible with AudioMessage() return values.

AudioHandle StartAudio3D(string filename, Vector Pos, int AudioCategory = 0, bool Loop = false)
AudioHandle StartAudio3D(string filename, Matrix Pos, int AudioCategory = 0, bool Loop = false)
AudioHandle StartAudio3D(string filename, number X, number Y, number Z, int AudioCategory = 0, bool Loop = false)
AudioHandle StartAudio3D(string filename, Handle h, int AudioCategory = 0, bool Loop = false, bool StopLast = false)

Starts a 3D Sound at the specified Location, or attached to the specified Handle. Valid AudioCategories are listed in the DLL Audio Category List.
if Stoplast is true, it kills any previous sound on the Handle that has the same filename.

AudioHandle StartAudio2D(string filename, number Volume, number Pan, number Rate, bool Loop = false, bool IsMusic = false)

Starts a 2D Sound, at the specified Volume, Pan, and Rate.
Volume has a range of 0.0 - 1.0. If Volume is -1, it uses the Sound Option's Shell FX Volume setting. If IsMusic is true, it uses the Music Volume setting.
Pan has a range of -1.0 - 1.0 from Left to Right.
Rate has a range of 0.0 - 44100.0.

bool IsAudioPlaying(int AudioHandle)

Returns true if the specified AudioHandle is playing.
Note: Not compatible with the return from AudioMessage().

StopAudio(int AudioHandle)

Stops the specified AudioHandle.

PauseAudio(int AudioHandle)

Pauses the specified AudioHandle.

ResumeAudio(int AudioHandle)

Resumes the specified AudioHandle.

SetVolume(int AudioHandle, number Volume, bool AdjustByVolumes = true)

Sets the Volume of the specified AudioHandle. Valid range is 0.0 - 1.0. This will be scaled by User's Volume Preferences if AdjustByVolumes is true.

SetPan(int AudioHandle, number Pan)

Sets the Pan of the specified AudioHandle. Valid range is -1.0 - 1.0.
Note: Only valid for 2D sounds.

SetRate(int AudioHandle, number Rate)

Sets the Rate of the specified AudioHandle. Valid range is 0.0 - 44100.0.

number GetAudioFileDuration(int AudioHandle)

Returns the length in seconds of AudioHandle's audio file.
Note: Not compatible with the return from AudioMessage().

bool IsPlayingLooped(int AudioHandle)

Returns true if the specified AudioHandle is playing in Loop mode.

Team Functions

Handle GetPlayerHandle()
Handle GetPlayerHandle(int Team)

Returns the Player's Handle of the specified Team. If the Team is not specified, returns the Local user's Player Handle.
Note: In MP, always use the version that takes a Team parameter.

SetAsUser(Handle h, int Team)

Sets the specified Handle as the Player on the specified Team.

char GetRaceOfTeam(int Team)

Returns the race letter for the specified Team. If TeamPlay is on, it returns the Race of the Commander's Team.

int AddScrap(int Team, int Value)

Adds the Value to the specified Team's Current Scrap.
Returns the new Current Scrap value.

int SetScrap(int Team, int Value)

Sets the specified Team's Current Scrap to the Value.
Returns the new Current Scrap value.

AddMaxScrap(int Team, int Value)

Adds the Value to the Team's Max Scrap.

SetMaxScrap(int Team, int Value)

Sets the specified Team's Max Scrap to the Value.

int GetScrap(int Team)

Returns the specified Team's Current Scrap value.

int GetMaxScrap(int Team)

Returns the specified Team's Current Max Scrap value.

int AddPower(int Team, int Value)

Adds the Value to the Team's Current Power.
Returns the new Current Power value.

int SetPower(int Team, int Value)

Sets the specified Team's Current Power to the Value.
Returns the new Current Power value.

int GetPower(int Team)

Returns the specified Team's Current Power value.

int GetMaxPower(int Team)

Returns the specified Team's Current Max Power value.

AddMaxPower(int Team, int Value)

Adds the Value to the Team's Max Power.

SetMaxPower(int Team, int Value)

Sets the specified Team's Max Power to the Value.

int GetFirstEmptyGroup()
int GetFirstEmptyGroup(int Team)

Returns the first empty Group index of the specified Team. If the Team is not specified, it uses the Local user's Team.
Note: For MP scripts, always use the version with a Team passed in.

DefaultAllies()

Sets the TeamPlay Alliances to Default.
Everyone is on their own Team.

TeamplayAllies()

Sets the TeamPlay Alliances to Team play.
Teams 1 - 5 are Allied, and Teams 6-10 are Allied.

Ally(Team a, Team b)

Allies Team a with Team b.

UnAlly(Team a, Team b)

Unallies Team a with Team b.

bool IsTeamAllied(Team a, Team b)

Returns true if Team A is an Ally of Team B.

bool IsAlly(Handle a, Handle b)

Returns true if Handle A is an Ally of Handle B.

string GetPlan(int Team)

Returns the current AI Plan file on the specified Team.
Note: For backwards compatibility with BZ98Redux, this function can also be called "GetAIP"

SetAIP(string filename.aip, int Team = 2)

Sets the specified AI Plan file for the specified Team. If Team is not specified, Team 2 is used.

ClearTeamColors()

Clears the Team Color settings.

DefaultTeamColors()

Sets the Team Colors to Default FFA/DM colors.

TeamplayTeamColors()

Sets the Team Colors to Default ST/MPI TeamPlay colors.

SetTeamColor(int Team, Vector Color)
SetTeamColor(int Team, int Red, int Green, int Blue)

Sets the Team Color for the specified Team, either in a Vector of R G B values, or individual RGB values.

ClearTeamColor(int Team)

Clears the Team Colors for the specified Team.

SetFFATeamColors(int TeamColorType)

Sets the Local User to use the specified TeamColorType for FFA mode.

SetTeamStratColors(int TeamColorType)

Sets the Local User to use the specified TeamColorType for TeamPlay mode.

int R, int G, int B GetFFATeamColor(int TeamColorType, int Team)

Returns the specified Team's FFA TeamColor settings for the specified TeamColorType as R G B ints.

Vector GetFFATeamColorVector(int TeamColorType, int Team)

Returns the specified Team's FFA TeamColor settings for the specified TeamColorType as a Vector of R G B ints.

int R, int G, int B GetTeamStratColor(int TeamColorType, int TeamGroup)

Returns the specified Team Group's TeamPlay TeamColor settings for the specified TeamColorType as R G B ints.
Note: TeamGroup is 0...1, or WhichTeamGroup(team).

Vector GetTeamStratColorVector(int TeamColorType, int Team)

Returns the specified Team's TeamPlay TeamColor settings for the specified TeamColorType as a Vector of R G B ints.

SwapTeamStratColors()

Swaps the current TeamPlay colors for the two Team Groups.

bool GetTeamColorsAreFFA()

Returns true if the last TeamColors set were FFA. The following functions change this return:
TeamplayTeamColors(), SetTeamStratColors() - will return false
DefaultTeamColors(), SetFFATeamColors() - will return true

SetTeamColors(int TeamColorType)

After FFA or Team Colors are setup, calls the appropriate SetTeamColors() function, either FFA or Strat, for the specified Type.

int R, int G, int B GetTeamStratIndividualColor(int TeamColorType, int Team)

Returns the specified individual Team's TeamColor settings for the specified TeamColorType as R G B ints.

Vector Color GetTeamStratIndividualColorVector(int TeamColorType, int Team)

Returns the specified individual Team's TeamColor settings for the specified TeamColorType as a Vector of R G B ints.

SetTeamNameForStat(int Team, string Name)

Sets the specified Team name displayed in the Debrief Scores screen.
Note: This function does not currently work in MP.

Get/Set Functions

Matrix GetTransform(Handle h)

Returns the Matrix position of the Handle.

Matrix GetTransform2(Handle h)

Returns the Matrix position of the Handle. Uses a slower search that will work recently dead objects in DeleteObject().

SetTransform(Handle h, Matrix Pos)
SetTransform(Handle h, Handle h2)
SetTransform(Handle h, string Path)

Sets the Handle's Matrix to the Position.
The Path version using the Position of Path Point 0, and faces towards Path Point 1.

int GetTeamNum(Handle h)

Returns the Team number of the Handle.

SetTeamNum(Handle h, int Team)

Sets the Handle to the Team number.
Note: Do not call this on a Player in MP.

int GetPerceivedTeam(Handle h)

Returns the Handle's Perceived Team.

SetPerceivedTeam(Handle h, int Team)

Sets the Handle's Perceived Team to the Team number.

number GetHealth(Handle h)

Returns the Health Ratio of the Handle. 1.0 is 100% Health, 0.0 is 0% Health.

number GetCurHealth(Handle h)

Returns the Current Health value of the Handle.

SetCurHealth(Handle h, number Value)

Sets the Current Health of the Handle to the Value.

number GetMaxHealth(Handle h)

Returns the Max Health value of the Handle.

SetMaxHealth(Handle h, number Value)

Sets the Max Health of the Handle to the Value.

AddHealth(Handle h, number Value)

Adds the Value to the Handle's Current Health.

number GetAmmo(Handle h)

Returns the Ammo Ratio of the specified Handle. 1.0 is 100% Ammo, 0.0 is 0% Ammo.

number GetCurAmmo(Handle h)

HaReturns the Current Ammo value of the Handle.

SetCurAmmo(Handle h, number Value)

Sets the Current Ammo of the Handle to the Value.

number GetMaxAmmo(Handle h)

Returns the Max Ammo value of the Handle.

SetMaxAmmo(Handle h, number Value)

Sets the Max Ammo of the Handle to the Value.

AddAmmo(Handle h, number Value)

Adds the Value to the Handle's Current Ammo.

number GetCurLocalAmmo(Handle h, int Slot)

Returns the Current Local Ammo of the Weapon Slot.

SetCurLocalAmmo(Handle h, number Value, int Slot)

Sets the Handle's Local Ammo in the Weapon Slot to the Value.

number GetMaxLocalAmmo(Handle h, int Slot)

Returns the Max Local Ammo of the Weapon Slot.

AddLocalAmmo(Handle h, number Value, int Slot)

Adds the Value to the Handle's Local Ammo in the Weapon Slot.

Vector GetVelocity(Handle h)

Returns the Handle's Velocity vector.

SetVelocity(Handle h, Vector velocity)

Sets the Velocity of the Handle.

Handle GetWhoShotMe(Handle h)

Returns the Handle of the object that most recently shot the Handle.

number GetLastEnemyShot(Handle h)

Returns the Time of the last time an Enemy shot the Handle.

number GetLastFriendShot(Handle h)

Returns the Time of the last time an Ally shot the Handle.

int GetIndependence(Handle h)

Returns the Handle's current Independence setting.

SetIndependence(Handle h, int Independence)

Sets the Handle's Independence. This controls if a unit acts on it's own. 0 = Off, 1 = On.

int GetWeaponMask(Handle h)

Returns the Handle's current WeaponMask.

SetWeaponMask(Handle h, number Mask)

Sets the WeaponMask of the Handle to the value.
Mask is a BitMask value. See ODF Documentation Guide for more info on BitMasks.

Handle GetUserTarget()
Handle GetUserTarget(int Team)

Returns the Handle of the Player's Target. If no Team is specified, it uses the Local user.
Note: When coding for MP, Only use the version that takes a Team.

SetUserTarget(Handle h)
SetUserTarget(int Team, Handle h)

Sets the users Target to the Handle. If Team is not specified, it uses the Local user.
Note: When coding for MP, Only use the version that takes a Team.

Handle GetTarget(Handle h)

Returns the Handle of the Handle's current Target.

SetTarget(Handle h, Handle Target)

Sets the Handle's Target. If Target is nil it clears the Target.

int GetSkill(Handle h)

Returns the Handle's current Skill setting.

SetSkill(Handle h, int Skill)

Sets the Handle's Skill level. Valid values are: 0-3.

int GetScavengerCurScrap(Handle h)

Returns the current Scrap storage inside the Handle. Only works for Scavenger/ScavengerH.

SetScavengerCurScrap(Handle h, int Value)

Sets the current Scrap storage inside the Handle to the Value. Only works for Scavenger/ScavengerH.

int GetScavengerMaxScrap(Handle h)

Returns the Max Scrap storage inside the Handle. Only works for Scavenger/ScavengerH.

SetScavengerMaxScrap(Handle h, int Value)

Sets the Max Scrap storage inside the Handle to the Value. Only works for Scavenger/ScavengerH.

int GetGroup(Handle h)
string GetGroup(int Team, int Group, int ObjectInfoType)

The Handle version returns the current Group index of the Handle, or nil if it's invalid.
The other returns a String of what Type the specified Group is, based on the ObjectInfoType requested.
ObjectInfoType values:

• 0 = Get_CFG, // Returns the GameObjectClass's cfg string
  
• 1 = Get_ODF, // Returns the ODF of the object
  
• 2 = Get_GOClass_gCfg, // Returns the GameObjectClass's gCfg string (not 100% sure how it differs from the CFG)

Returns nil if there are any problems.
Note: AI teams ignore groups, so don't trust the results.

GetGroupCount(int Team, int Group)

Returns the number of Units in the Group of the specified Team.

SetGroup(Handle h, int GroupIndex)

Sets the Handle to the Group in the F Key slots.

int SetBestGroup(Handle h)

Sets the Best group found for the Handle, which is the first non-full group matching it's type, or a new group if available.
Returns the Group index or -1 if it couldn't find a valid Group.

Handle GetOwner(Handle h)

Returns the Owner of the Handle.
Note: Not all objects have known owners, so this'll probably return 0 much of the time.

SetOwner(Handle h, Handle owner)

Sets the Handle's Owner.

string GetPilotClass(Handle h)

Returns the Pilot Class of the Handle. e.g. "ispilo"

string GetPilotOdf(Handle h)

Returns the Pilot ODF of the Handle. e.g. "ispilo.odf"

SetPilotClass(Handle h, string PilotClass)

Sets the Handle's PilotClass. e.g. "ispilo".

string GetLabel(Handle h)

Returns the Handle's Label string.
Returns nil if h is invalid.

SetLabel(Handle h, string Label)

Sets the Handle's Label string. Usable by GetHandle().

Handle GetTap(Handle BaseObj, int Slot)

Returns the Handle of the BaseObj's Tap Slot.

SetTap(Handle BaseObj, int Slot, Handle h)

Sets the Handle as the BaseObj's Tap Slot Handle.

Vector GetOmega(Handle h)

Returns the Handle's current Omega Vector.

SetOmega(Handle h, Vector Omega)

Sets the Handle's current Omega Vector.

bool GetCanSnipe(Handle h)

Returns true if the Handle can be Sniped.

SetCanSnipe(Handle h, int CanSnipe = -1)

Sets if the Handle can be Sniped. -1 is Default, 0 = false, 1 = true.

number GetEjectRatio(Handle h)

Returns the Handle's eject Ratio.

SetEjectRatio(Handle h, number Ratio)

Sets the Handle's eject Ratio. Valid values are 0.0 - 1.0.

Object Functions Part 1

Handle BuildObject(string ODF, int Team, Handle Position)
Handle BuildObject(string ODF, int Team, Matrix Position)
Handle BuildObject(string ODF, int Team, Vector Position)
Handle BuildObject(string ODF, int Team, string Path, int Point = 0)

Builds the ODF, on the Team number, at the Location.
Note: Triggers AddObject on the Handle it returns.

RemoveObject(Handle h)

Removes the Handle.
Note: Triggers DeleteObject on the Handle.

Vector GetPosition(Handle h)
Vector GetPosition(string Path, int Point = 0)

Returns the Vector position of the Handle or Path.

Vector GetPosition2(Handle h)

Like GetPosition, but does a search over recently dead objects. For use in DeleteObject() to get the position of a recently dead thing.

SetPosition(Handle h, Vector pos)
SetPosition(Handle h, Handle h)
SetPosition(Handle h, string Path, int Point = 0)

Sets the Handle's position to the specified Vector.
Note: This is only position. Use SetTransform() if you want to change rotation too.

bool IsPlayer(Handle h)

Returns true if the specified Handle is a Player.

Handle GetNearestObject(Handle h)

Returns the nearest GameObject to the specified Handle.

Handle GetNearestVehicle(Handle h)
Handle GetNearestVehicle(string Path, int Point = 0)

Returns the nearest Craft to the specified Handle, or Path point, optionally at the specified point # in the Path.

Handle GetNearestBuilding(Handle h)

Returns the nearest Building to the specified Handle.

Handle GetNearestEnemy(Handle h)
Handle GetNearestEnemy(Handle h, bool ignorePilots, bool ignoreScavs, number maxDist = 450.0)

Returns the nearest Enemy Craft or Person within a 450m radius of the specified Handle.

char GetRace(Handle h)

Returns the Race letter of the specified Handle.

bool IsAround(Handle h)

Returns false if the Handle doesn't exist.
Note: For backwards compatability with BZ98Redux this function can also be called "IsValid"

bool IsAlive(Handle h)

Returns false if the Handle doesn't exist,
Returns false if the Handle doesn't have an AI Process.
Note: The Player's Handle will return False. Use in combination with NOT IsPlayer(Handle h) on Players.

bool IsAliveAndPilot(Handle h)

Returns false if the Handle doesn't exist.
Returns false if the Handle Is a Player and is not a Person.
Returns false if the Handle is a Vehicle and doesn't have an AI Process, or doesn't have a Pilot.
Note: The Player's Handle will return False unless they are not in a ship. Use in combination with NOT IsPlayer(Handle h) on Players.

bool IsNotDeadAndPilot(Handle h)

Like IsAliveAndPilot(), but does a slower search over GameObject's that may be flagged Destroyed but not fully Removed yet.
Returns false if the Handle doesn't exist.
Returns false if the Handle Is a Player and is not a Person.
Returns false if the Handle is a Vehicle and doesn't have an AI Process, or doesn't have a Pilot.
Note: The Player's Handle will return False unless they are not in a ship. Use in combination with NOT IsPlayer(Handle h) on Players.

bool IsFlying(Handle h)

Returns true if the Handle is considered Flying.

bool IsPowered(Handle h)

Returns true if the Handle is Powered.
Note: Powered might mean different things on non Buildings.

Handle InBuilding(Handle h)
Handle InBuilding(Handle h, number MaxHeight)

Returns the Handle of the Building the specified Handle is inside of. The MaxHeight can be used to control how high it looks for a Cieling above the Handle. Default is 1000.

Handle AtTerminal(Handle h)

Returns the Handle of the building the specified Handle is at.

Vector GetFront(Handle h)

Gets the Front Vector of the specified Handle.

Vector GetLookFront(Handle h)

Gets the Front Vector of the specified Handle's Reticle.

Damage(handle me, number Amount)
Damage(handle me, Handle him, number Amount)

Damages the Handle me by the specified amount and assigns Handle him as the object that did the damage. If Handle him is not specified, Handle me is treated as the object that did the Damage.

AddPilotByHandle(Handle h)

Adds a Pilot to the specified Handle if it's Empty and can have a Pilot.

bool IsDeployed(Handle h)

Returns true if the specified Handle is Deployed.

Handle HoppedOutOf(Handle h)

Returns the Handle that the specified Handle last Hopped out of.

GiveWeapon(Handle h, string Weapon)
GiveWeapon(Handle h, string Weapon, int Slot)

Gives the specified weapon string to the specified Handle.
The first version acts just like a Powerup Pickup, checking that there is a valid Hardpoint and slotting it into the first available slot that is valid.
The second skips all validation checks and stomps over the specified Slot, but will still respect isAssault and use altName.
Note: Slot is 0 - 4.
Note: If no altName exists for Assault HPs, it clears it.

bool IsFollowing(Handle me)
bool IsFollowing(Handle me, Handle him)

The first function Returns true if the specified Handle's CurCmd or NextCmd is CMD_FOLLOW.
The second Returns true if Handle me is Following Handle him.

Handle WhoFollowing(Handle h)

Returns the Handle of who the specified Handle is following.

KillPilot(Handle h)

Causes the Pilot inside the specified Handle to Explode as if it were Sniped.

RemovePilot(Handle h)

Removes the Pilot inside the specified Handle.

SetAvoidType(Handle h, int Type)

Sets the Avoidance Type of the Handle. Valid values are:

• 0 = None
  
• 1 = Force
  
• 2 = Plan

Annoy(Handle me, Handle him)

Causes Him to aggro on Me, as if me shot him.

ClearThrust(Handle h)

Clears the Handle's thrust.

SetVerbose(Handle h, bool Verbose)

Sets the Verbose flag on the Handle. If Verbose is false, and Priority is 1, it will not say any Unit VO Dialog.

ClearIdleAnims(Handle h)

Clears the Idle Animations on an Animal class object.

AddIdleAnim(Handle h, string Name)

Adds an Idle Animation to an Animal class object.

bool IsIdle(Handle h)

Returns false if the Handle is a Player, CurCmd != CMD_NONE, NextCmd != CMD_NONE, or last Cmd Priority = 1. Otherwise returns true.

int Here, int Coming CountThreats(Handle h)

Counts the number of Enemy Craft that are alive and have a current Task set.
Returns the number of Units within 200m of the Handle as Here, and the number of Units outside 200m as Coming.

SpawnBirds(int Group, int Count, string ODF, int Team, string Path)
SpawnBirds(int Group, int Count, string ODF, int Team, Handle Start, Handle Finish)

Spawns a Group of Boid class Objects at the Start location or start of the Path, and sets their destination position to the Finish location or end of the Path.

RemoveBirds(int Group)

Removes a Group of Boid objects spawned via SpawnBirds().

SetRandomHeadingAngle(Handle h)

Sets the specified Handle to a random horizontal facing direction.

SetAngle(Handle h, number Degrees)

Sets the specified Handle to the horizontal facing direction in Degrees (from North).

Handle GetTug(Handle Cargo)

Returns the Handle of the Tug carrying the specified Cargo. Returns nil if there is no Tug.

bool HasCargo(Handle Tug)

Returns true if the object is a Tug and is carrying Cargo.

Object Functions Part 2

Handle GetHandle(int SequenceNumber)
Handle GetHandle(string Label)

Returns the Handle ID of the specified Object.
Note: If multiple objects with the same Label exist, it will return the oldest one.

Handle GetObjectByTeamSlot(int Slot)
Handle GetObjectByTeamSlot(int Team, int Slot)

Returns the Handle of the object occupying the specified Team Slot. Valid values are 0-14, as noted in DLL_TEAM_SLOTS.
If the Team number is not specified, uses the Local User's Team.
Note: When scripting in MP, only use the version that takes a Team number.
Note: For backwards compatibility with BZ98 Redux, this function can also be named "GetTeamSlot"

Table GetAllGameObjectHandles()

Returns a Table of all the Game Objects on the map.
Note: This is slightly intensive, so use it sparingly.

Table WhoIsTargeting(Handle h)

Returns a Table of all the Game Objects currently Targeting the Handle.

bool IsPerson(Handle h)

Returns true if the specified Handle is a Person class.

bool IsBuilding(Handle h)

Returns true if the specified Handle is a Building class.
Note: Gun Towers are a Craft.

bool IsPowerup(Handle h)

Returns true if the specified Handle is a Powerup class.

bool IsCraftButNotPerson(Handle h)

Returns true if the specified Handle is a Craft class.

bool IsCraftOrPerson(Handle h)

Returns true if the specified Handle is a Craft or Person class.

bool IsOdf(Handle h, string ODF)

Returns true of the Handle is of the specified ODF name.
Note: This is an exact match only. It may not work with the appended :# Team numbers on Objects built from a Recycler/Factory.

MakeInert(Handle h)

Sets the specified craft to be invisible, uncollidable, without weapons, etc. Used for a dedicated server's fake-vehicle.

Deploy(Handle h)

Forces the specified Handle to trigger the Deploy Control.

EjectPilot(Handle h)

Forces the specified Handle to trigger the Eject Control.

HopOut(Handle h)

Forces the specified Handle to trigger the Abandon Control.

SetControls(Handle h, Table Controls)

Sets which Controls are available for use. Takes a Table with the following values, and a bool if they're enabled or not.

• braccel
  
• steer
  
• pitch
  
• strafe
  
• jump
  
• deploy
  
• eject
  
• abandon
  
• fire

SetNoScrapFlagByHandle(Handle h)

Sets the specified Handle to not drop Scrap.

ClearNoScrapFlagByHandle(Handle h)

Sets the specified Handle to be able to drop Scrap.

SelfDamage(Handle h, number Amount)

Damages the object as if it shot it self.

ResetTeamSlot(Handle h)

Resets the Team Slot of the specified Handle. For use if there are multiple objects that use the same Team Slot on the same Team. This makes the specified Handle the currently used one.

int GetCategoryTypeOverride(Handle h)

Returns the categoryTypeOverride value, as specified in the ODF by [GameObjectClass]::categoryTypeOverride.
Returns -1 if it is still Default, or -2 if h is invalid.

int GetCategoryType(Handle h)

Returns the categoryType of the specified Handle. Useful if categoryTypeOverride is hiding it.

number GetRemainingLifespan(Handle h)

Returns the remaining Lifespan of the Handle, in seconds.
Returns nil if the Handle is invalid.
Returns 0 if the Lifespan is infinite.

number GetLifeSpan(Handle h)

Returns the remaining Lifespan of the Handle, in seconds.
Returns nil if the Handle is invalid
Returns < 0 if the lifespan is Infinite.

SetLifespan(Handle h, number Time)

Sets the remaining LifeSpan of the specified Handle to the Time, in seconds.

Handle GetNearestPowerup(Handle h, bool IgnoreSpanwpoints, number MaxDist = 450.0)

Returns the nearest Powerup object to the specified Handle, within the maxDist. If IgnoreSpanwpoints is true, it skips the ODF "pspwn_1".

Handle GetNearestPerson(Handle h, bool skipFriendlies, number MaxDist = 450.0)

Returns the nearest Person object to the specified Handle, within the maxDist. If skipFriendlies is true, it skips Allies.

bool IsWithin(Handle h1, Handle h2, number Distance)

Returns true if h1 and h2 are within the specified Distance of each other.

int CountUnitsNearObject(Handle h, number Distance, int Team, string ODF)

Counts objects near the specified Handle.
If h is NIL and Distance is > 10000 it will count all objects on the map. If ODF is NIL, it will count all objects within distance.
Note: The count includes the handle object.

string GetCfg(Handle h)

Returns the GetObjInfo_CFG string for the Handle. e.g. "ivtank" or "ivtank:1"

string GetOdf(Handle h)

Returns the GetObjInfo_ODF string for the Handle. e.g. "ivtank.odf"

string GetBase(Handle h)

Returns the GetObjInfo_GOClass_gCFG string for the Handle. This is the baseName value.

string GetClassSig(Handle h)

Returns the GetObjInfo_EntityType string for the Handle. Valid values are listed in the EntityTypes List. e.g. "CLASS_ID_CRAFT".

string GetClassLabel(Handle h)

Returns the GetObjInfo_GOClass string for the Handle. Valid values are listed in the GOClass list. e.g. "CLASS_WINGMAN".

string GetWeaponConfig(Handle h, Slot = 0)

Returns the Get_Weapon#Config string for the Handle, for the specified Weapon Slot. e.g. "gminigun_c"
Note: For backwards compatibility with BZ98 Redux, this function can also be called "GetWeaponClass"

string GetWeaponODF(Handle h, int Slot = 0)

Returns the GetObjInfo_Weapon#ODF string for the Handle, for the specified Weapon Slot. e.g. "gminigun_c.odf"

string GetWeaponGOClass(Handle h, int Slot = 0)

Returns the GetObjInfo_Weapon#GOClass string for the Handle, for the specified Weapon Slot. e.g. "CLASS_MACHINEGUN".

int GetTeamRelationship(Handle h1, Handle h2)

Returns the Team Relationship List value for the specified Handles.

bool HasPilot(Handle h)

Returns true if the Handle has a Pilot.

int GetBaseScrapCost(Handle h)
int GetActualScrapCost(Handle h)

Returns the Base scrap cost of the Handle.

SetLastCurrentPosition(Handle h, Matrix LastMatrix, Matrix CurMatrix = nil)

Sets the last and current orientation & positions simultaneously. The caller should take care to set lastMatrix to what was passed in as the curMatrix last frame, or jittering can occur.

SetInterpolablePosition(Handle h, Vector TruePos = nil, Vector LastPos = nil)
SetInterpolablePosition(Handle h, Matrix TrueMat = nil, Matrix LastMat = nil, bool SetPosition = true)

Sets the Last and True positions for a Handle.
If you pass nil for one of the Positions, it will leave that value untouched.
If SetPosition is false, the Matrix version will only update the Orientation.
Note: BZCC will interpolate each turn (1.0 seconds divided by MWF) every object's position/orientation from the last position to true position. For smoother onscreen movement, an entity's true position should be passed in as the last position the next turn.

bool CanBuild(Handle h)

Returns true if the specified Handle can Build things.

bool IsBusy(Handle h)

Returns true if the specified Handle is currently Building something.

string GetBuildClass(Handle h)

Gets the ODF that the Handle is currently Building.

string GetQueuedItem(Handle h, int Index = 0)

Gets the ODF that the Handle has qued to Build in the Index slot.

Object Functions Part 3

MaskEmitter(Handle h, int Mask)

Sets the EffectMask of the Handle to the specified Bitmask.

number GetEmitterMask(Handle h)

Gets the EffectMask of the specified Handle.

StartEmitter(Handle h, int Slot)

Starts the EffectHard of the specified Slot.

StopEmitter(Handle h, int Slot)

Stops the EffectHard of the specified Slot.

bool IsEmitterOn(Handle h, int Slot)

Returns true if the specified EffectHard slot is active.

number SetAnimation(Handle h, string Name, int Type)

Sets the specified Animation Name on the Handle, and sets the Type of animation. 0 = loop, 1 = two way.
Returns the max Frame count of the Animation.

StartAnimation(Handle h)

Starts the currently Set Animation on the Handle.

number GetAnimationFrame(Handle h, string Name)

Gets the current Frame of the specified Animation Name on the Handle.

number PauseAnimation(Handle h)

Pauses the currently playing Animation on the Handle. Returns the direction the Animation was playing.

ResumeAnimation(Handle h, int Direction = 1)

Resumes the Handle's Animation, or changes it's direction. -1 = Backwards, 1 = Forwards.

int GetAnimationDirection(Handle h)

Returns the Handle's current Animation's Direction.

bool Move(Handle h, number TurnSpeed, number Time)
bool Move(Handle h, number TurnSpeed, number MoveSpeed, Vector Dest)

Moves the Handle for the specified Time, or to the specified Destination Vector.
Returns true when it arrives, or the time runs out.

Handle ReplaceObject(Handle h, string ODF = nil, int Team = -1, number HeightOffset = 0.0, int Empty = -1, bool restoreweapons = true, int group = -1, int CanSnipe = -1, bool keepcmd = true, int NewCmd = -1, int NewPriority = 0, Handle NewWho = 0, Vector NewWhere = (0, 0, 0))

Replaces the specified Handle, while retaining as much information as possible. Returns the new Handle. Optionally with the following parameters:

• ODF: The ODF to replace it with. If nil it uses the same ODF.
  
• Team: The Team to put the replacement object on. If -1 it leaves Team unchanged.
  
• HeightOffset: Height difference to spawn the replacement object with, compared to the original.
  
• Empty: If Empty is 1, it spawns the vehicle Empty, if 0 it spawns it with a Pilot. If -1 then it retains the state it had before.
  
• restoreWeapons: If true, transfers the equipped Weapons. If false, doesn't update the Weapons.
  
• Group: The Group to put this object into. if -1 then it leaves group unchanged.
  
• CanSnipe: Sets if the new object can be Sniped. if -1 then it leaves that setting unchanged.
  
• keepCmd: If true, tries to keep as much info about the object's current Command as possible.
  
• NewCmd: If this is not -1, replaces previous Command with this Command, and uses the following.
  
• NewPriority: If NewCmd is used, this is the Priority of that Command.
  
• NewWho: If NewCmd is used, This is the Who of that Command.
  
• NewWhere: If NewCmd is used, This is the new Where of that Command.

bool CanCommand(Handle h)

Returns true if the object is Around, has a Pilot, and is in a Group.

Cinematic Functions

Vector Pos, Vector Dir GetCameraPosition()

Returns the Position Vector, and the Direction Vector of the Camera.

SetCameraPosition(Vector pos, Vector dir)

Sets the Position and Direction vectors of the Camera.

ResetCameraPosition()

Resets the Camera Position.

bool CameraReady()

Prepares the Camera for a Cutscene. Must be called before other Camera functions.

bool CameraPath(string Path, int Height, int Speed, Handle Target)

Makes the Camera follow the Path at the specified Height above ground and Speed, and looking at the specified Target.
Returns true when it reaches the end of the Path.

bool CameraPathDir(string Path, int Height, int Speed)

Makes the Camera follow the Path at the specified Height above ground and Speed.
Returns true when it reaches the end of the Path.

bool CameraPos(Handle me, Handle him, Vector PosA, Vector PosB, number Speed)

Moves the Camera from Position A, to Position B, based on the position of Handle me, looking towards Handle him.

bool PanDone()

Returns true when the Camera reaches the end of the Path.

bool CameraObject(Handle Object, Vector Offset, Handle Target)
bool CameraObject(Handle Object, number X, number Y, number Z, Handle Target)

Sets the Camera at the specified Offset from the Object's position, looking towards the Target.

CameraOf(Handle me, Vector offset)

Sets the Camera to the perspective of the specified Handle, with the specified Offset.

bool CameraFinish()

Called at the end of a Camera sequence. Returns the Camera to the normal perspective.

bool CameraCancelled()

Returns true if the user pressed the Space bar to Skip the camera sequence.

bool FreeCamera()

Sets the Camera to Free Camera mode, and enables the Cursor on the screen.

bool FreeFinish()

Turns off Free Camera mode, and hides the Cursor on the screen.

bool PlayMovie(string name)

Plays a prerecorded camera sequence.

StopMovie()

Stops a prerecorded Camera sequence.

bool PlayMove()

Plays the currently selected Move. Returns true when finished.

bool PlayRecording(string Name)
bool PlayRecording(string Name, bool UpdateCam)

Plays the specified Recording, optionally with the ability to update the existing Camera or not.

bool PlaybackVehicle(string Name)

Plays a prerecorded series of Craft control movements on the User's craft.

Interface Functions

StartCockpitTimer(number Time, number Warn = --2147483647, number Alert = -2147483647)

Starts a Cockpit timer that counts Down for specified Time, in seconds.
Setting Warn sets the time that the Cockpit Timer turns Yellow.
Setting Alert sets the time the Cockpit Timer turns Red.

StartCockpitTimerUp(number Time, number Warn, number Alert)

Starts a Cockpit Timer that counts Up from the specified Time, in seconds.
Setting Warn sets the time that the Cockpit Timer turns Yellow.
Setting Alert sets the time the Cockpit Timer turns Red.

StopCockpitTimer()

Stops the Cockpit Timer.

HideCockpitTimer()

Hides the Cockpit Timer.

number GetCockpitTimer()

Returns the current time on the Cockpit Timer.

SetObjectiveOn(Handle h)

Highlights the specified Handle.

SetObjectiveOff(Handle h)

Turns off Highlighting on the specified Handle.

string GetObjectiveName(Handle h)

Returns the Handle's current Name.

SetObjectiveName(Handle h, string Name)

Sets the Name displayed for this object.

ClearObjectives()

Clears the Objective Box of text.

AddObjective(string Text, int Color, number Showtime = 8.0)
AddObjective(string Text, string Color, number Showtime = 8.0)

Displays the Text in the Objective Box with the specified Color, for the specified ShowTime.
Showtime is how long the Objective Box stays open on it's own.
Color can be a direct Color, retrieved from Make_RGB or Make_RGBA, or one of the Color Strings. Default is WHITE if not specified.

string GetPlayerName(Handle h)

Returns the Name of the Player that owns the specified Handle. If the Handle doesn't exist, Team 0 is used. If the value is empty, "Unknown" is returned.

string GetVarItemStr(string VarName)

Returns the value of the specified Var string.
Note: In 185 this function doesn't work. Use IFace_GetString for now.

int GetVarItemInt(string VarName)

Returns the value of the specified Var string
This version returns an Int and looks first in the MP ivars, and then in all vars, so it is faster for use with ivars in an MP game.

int GetCVarItemInt(int Team, int Index)

Returns one of the Client's civars on the specified Team, of the specified civar Index number.

string GetCVarItemStr(int Team, int Index)

Returns one of the Client's csvars on the specified Team, of the specified csvar Index number.

IFace_Exec(string filename.cfg)
IFace_Exec(string filename.cfg, bool MenuScale)

Loads the specified Config file.Max length is 256.
The optional Scale version can be used to control the font scale used in the UI, if true, uses Menu scale, if false, uses in-Game scale.
Note: If .cfg is missing, it won't try to find a Resolution specific version.

IFace_Activate(string Name)

Activates the specified CFG Control Name.

IFace_Deactivate(string Name)

Deactivates the specified CFG Control Name.

IFace_CreateCommand(string command)

Creates a VarSys command.

IFace_CreateString(string Name, string Value)

Creates a string in VarSys with the specified Name and Value.
Note: Do NOT create a Name that already exists.

IFace_SetString(string Name, string Value)

Sets the specified VarSys string to the specified Value.

string IFace_GetString(string Name)

Returns the value of the specified VarSys string.

IFace_CreateInteger(string Name, int Value)

Creates an Integer in VarSys with the specified Name and Value.
Note: Do NOT create a Name that already exists.

IFace_SetInteger(string Name, string Value)

Sets the specified VarSys integer to the specified Value.

int IFace_GetInteger(string Name)

Returns the value of the specified VarSys integer.

IFace_SetIntegerRange(string Name, int Min, int Max)

Sets the min/max range of the specified VarSys integer.

IFace_CreateFloat(string Name, number Value)

Creates a float in VarSys with the specified Name and Value.
Note: Do NOT create a Name that already exists.

IFace_SetFloat(string Name, string Value)

Sets the specified VarSys float to the specified Value.

number IFace_GetFloat(string Name)

Returns the value of the specified VarSys float.

IFace_ClearListBox(string Name)

Clears the specified ListBox Control Name's contents

IFace_AddTextItem(string Name, string Value)

Adds the specified Value to the ListBox with specified Control Name.

string IFace_GetSelectedItem(string Name)

Returns the contents of the currently Selected item in the specified ListBox Control.

IFace_ConsoleCmd(string Cmd, bool SquelchOutput = true)

Inputs a string to the Console, as if the user typed it in.
Note: Can be used on any console command, even if it is not accessible from the Console.

IFace_EnterMenuMode()

Enters Menu mode aspect Ratio.

IFace_ExitMenuMode()

Exits Menu mode aspect Ratio.

Network_SetString(string Name, string Value)

Sets the specified svar to the Value.

Network_SetInteger(string Name, int Value)

Sets the specified ivar to the Value.

int GetInstantMyForce()

Returns the setting from Instant Action's My Force setting.

int GetInstantCompForce()

Returns the setting from Instant Action's Computer Force setting.

int GetInstantDifficulty()

Returns the setting from Instant Action's Difficulty setting.

int GetInstantGoal()

Returns the setting from Instant Action's Goal setting.

int GetInstantType()
int GetInstantFlag()

Depreciated.

int GetInstantMySide()

Returns the setting from Instant Action's MySide setting from the TRN.

Multi Player Functions

int GetCurWorld()

Returns the current MP World.

bool IsNetworkOn()

Returns true if the game is being played in MP.
Note: For backwards compatibility with BZ98 Redux, this function can also be called "IsNetGame".

bool ImServer()

Returns true if the local machine is the current Host.
Note: For backwards compatibility with BZ98 Redux, this function can also be called "IsHosting".

bool ImDedicatedServer()

Returns false. Dedicated Server not supported in BZCC.

bool IsTeamplayOn()

Returns true if Teamplay is on in an MP game.

int CountPlayers()

Returns the number of Players currently in-game.

int CountAllies(int Team)

Returns the number of Players on the specified Team Group that are currently in-game.

int WhichTeamGroup(int Team)

Returns which MP Team Group the specified Team belongs to. If TeamPlay is on, typically Team 1-5 are TeamGroup 1, and 6-10 are TeamGroup 2.

• 0 = Team Group 1
  
• 1 = Team Group 2

int GetCommanderTeam(int Team)

Returns the Commander's Team # for the specified Team. If TeamPlay is on, typically 1 or 6.

int GetFirstAlliedTeam(int Team)

Returns the lowest Team that is in the same TeamGroup as the specified Team. If TeamPlay is on, typically 1 or 6.

int GetLastAlliedTeam(int Team)

Returns the highest Team that is in the same TeamGroup as the specified Team. If TeamPlay is on, typically 5 or 10.

int DefensiveTeam, int OffensiveMinTeam, int OffensiveMaxTeam GetTeamplayRanges(int Team)

For the specified Team, returns the Defensive (Commander) Team number, the first Offensive (Thug) Team number, and the last Offensive (Thug) Team number.

string GetPlayerODF(int Team, int RandomizeType = 0)

Returns the next ODF from the MPVehicles list of possible Vehicles to Spawn the player in.
RandomizeType is the type of Randomization to use, valid values are:

• 0 = None
  
• 1 = Race
  
• 2 = Any

Handle BuildEmptyCraftNear(Handle h, string ODF, int Team, number MinRadius, number MaxRadius)

Builds the specified ODF within MinRadius and MaxRadius around the specified Handle, on the specified Team.
Note: This is used with GetPlayerODF() in MP to spawn a ship when the player lands. If the ODF is a Person class, it doesn't spawn it.

Vector GetSafestSpawnpoint()

Returns the closest Spawnpoint or next closest Spawnpoint position to a given position. Returns 0 if no Spawnpoints are available.

Vector GetSpawnpoint(int Team)

Returns the position of the first Spawnpoint found with the specified Team number.

Handle GetSpawnpointHandle(int Team)

Returns the Handle of the first Spawnpoint found with the specified Team number.

Vector GetRandomSpawnpoint(int Team = -1)

Returns the Position of a Spawnpoint at random that looks fairly safe to the specified Team. If Team is not specified or is -1, picks out of all Spawnpoints.

Table GetAllSpawnpoints(int Team = 0)

Returns a Table of all Spawn Points, each with the following info:

• Vector Position
  
• int Team
  
• Handle Handle
  Distances will be a "huge number" (1.0e30f) if nothing can be found in that category. Otherwise, it's the distance (in meters) in the XZ (horizontal) plane
  Distance to closest item on team 0 (including scrap pools, etc)
  
• number DistanceToClosestTeamZero
  The following are valid only if spawnpoint has a team set, or finding spawnpoints relative to a team
  
• number DistanceToClosestSameTeam
  
• number DistanceToClosestAlly
  
• number DistanceToClosestEnemy

SetTimerBox(string Text)

Sets the Text in the Timer Box in the MP Scores screen. e.g: "Time Left: 03:14"

AddToMessagesBox(string Text)
AddToMessagesBox(string Text, int Color)

Adds a String to the MP Chat box. If Color is specified, it uses that Color.
Color can be a value returned from Make_RGB or Make_RGBA, or a Color String.

int GetDeaths(Handle h)

Returns the number of Deaths on the Score Board for the Player who owns the specified Handle.

int GetKills(Handle h)

Returns the number of Kills on the Score Board for the Player who owns the specified Handle.

int GetScore(Handle h)

Returns the Score on the Score Board for the Player who owns the specified Handle.

SetDeaths(Handle h, int Value)

Sets the number of Deaths on the Score Board for the Player who owns the specified Handle to the Value.

SetKills(Handle h)

Sets the number of Kills on the Score Board for the Player who owns the specified Handle to the Value.

SetScore(Handle h)

Sets the Score on the Score Board for the Player who owns the specified Handle to the Value.

AddDeaths(Handle h, int Value)

Adds the Value to the number of Deaths on the Score Board for the Player who owns the specified Handle.

AddKills(Handle h)

Adds the Value to the number of Kills on the Score Board for the Player who owns the specified Handle.

AddScore(Handle h)

Adds the Value to the Score on the Score Board for the Player who owns the specified Handle.

int GetLocalPlayerDPID()

Returns the DPID of the local Player.

FlagSteal(Handle flag, Handle holder)

Triggers a Flag Steal message on the Holder.

FlagRecover(Handle flag, Handle holder)

Triggers a Flag Recover message on the Holder, and Resets the Flag to it's Base.

FlagScore(Handle flag, Handle holder)

Triggers a Flag Score message on the Holder.

MoneyScore(int Amount, Handle holder)

Adds the specified Amount to the score of the Holder.

NoteGameoverByTimelimit()

Prints a message to the MP Chat box and Debrief Screen that the MP Game is over by Time Limit.

NoteGameoverByKillLimit(Handle h)

Prints a message to the MP Chat box and Debrief Screen that the MP Game is over by Kill Limit by the specified Handle.

NoteGameoverByScore(Handle h)

Prints a message to the MP Chat box and Debrief Screen that the MP Game is over by Score Limit by the specified Handle.

NoteGameoverByLastWithBase(Handle h)

Prints a message to the MP Chat box and Debrief Screen that the MP Game is over by the last individual with a Base by the specified Handle.

NoteGameoverByLastTeamWithBase(int TeamGroup)

Prints a message to the MP Chat box and Debrief Screen that the MP Game is over by the last Team Group with a Base.

NoteGameoverByNoBases()

Prints a message to the MP Chat box and Debrief Screen that the MP Game is over by no one having a Base.

NoteGameoverWithCustomMessage(string Message)

Prints a message to the MP Chat box and Debrief Screen that the MP Game is over by the Message string.

DoGameover(number Time)

Sets the MP game to End to the End game Scores screen after the specified Time in seconds has passed.

SetMPTeamRace(int TeamGroup, char Race)

Sets the specified TeamGroup's Race.

KickPlayer(Handle h, string Reason, bool Ban = false)

Kicks the Player who owns the specified Handle, with the specified Reason. If Ban is true it also adds them to the Ban list.

string GetNetworkListItem(int NetworkListType, int Index)

Returns the specified Item in the specified NetworkListType.

int GetNetworkListCount(int NetworkListType)

Returns the count of how many items are in the specified NetworkListType.

Single Player Only Functions

FailMission(number Time, string debrief.txt)
SucceedMission(number Time, string debrief.txt)

Fails/Succeeds the mission after the specified Time has passed, optionally with the specified text file displayed in the Debrief screen. Must specify file extension, but can be any text file format, .txt, .des, .otf, etc.
If no text is specified for FailMission, "genFail.txt" is used.
Note: The debrief text can only be a maximum size of 14 characters, including file extension.

ChangeSide()

Switches the Player's Profile setting from ISDF campaign to Scion campaign. Used to control the Branching campaign system.

bool IsInfo(Handle h)
bool IsInfo(string ODF)

Returns true if the local user has the Info KeyCard active on the specified object type.

bool IsSelected(Handle h)

Returns true if the local user has the specified Handle currently Selected.

SetColorFade(number Ratio, number Rate, string Color)
SetColorFade(number Ratio, number Rate, int Color)

Starts a Color Fade on the local user's Screen. Use Make_RGB to generate an int Color.

StopCheats()

Turns off the following Cheats: Scrap, Ammo, Health, Radar, Satellite, Edit.

Handle GetLocalUserInspectHandle()

Returns the Handle of the object the Local Player's reticle is pointing at.

Handle GetLocalUserSelectHandle()

Returns the Handle of the object the Local Player currently has Selected.

Utility Functions

Print(string)
PrintConsoleMessage(string)

Prints the string to the in game Console.

int CalcCRC(string)

Returns the CRC of the specified String. Used in some SetCommand() commands.

int Make_RGB(int Red, int Green, int Blue)

Creates a Color from R G B. Valid values are 0-255. The Alpha is treated as 255.
Returns the Color value.

int Make_RGBA(int Red, int Green, int Blue, int Alpha)

Creates a Color from R G B A. Valid values are 0-255.
Returns the Color value.

string TranslateString(string Key)
string TranslateString(string Prefix, string Key)

Returns the Translated string from the Localization Table for the specified Key.
If Prefix is not specified, it uses the "ScriptUtils" prefix. e.g. TranslateString("odf", "Unknown")

WantBotKillMessages()

If this is called, even once, it sets the mission to Enable Bot Kills/Deaths events.
Enables Kill/Score for when an AI Building/Craft is killed by a Player.
Enables PlayerEjected()/ObjectKilled()/ObjectSniped() on Non Player Craft.

SetAutoGroupUnits(bool autoGroup = true

Sets if newly spawned units not built by a Factory are automatically added to a Group.

AllowRandomTracks(bool Allow = true)

Sets if Random Music is allowed.
If it is allowed, the Music will play Random songs. If not, only the Tracks listed in the map's .TRN file are played.
Note: LuaMission calls this as True internally, so to override you should call this ASAP, in InitialSetup().

int EnableHighTPS()

Returns the current TPS rate, and enables the Hosts's TPS rate for Clients.
Note: LuaMission does this automatically.

int GetTPS()

Returns the current TPS rate.

string GetMapTRNFilename()

Returns the .TRN file name used with the current map.

string GetMissionFilename()

Returns the .BZN file name used with the current map.

number GetTime()

Returns the current mission Time, in seconds.

number GetDistance(Handle h1, Handle h2)
number GetDistance(Handle h1, Matrix Pos)
number GetDistance(Handle h1, Vector pos)
number GetDistance(Handle h1, string Path, int Point = 0)

Returns the distance between the specified items.

Table GetAiPaths()

Returns a Table of all the Path points on the map.
Note: The order the paths load is not guaranteed to be in the same order as they are in the .bzn

SetPathType(string Path, int Type)

Sets the Path Type. Valid values are:

• 0 = One Way
  
• 1 = Round Trip
  
• 2 = Loop

SetPathOneWay(string Path)
SetPathRoundTrip(string Path)
SetPathLoop(string Path)

Individual versions of SetPathType() above. Added for BZ98Redux backwards compatibility.

Table GetPathPoints(string Path)

Returns a Table of Vectors of the positions of the path Points in the specified Path name.

bool IsInsideArea(string Path, Vector Pos)
bool IsInsideArea(string Path, Matrix Pos)
bool IsInsideArea(string Path, Handle h)

Returns true if the Location is within an enclosed area of the Path.

int GetWindingNumber(string Path, Vector Pos)
int GetWindingNumber(string Path, Matrix Pos)
int GetWindingNumber(string Path, Handle h)

Returns the number of times the Location is encircled by the Path.

StartEarthQuake(number Magnitude)

Starts an Earth Quake at the specified magnitude.

UpdateEarthQuake(number Magnitude)

Updates the current Earth Quake magnitude.

StopEarthquake()

Stops the Earth Quake.

SetGravity(number Gravity = 12.5)

Sets the Gravity on the map to the specified amount.

PreloadODF(string ODF)

This preloads the specified ODF, which is useful to do at the start of a mission to avoid hiccups from calling BuildObject on the object for the first time during game play.

number TerrainFindFloor(Matrix Pos)
number TerrainFindFloor(Vector Pos)
number TerrainFindFloor(Handle h)
number TerrainFindFloor(string Path, int Point = 0)
number TerrainFindFloor(number X, number Z)

Returns the height of the collision floor at the specified location.
Note: This returns the collision map's height, if there is a Building's collision mesh at the location, it will return that height, not the Terrain under the building.
Note: For backwards compatibility with BZ98Redux this function can also be called "GetFloorHeightAndNormal"

bool TerrainIsWater(Vector Pos)
bool TerrainIsWater(Matrix Pos)
bool TerrainIsWater(Handle h)
bool TerrainIsWater(string Path, int Point = 0)
bool TerrainIsWater(number X, number Z)

Returns true if the specified location has a Water tile. This is a very fast check, and ignores Terrain height. If you want more detailed search, use GetTerrainHeightAndNormal.

number Height, Vector Normal GetTerrainHeightAndNormal(Vector Pos, bool UseWater = false)
number Height, Vector Normal GetTerrainHeightAndNormal(Matrix Pos, bool UseWater = false)
number Height, Vector Normal GetTerrainHeightAndNormal(Handle h, bool UseWater = false)
number Height, Vector Normal GetTerrainHeightAndNormal(string Path, int Point = 0, bool UseWater = false)

Returns the Height and the Normal Vector of the Terrain of the specified location. If useWater is true, it uses Water Height.

CalcCliffs(string Path)
CalcCliffs(Handle h1, Handle h2, number Radius)

Forces a Recalculation of the Cell Type Pathing cliffs around the specified area.
Path version draws a rectangle of the bounding box of the specified Path, similar to how edge_path works.
Handle version draws a bounding box between the two Handles and adds the Radius to the size.

Vector GetPositionNear(Matrix Pos, number MinRadius, number MaxRadius)
Vector GetPositionNear(Vector Pos, number MinRadius, number MaxRadius)
Vector GetPositionNear(Handle Pos, number MinRadius, number MaxRadius)
Vector GetPositionNear(string Path, int Point, number MinRadius, number MaxRadius)

Returns a position 'near' Pos, in the ring between MinRadius and MaxRadius, and with roughly the same terrain height as the terrain at the original position.

Vector GetCircularPos(Vector Pos, number Radius, number Angle)

Returns a new position around a central point.

int GetLocalPlayerTeamNumber()

Returns the Team number of the local Player.
Note: Be careful using this in MP.

bool DoesODFExist(string ODF)

Returns true if the specified ODF exists.
Note: Only checks .ODF files. To check a different type, use DoesFileExist().

bool DoesFileExist(string filename)

Returns true if the specified File exists in the currently loaded Assets. Requires file name extension.
Note: This is a fairly intensive search, avoid calling this a lot every turn.

PetWatchdogThread()

Delays the Watchdog timer for 1 turn. Useful if you need to Preload a lot of objects at once.

number SecondsToTurns(number Seconds)

Converts the Seconds into a number of Turns.

number TurnsToSeconds(int Turns)

Converts the number of Turns into Seconds.

number GetTimeStep()

Returns the Seconds that elapse in a single Turn.

DoTaunt(int TauntType)

Calls the Taunt engine to display a Random taunt from the specified TauntType Category.

SetTauntCPUTeamName(string Name)

Sets the CPU Team Name, displayed in front of DoTaunt messages. By default this is the value in svar2.

File Reading/Writing Functions

ODF Reading functions:
These are specific to each Data Type found in ODF files.

int Value, bool Found GetODFHexInt(string File, string Block, string Name, DefaultValue = 0)
int Value, bool Found GetODFHexInt(Handle h, string Block, string Name, DefaultValue = 0)

int Value, bool Found GetODFInt(string File, string Block, string Name, DefaultValue = 0)
int Value, bool Found GetODFInt(Handle h, string Block, string Name, DefaultValue = 0)

number Value, bool Found GetODFLong(string File, string Block, string Name, DefaultValue = 0)
number Value, bool Found GetODFLong(Handle h, string Block, string Name, DefaultValue = 0)

number Value, bool Found GetODFFloat(string File, string Block, string Name, DefaultValue = 0.0)
number Value, bool Found GetODFFloat(Handle h, string Block, string Name, DefaultValue = 0.0)

number Value, bool Found GetODFDouble(string File, string Block, string Name, DefaultValue = 0.0)
number Value, bool Found GetODFDouble(Handle h, string Block, string Name, DefaultValue = 0.0)

bool Value, bool Found GetODFBool(string File, string Block, string Name, DefaultValue = false)
bool Value, bool Found GetODFBool(Handle h, string Block, string Name, DefaultValue = false)

string Value, bool Found GetODFChar(string File, string Block, string Name, DefaultValue = "")
string Value, bool Found GetODFChar(Handle h, string Block, string Name, DefaultValue = "")

Note: Returns nil if it doesn't find anything.

string Value, bool Found GetODFString(string File, string Block, string Name, DefaultValue = nil)
string Value, bool Found GetODFString(Handle h, string Block, string Name, DefaultValue = nil)

Note: Returns nil if it doesn't find anything.

number Value, bool Found GetODFColor(string File, string Block, string Name, DefaultValue = 0)
number Value, bool Found GetODFColor(Handle h, string Block, string Name, DefaultValue = 0)

Vector Value, bool Found GetODFVector(string File, string Block, string Name, DefaultValue = (0, 0, 0))
Vector Value, bool Found GetODFVector(Handle h, string Block, string Name, DefaultValue = (0, 0, 0))

Opens the specified File and reads the ODF Parameter of the given Name, under the Header of the given Block.
If it doesn't find the Parameter, it returns the DefaultValue. Also Returns a bool if it Found the specified Parameter or not.

string LoadFile(string Filename)

Loads the specified Filename as text and Returns that string. Useful for opening Text files, not so useful for any other types. Returns nil if it can't find the file.

bool WriteToFile(string Filename, string Text, bool Append = true)

Writes a text file to the Logs folder located under Documents\My Games\Battlezone Combat Commander\
Writes the string of Text to the specified Filename.
If Append is true, it adds to the existing file, if it is False it wipes the file and starts blank.
Returns true if it was successful, or false if it failed.

[econchump]

this is really great, thanks. makes me feel much more comfortable with tackling an AIP