Document Revised 2018-04-15
Covers Battlezone up to version 1.5.2.27u1
Covers Battlezone 98 Redux versions 2.1+
This document describes the global script utility functions available for user-created Lua mission scripts. They offer the same functionality that the original designers used when creating the single-player campaign, along with new functionality back-ported from Battlezone II: Combat Commander or added to fill notable gaps.
Version numbers appearing in [square brackets] indicate the earliest version that supports the value or function. While a script could check the version number, it's faster and easier to check if the value or function is nil.
The Lua scripting system defines some global variables that can be of use to user scripts.
Contains current build version (e.g. "1.5.2.27u1").
Battlezone 1.5 versions start with "1" and Battlezone 98 Redux versions start with "2".
Contains the index of the current language.
Contains the full name of the current language in all-caps:
"ENGLISH", "FRENCH", "GERMAN", "SPANISH", "ITALIAN", "PORTUGUESE", or "RUSSIAN"
Contains the two-letter language code of the current language:
"en", "fr", "de", "es", "it", "pt" or "ru"
Contains the most recently pressed game key (e.g. "Ctrl+Z")
The Lua scripting system calls these script-defined functions when various script events occur. LuaMission looks up the functions by name so they can have different functions assigned to them at runtime.
Called when loading state from a save game file, allowing the script to restore its state.
Data values returned from Save will be passed as parameters to Load in the same order they were returned. Load supports nil, boolean, handle, integer, number, string, vector, and matrix data types. It does not support function, thread, or arbitrary userdata types.
The console window will print the loaded values in human-readable format.
Called when saving state to a save game file, allowing the script to preserve its state.
Any values returned by this function will be passed as parameters to Load when loading the save game file. Save supports nil, boolean, handle, integer, number, string, vector, and matrix data types. It does not support function, thread, or arbitrary userdata types.
The console window will print the saved values in human-readable format.
Called when the mission starts for the first time.
Use this function to perform any one-time script initialization.
Called any time a game key is pressed.
Key is a string that consisting of zero or more modifiers (Ctrl, Shift, Alt) and a base key.
The base key for keys corresponding to a printable ASCII character is the upper-case version of that character.
The base key for other keys is the label on the keycap (e.g. PageUp, PageDown, Home, End, Backspace, and so forth).
Called once per frame after updating the network system and before simulating game objects.
This function performs most of the mission script's game logic.
Called after any game object is created.
Handle is the game object that was created.
This function will get a lot of traffic so it should not do too much work.
Called when a game object gets added to the mission
Handle is the game object that was added
This function is normally called for "important" game objects, and excludes things like Scrap pieces.
Called before a game object is deleted.
Handle is the game object to be deleted.
This function will get a lot of traffic so it should not do too much work.
Called when a player joins the session.
Players that join before the host launches trigger CreatePlayer just before the first Update.
Players that join joining after the host launches trigger CreatePlayer on entering the pre-game lobby.
This function gets called for the local player.
Called when a player starts sending state updates.
This indicates that a player has finished loaded and started simulating.
This function is not called for the local player.
Called when a player leaves the session.
Called when a script-defined message arrives.
This function should return true if it handled the message and false, nil, or none if it did not.
From is the network player id of the sender.
Type is an arbitrary one-character string indicating the script-defined message type.
Data values passed as parameters to Send will arrive as parameters to Receive in the same order they were sent. Receive supports nil, boolean, handle, integer, number, string, vector, and matrix data types. It does not support function, thread, or arbitrary userdata types.
Called for any in-game chat command that was not handled by the system, allowing script-defined commands.
This function should return true if it handled the command and false, nil, or none if it did not.
LuaMission breaks the command into
Command is the string immediately following the '/'. For example, the command for "/foo" is "foo".
Arguments arrive as a string parameter to Command. For example "/foo 1 2 3" would receive "1 2 3".
The Lua string library provides several functions that can split the string into separate items.
You can use string.match with captures if you have a specific argument list:
local foo, bar, baz = string.match(arguments, "(%g+) (%g+) (%g+)")
You can use string.gmatch, which returns an iterator, if you want to loop through arguments:
for arg in string.gmatch(arguments, "%g+") do ... end
Check the Lua patterns tutorial and patterns manual for more details.
These functions control audio messages, 2D sounds typically used for radio messages, voiceovers, and narration.
Audio messages use the Voice Volume setting from the Audio Options menu.
Repeat the last audio message.
Plays the given audio file, which must be an uncompressed RIFF WAVE (.WAV) file.
Returns an audio message handle.
Returns true if the audio message has stopped. Returns false otherwise.
Stops the given audio message.
Returns true if any audio message is playing. Returns false otherwise.
These functions control sound effects, either positional 3D sounds attached to objects or global 2D sounds.
Sound effects use the Effects Volume setting from the Audio Options menu.
Plays the given audio file, which must be an uncompressed RIFF WAVE (.WAV) file.
Specifying an object handle creates a positional 3D sound that follows the object as it moves and stops automatically when the object goes away. Otherwise, the sound plays as a global 2D sound.
Priority ranges from 0 to 100, with higher priorities taking precedence over lower priorities when there are not enough channels. The default priority is 50 if not specified.
Looping sounds will play forever until explicitly stopped with StopSound or the object to which it is attached goes away. Non-looping sounds will play once and stop. The default is non-looping if not specified.
Volume ranges from 0 to 100, with 0 being silent and 100 being maximum volume. The default volume is 100 if not specified.
Rate overrides the playback rate of the sound file, so a value of 22050 would cause a sound file recorded at 11025 Hz to play back twice as fast. The rate defaults to the file's native rate if not specified.
Stops the sound using the given filename and associated with the given object. Use a handle of none or nil to stop a global 2D sound.
These functions create, manipulate, and query game objects (vehicles, buildings, people, powerups, and scrap) and return or take as a parameter a game object handle.
Object handles are always safe to use, even if the game object itself is missing or destroyed.
Returns the handle of the game object with the given label. Returns nil if none exists.
Creates a game object with the given odf name and team number at the location of a game object.
Returns the handle of the created object if it created one. Returns nil if it failed.
Creates a game object with the given odf name and team number at a point on the named path. It uses the start of the path if no point is given.
Returns the handle of the created object if it created one. Returns nil if it failed.
Creates a game object with the given odf name and team number at the given position vector.
Returns the handle of the created object if it created one. Returns nil if it failed.
Creates a game object with the given odf name and team number with the given transform matrix.
Returns the handle of the created object if it created one. Returns nil if it failed.
Removes the game object with the given handle.
Returns true if the game object's odf name matches the given odf name. Returns false otherwise.
Returns the odf name of the game object. Returns nil if none exists.
Returns the base config of the game object which determines what VDF/SDF model it uses. Returns nil if none exists.
Returns the label of the game object (e.g. "avtank0_wingman"). Returns nil if none exists.
Set the label of the game object (e.g. "tank1").
Note: this function was misspelled as SettLabel in 1.5. It can be renamed compatibly with a short snippet of code at the top of the mission script:
SetLabel = SetLabel or SettLabel
Returns the four-character class signature of the game object (e.g. "WING"). Returns nil if none exists.
Returns the class label of the game object (e.g. "wingman"). Returns nil if none exists.
Returns the numeric class identifier of the game object. Returns nil if none exists.
Looking up the class id number in the ClassId table will convert it to a string. Looking up the class id string in the ClassId table will convert it back to a number.
This is a global table that converts between class identifier numbers and class identifier names. For example, ClassId.SCRAP or ClassId["SCRAP"] returns the class identifier number (7) for the Scrap class; ClassId[7] returns the class identifier name ("SCRAP") for class identifier number 7. For maintainability, always use this table instead of raw class identifier numbers.
Available class identifiers: NONE, HELICOPTER, STRUCTURE1, POWERUP, PERSON, SIGN, VEHICLE, SCRAP, BRIDGE, FLOOR, STRUCTURE2, SCROUNGE, SPINNER, HEADLIGHT_MASK, EYEPOINT, COM, WEAPON, ORDNANCE, EXPLOSION, CHUNK, SORT_OBJECT, NONCOLLIDABLE, VEHICLE_GEOMETRY, STRUCTURE_GEOMETRY, WEAPON_GEOMETRY, ORDNANCE_GEOMETRY, TURRET_GEOMETRY, ROTOR_GEOMETRY, NACELLE_GEOMETRY, FIN_GEOMETRY, COCKPIT_GEOMETRY, WEAPON_HARDPOINT, CANNON_HARDPOINT, ROCKET_HARDPOINT, MORTAR_HARDPOINT, SPECIAL_HARDPOINT, FLAME_EMITTER, SMOKE_EMITTER, DUST_EMITTER, PARKING_LOT
Returns the one-letter nation code of the game object (e.g. "a" for American, "b" for Black Dog, "c" for Chinese, and "s" for Soviet).
The nation code is usually but not always the same as the first letter of the odf name. The ODF file can override the nation in the [GameObjectClass] section, and player.odf is a hard-coded exception that uses "a" instead of "p".
Returns true if the game object exists. Returns false otherwise.
Returns true if the game object exists and (if the object is a vehicle) controlled. Returns false otherwise.
Returns true if the game object exists and (if the object is a vehicle) controlled and piloted. Returns false otherwise.
Returns true if the game object exists and is a vehicle. Returns false otherwise.
Returns true if the game object exists and is a building. Returns false otherwise.
Returns true if the game object exists and is a person. Returns false otherwise.
Returns true if the game object exists and has less health than the threshold. Returns false otherwise.
Returns true if the game object was recycled by a Construction Rig on the given team.
These functions get and set team number. Team 0 is the neutral or environment team.
Returns the game object's team number.
Sets the game object's team number.
Returns the game object's perceived team number (as opposed to its real team number).
The perceived team will differ from the real team when a player enters an empty enemy vehicle without being seen until they attack something.
Set the game object's perceived team number (as opposed to its real team number).
Units on the game object's perceived team will treat it as friendly until it "blows its cover" by attacking, at which point it will revert to its real team.
Units on the game object's real team will treat it as friendly regardless of its perceived team.
These function get and set a unit's target.
Sets the local player's target.
Returns the local player's target. Returns nil if it has none.
Sets the game object's target.
Returns the game object's target. Returns nil if it has none.
These functions get and set owner. The default owner for a game object is the game object that created it.
Sets the game object's owner.
Returns the game object's owner. Returns nil if it has none.
These functions get and set vehicle pilot class.
Sets the vehicle's pilot class to the given odf name. This does nothing useful for non-vehicle game objects. An odf name of nil resets the vehicle to the default assignment based on nation.
Returns the odf name of the vehicle's pilot class. Returns nil if none exists.
These functions get and set position and orientation.
Teleports the game object to a point on the named path. It uses the start of the path if no point is given.
Teleports the game object to the position vector.
Teleports the game object to the position of the transform matrix.
Returns the game object's position vector. Returns nil if none exists.
Returns the path point's position vector. Returns nil if none exists.
Returns the game object's front vector. Returns nil if none exists.
Teleports the game object to the given transform matrix.
Returns the game object's transform matrix. Returns nil if none exists.
These functions get and set linear velocity.
Returns the game object's linear velocity vector. Returns nil if none exists.
Sets the game object's angular velocity vector.
These functions get and set angular velocity.
Returns the game object's angular velocity vector. Returns nil if none exists.
Sets the game object's angular velocity vector.
These functions help generate position values close to a center point.
Returns a ground position offset from the center by the radius in a direction controlled by the angle.
If no radius is given, it uses a default radius of zero.
If no angle is given, it uses a default angle of zero.
An angle of zero is +X (due east), pi * 0.5 is +Z (due north), pi is -X (due west), and pi * 1.5 is -Z (due south).
Returns a ground position in a ring around the center between minradius and maxradius with roughly the same terrain height as the terrain height at the center.
This is good for scattering spawn positions around a point while excluding positions that are too high or too low.
If no radius is given, it uses the default radius of zero.
These functions query a game object for information about ordnance hits.
Returns who scored the most recent hit on the game object. Returns nil if none exists.
Returns the last time an enemy shot the game object.
Returns the last time a friend shot the game object.
These functions control and query alliances between teams.
The team manager assigns each player a separate team number, starting with 1 and going as high as 15. Team 0 is the neutral "environment" team.
Unless specifically overridden, every team is friendly with itself, neutral with team 0, and hostile to everyone else.
Sets team alliances back to default.
Sets whether team alliances are locked. Locking alliances prevents players from allying or un-allying, preserving alliances set up by the mission script.
Makes the two teams allies of each other.
This function affects both teams so Ally(1, 2) and Ally(2, 1) produces the identical results, unlike the "half-allied" state created by the "ally" game key.
Makes the two teams enemies of each other.
This function affects both teams so UnAlly(1, 2) and UnAlly(2, 1) produces the identical results, unlike the "half-enemy" state created by the "unally" game key.
Returns true if team1 considers team2 an ally. Returns false otherwise.
Due to the possibility of player-initiated "half-alliances", IsTeamAllied(team1, team2) might not return the same result as IsTeamAllied(team2, team1).
Returns true if game object "me" considers game object "him" an ally. Returns false otherwise.
Due to the possibility of player-initiated "half-alliances", IsAlly(me, him) might not return the same result as IsAlly(him, me).
These functions control objective markers.
Objectives are visible to all teams from any distance and from any direction, with an arrow pointing to off-screen objectives. There is currently no way to make team-specific objectives.
Sets the game object as an objective to all teams.
Sets the game object back to normal.
Gets the game object's visible name.
Sets the game object's visible name.
Sets the game object's visible name. This function is effectively an alias for SetObjectiveName.
These functions measure and return the distance between a game object and a reference point.
Returns the distance in meters between the two game objects.
Returns the distance in meters between the game object and a point on the path. It uses the start of the path if no point is given.
Returns the distance in meters between the game object and a position vector.
Returns the distance in meters between the game object and the position of a transform matrix.
Returns true if the units are closer than the given distance of each other. Returns false otherwise.
(This function is equivalent to GetDistance (h1, h2) < d)
Returns true if the bounding spheres of the two game objects are within the specified tolerance. The default tolerance is 1.3 meters if not specified.
These functions find and return the game object of the requested type closest to a reference point.
Returns the game object closest to the given game object. Returns nil if none exists.
Returns the game object closest to a point on the path. It uses the start of the path if no point is given. Returns nil if none exists.
Returns the game object closest to the position vector. Returns nil if none exists.
Returns the game object closest to the position of the transform matrix. Returns nil if none exists.
Returns the craft closest to the given game object. Returns nil if none exists.
Returns the craft closest to a point on the path. It uses the start of the path if no point is given. Returns nil if none exists.
Returns the vehicle closest to the position vector. Returns nil if none exists.
Returns the vehicle closest to the position of the transform matrix. Returns nil if none exists.
Returns the building closest to the given game object. Returns nil if none exists.
Returns the building closest to a point on the path. It uses the start of the path if no point is given. Returns nil if none exists.
Returns the building closest to the position vector. Returns nil if none exists.
Returns the building closest to the position of the transform matrix. Returns nil if none exists.
Returns the enemy closest to the given game object. Returns nil if none exists.
Returns the enemy closest to a point on the path. It uses the start of the path if no point is given. Returns nil if none exists.
Returns the enemy closest to the position vector. Returns nil if none exists.
Returns the enemy closest to the position of the transform matrix. Returns nil if none exists.
Returns the friend closest to the given game object. Returns nil if none exists.
Returns the friend closest to a point on the path. It uses the start of the path if no point is given. Returns nil if none exists.
Returns the friend closest to the position vector. Returns nil if none exists.
Returns the friend closest to the position of the transform matrix. Returns nil if none exists.
Returns the craft or person on the given team closest to the given game object. Returns nil if none exists.
Returns the craft or person on the given team closest to a point on the path. It uses the start of the path if no point is given. Returns nil if none exists.
Returns the craft or person on the given team closest to the position of the transform matrix. Returns nil if none exists.
Returns the craft or person on the given team closest to the position vector. Returns nil if none exists.
Returns how many objects with the given team and odf name are closer than the given distance.
These functions return iterator functions for use with Lua's "for <variable> in <expression> do ... end" form. For example: "for h in AllCraft() do print(h, GetLabel(h)) end" will print the game object handle and label of every craft in the world.
Enumerates game objects within the given distance of the game object.
Enumerates game objects within the given distance of the path point. It uses the start of the path if no point is given.
Enumerates game objects within the given distance of the position vector.
Enumerates game objects within the given distance of the transform matrix.
Enumerates all game objects.
Use this function sparingly at runtime since it enumerates all game objects, including every last piece of scrap. If you're specifically looking for craft, use AllCraft() instead.
Enumerates all craft.
Enumerates all game objects currently selected by the local player.
Enumerates all game objects marked as objectives.
These functions remove scrap, either to reduce the global game object count or to remove clutter around a location.
While the global scrap count is above the limit, remove the oldest scrap piece. It no limit is given, it uses the default limit of 300.
Clear all scrap within the given distance of a game object.
Clear all scrap within the given distance of a point on the path. It uses the start of the path if no point is given.
Clear all scrap within the given distance of a position vector.
Clear all scrap within the given distance of the position of a transform matrix.
These functions look up game objects in team slots.
This is a global table that converts between team slot numbers and team slot names. For example, TeamSlot.PLAYER or TeamSlot["PLAYER"] returns the team slot (0) for the player; TeamSlot[0] returns the team slot name ("PLAYER") for team slot 0. For maintainability, always use this table instead of raw team slot numbers.
Available slots: UNDEFINED, PLAYER, RECYCLER, FACTORY, ARMORY, CONSTRUCT, MIN_OFFENSE, MAX_OFFENSE, MIN_DEFENSE, MAX_DEFENSE, MIN_UTILITY, MAX_UTILITY, MIN_BEACON, MAX_BEACON, MIN_POWER, MAX_POWER, MIN_COMM, MAX_COMM, MIN_REPAIR, MAX_REPAIR, MIN_SUPPLY, MAX_SUPPLY, MIN_SILO, MAX_SILO, MIN_BARRACKS, MAX_BARRACKS, MIN_GUNTOWER, MAX_GUNTOWER.
Slots starting with MIN_ and MAX_ represent the lower and upper bound of a range of slots.
Get the game object in the specified team slot.
It uses the local player team if no team is given.
Returns the game object controlled by the player on the given team. Returns nil if none exists.
It uses the local player team if no team is given.
Returns the Recycler on the given team. Returns nil if none exists.
It uses the local player team if no team is given.
Returns the Factory on the given team. Returns nil if none exists.
It uses the local player team if no team is given.
Returns the Armory on the given team. Returns nil if none exists.
It uses the local player team if no team is given.
Returns the Constructor on the given team. Returns nil if none exists.
It uses the local player team if no team is given.
These functions get and set pilot counts for a team.
Adds pilots to the team's pilot count, clamped between zero and maximum count.
Returns the new pilot count.
Sets the team's pilot count, clamped between zero and maximum count.
Returns the new pilot count.
Returns the team's pilot count.
Adds pilots to the team's maximum pilot count.
Returns the new pilot count.
Sets the team's maximum pilot count.
Returns the new pilot count.
Returns the team's maximum pilot count.
These functions get and set scrap values for a team.
Adds to the team's scrap count, clamped between zero and maximum count.
Returns the new scrap count.
Sets the team's scrap count, clamped between zero and maximum count.
Returns the new scrap count.
Returns the team's scrap count.
Adds to the team's maximum scrap count.
Returns the new maximum scrap count.
Sets the team's maximum scrap count.
Returns the new maximum scrap count.
Returns the team's maximum scrap count.
These functions control deployable craft (such as Turret Tanks or Producer units).
Returns true if the game object is a deployed craft. Returns false otherwise.
Tells the game object to deploy.
These functions access selection state (i.e. whether the player has selected a game object)
Returns true if the game object is selected. Returns false otherwise.
The "mission critical" property indicates that a game object is vital to the success of the mission and disables the "Pick Me Up" and "Recycle" commands that (eventually) cause IsAlive() to report false.
Returns true if the game object is marked as mission-critical. Returns false otherwise.
Sets the game object's mission-critical status.
If critical is true or not specified, the object is marked as mission-critical. Otherwise, the object is marked as not mission critical.
These functions access unit weapons and damage.
Sets what weapons the unit's AI process will use.
To calculate the mask value, add up the values of the weapon hardpoint slots you want to enable.
weaponHard1: 1 weaponHard2: 2 weaponHard3: 4 weaponHard4: 8 weaponHard5: 16
Gives the game object the named weapon in the given slot. If no slot is given, it chooses a slot based on hardpoint type and weapon priority like a weapon powerup would. If the weapon name is empty, nil, or blank and a slot is given, it removes the weapon in that slot.
Returns true if it succeeded. Returns false otherwise.
Returns the odf name of the weapon in the given slot on the game object. Returns nil if the game object does not exist or the slot is empty.
For example, an "avtank" game object would return "gatstab" for index 0 and "gminigun" for index 1.
Tells the game object to fire at the given target.
Applies damage to the game object.
These function report various global time values.
Returns the elapsed time in seconds since the start of the mission.
Returns the simulation time step in seconds.
Returns the current system time in milliseconds. This is mostly useful for performance profiling.
These functions control general mission properties like strategic AI and mission flow
Enables (or disables) strategic AI control for a given team. As of version 1.5.2.7, mission scripts must enable AI control for any team that intends to use an AIP.
IMPORTANT SAFETY TIP: only call this function from the "root" of the Lua mission script! The strategic AI gets set up shortly afterward and attempting to use SetAIControl later will crash the game.
Returns true if a given team is AI controlled. Returns false otherwise.
Unlike SetAIControl, this function may be called at any time.
Returns the current AIP for the team. It uses team 2 if no team number is given.
Switches the team's AI plan. It uses team 2 if no team number is given.
Fails the mission after the given time elapses. If supplied with a filename (usually a .des), it sets the failure message to text from that file.
Succeeds the mission after the given time elapses. If supplied with a filename (usually a .des), it sets the success message to text from that file.
These functions control the objective panel visible at the right of the screen.
Clears all objective messages.
Adds an objective message with the given name and properties.
The message defaults to white if no color is given. The color may be "black", "dkgrey", "grey", "white", "blue", "dkblue", "green", "dkgreen", "yellow", "dkyellow", "red", or "dkred"; the value is case-insensitive.
The message lasts 8 seconds if no duration is given.
The message text defaults to the contents of of the file with the specified name (usually an .otf).
Script-supplied message text is only available in version 2.0.121.1 or higher.
Updates the objective message with the given name. If no objective exists with that name, it does nothing.
The message defaults to white if no color is given. The color may be "black", "dkgrey", "grey", "white", "blue", "dkblue", "green", "dkgreen", "yellow", "dkyellow", "red", or "dkred"; the value is case-insensitive.
The message lasts 8 seconds if no duration is given.
The message text will keep its previous value if no text is given.
Script-supplied message text is only available in version 2.0.121.1 or higher.
Removes the objective message with the given file name. Messages after the removed message will be moved up to fill the vacancy. If no objective exists with that file name, it does nothing.
These functions control the large timer at the top of the screen.
Starts the cockpit timer counting down from the given time. If a warn time is given, the timer will turn yellow when it reaches that value. If an alert time is given, the timer will turn red when it reaches that value. All time values are in seconds.
The start time can be up to 35999, which will appear on-screen as 9:59:59. If the remaining time is an hour or less, the timer will show only minutes and seconds.
Starts the cockpit timer counting up from the given time. If a warn time is given, the timer will turn yellow when it reaches that value. If an alert time is given, the timer will turn red when it reaches that value. All time values are in seconds.
The on-screen timer will always show hours, minutes, and seconds The hours digit will malfunction after 10 hours.
Stops the cockpit timer.
Hides the cockpit timer.
Returns the current time in seconds on the cockpit timer.
These functions control the global earthquake effect.
Starts a global earthquake effect.
Changes the magnitude of an existing earthquake effect.
Important: note the inconsistent capitalization, which matches the internal C++ script utility functions.
Stops the global earthquake effect.
These functions get and set the looping type of a path.
Looking up the path type number in the PathType table will convert it to a string. Looking up the path type string in the PathType table will convert it to a number.
Changes the named path to the given path type.
Returns the type of the named path.
Changes the named path to one-way. Once a unit reaches the end of the path, it will stop.
Changes the named path to round-trip. Once a unit reaches the end of the path, it will follow the path backwards to the start and begin again.
Changes the named path to looping. Once a unit reaches the end of the path, it will continue along to the start and begin again.
Returns the number of points in the named path, or 0 if the path does not exist.
These functions treat a path as the boundary of a closed polygonal area.
Returns how many times the named path loops around the given game object.
Each full counterclockwise loop adds one and each full clockwise loop subtracts one.
Returns how many times the named path loops around the given position.
Each full counterclockwise loop adds one and each full clockwise loop subtracts one.
Returns how many times the named path loops around the position of the given transform.
Each full counterclockwise loop adds one and each full clockwise loop subtracts one.
Returns true if the given game object is inside the area bounded by the named path. Returns false otherwise.
This function is equivalent to
GetWindingNumber( path, h ) ~= 0
Returns true if the given position is inside the area bounded by the named path. Returns false otherwise.
This function is equivalent to
GetWindingNumber( path, position ) ~= 0
Returns true if the position of the given transform is inside the area bounded by the named path. Returns false otherwise.
This function is equivalent to
GetWindingNumber( path, transform ) ~= 0
These functions send commands to units or query their command state.
This is a global table that converts between command numbers and command names. For example, AiCommand.GO or AiCommand["GO"] returns the command number (3) for the "go" command; AiCommand[3] returns the command name ("GO") for command number 3. For maintainability, always use this table instead of raw command numbers.
Available commands: NONE, SELECT, STOP, GO, ATTACK, FOLLOW, FORMATION, PICKUP, DROPOFF, NO_DROPOFF, GET_REPAIR, GET_RELOAD, GET_WEAPON, GET_CAMERA, GET_BOMB, DEFEND, GO_TO_GEYSER, RESCUE, RECYCLE, SCAVENGE, HUNT, BUILD, PATROL, STAGE, SEND, GET_IN, LAY_MINES, CLOAK [2.1+], DECLOAK [2.1+].
Returns true if the game object can be commanded. Returns false otherwise.
Returns true if the game object is a producer that can build at the moment. Returns false otherwise.
Returns true if the game object is a producer and currently busy. Returns false otherwise.
Returns the current command for the game object. Looking up the command number in the AiCommand table will convert it to a string. Looking up the command string in the AiCommand table will convert it back to a number.
Returns the target of the current command for the game object. Returns nil if it has none.
Gets the independence of a unit.
Sets the independence of a unit. 1 (the default) lets the unit take initiative (e.g. attack nearby enemies), while 0 prevents that.
Commands the unit using the given parameters. Be careful with this since not all commands work with all units and some have strict requirements on their parameters.
"Command" is the command to issue, normally chosen from the global AiCommand table (e.g. AiCommand.GO).
"Priority" is the command priority; a value of 0 leaves the unit commandable by the player while the default value of 1 makes it uncommandable.
"Who" is an optional target game object.
"Where" is an optional destination, and can be a matrix (transform), a vector (position), or a string (path name).
"When" is an optional absolute time value only used by command AiCommand.STAGE.
"Param" is an optional odf name only used by command AiCommand.BUILD.
Commands the unit to attack the given target.
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the unit to go to the named path.
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the unit to go to the given target
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the unit to go to the given position vector
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the unit to go to the position of the given transform matrix
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the unit to lay mines at the named path; only minelayer units support this.
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the unit to lay mines at the given position vector
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the unit to lay mines at the position of the transform matrix
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the unit to follow the given target.
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Returns true if the unit is currently following the given target.
Commands the unit to defend its current location.
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the unit to defend the given target.
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the unit to stop at its current location.
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the unit to patrol along the named path. This is equivalent to Goto with an independence of 1.
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the unit to retreat to the named path. This is equivalent to Goto with an independence of 0.
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the unit to retreat to the given target. This is equivalent to Goto with an independence of 0.
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the pilot to get into the target vehicle.
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the unit to pick up the target object. Deployed units pack up (ignoring the target), scavengers pick up scrap, and tugs pick up and carry objects.
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the unit to drop off at the named path. Tugs drop off their cargo and Construction Rigs build the selected item at the location using their current facing.
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the unit to drop off at the position vector. Tugs drop off their cargo and Construction Rigs build the selected item at the location using their current facing.
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the unit to drop off at the position of the transform matrix. Tugs drop off their cargo and Construction Rigs build the selected item with the facing of the transform matrix.
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands a producer to build the given odf name. The Armory and Construction Rig need an additional Dropoff to give them a location to build but first need at least one simulation update to process the Build.
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands a producer to build the given odf name at the location of the target game object. A Construction Rig will build at the location and an Armory will launch the item to the location. Other producers will ignore the location.
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands a producer to build the given odf name at the named path. A Construction Rig will build at the location and an Armory will launch the item to the location. Other producers will ignore the location.
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands a producer to build the given odf name at the position vector. A Construction Rig will build at the location with their current facing and an Armory will launch the item to the location. Other producers will ignore the location.
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands a producer to build the given odf name at the transform matrix. A Construction Rig will build at the location with the facing of the transform and an Armory will launch the item to the location. Other producers will ignore the location.
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the unit to follow the given target closely. This function is equivalent to SetCommand(me, AiCommand.FORMATION, priority, him).
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the unit to hunt for targets autonomously. This function is equivalent to SetCommand(me, AiCommand.HUNT, priority).
Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
These functions query Tug and Cargo.
Returns true if the unit is a tug carrying cargo.
Returns the handle of the cargo if the unit is a tug carrying cargo. Returns nil otherwise.
Returns the handle of the tug carrying the object. Returns nil if not carried.
These functions control the pilot of a vehicle.
Commands the vehicle's pilot to eject.
Commands the vehicle's pilot to hop out.
Kills the vehicle's pilot as if sniped.
Removes the vehicle's pilot cleanly.
Returns the vehicle that the pilot most recently hopped out of.
These functions get and set health values on a game object.
Returns the fractional health of the game object between 0 and 1.
Returns the current health value of the game object.
Returns the maximum health value of the game object.
Sets the current health of the game object.
Sets the maximum health of the game object.
Adds to the current health of the game object.
Sets the unit's current health to maximum.
These functions get and set ammo values on a game object.
Returns the fractional ammo of the game object between 0 and 1.
Returns the current ammo value of the game object.
Returns the maximum ammo value of the game object.
Sets the current ammo of the game object.
Sets the maximum ammo of the game object.
Adds to the current ammo of the game object.
Sets the unit's current ammo to maximum.
These functions control the cinematic camera for in-engine cut scenes (or "cineractives" as the Interstate '76 team at Activision called them).
Starts the cinematic camera and disables normal input.
Always returns true.
Moves a cinematic camera along a path at a given height and speed while looking at a target game object.
Returns true when the camera arrives at its destination. Returns false otherwise.
Moves a cinematic camera long a path at a given height and speed while looking along the path direction.
Returns true when the camera arrives at its destination. Returns false otherwise.
Returns true when the camera arrives at its destination. Returns false otherwise.
Offsets a cinematic camera from a base game object while looking at a target game object. The right, up, and forward offsets are in centimeters.
Returns true if the base or handle game object does not exist. Returns false otherwise.
Finishes the cinematic camera and enables normal input.
Always returns true.
Returns true if the player canceled the cinematic. Returns false otherwise.
Returns true if the game object inspected by the info display matches the given odf name.
LuaMission currently has limited network support, but can detect if the mission is being run in multiplayer and if the local machine is hosting.
Returns true if the game is a network game. Returns false otherwise.
Returns true if the local machine is hosting a network game. Returns false otherwise.
Sets the game object as local to the machine the script is running on, transferring ownership from its original owner if it was remote. Important safety tip: only call this on one machine at a time!
Returns true if the game is local to the machine the script is running on. Returns false otherwise.
Returns true if the game object is remote to the machine the script is running on. Returns false otherwise.
Adds a system text message to the chat window on the local machine.
Send a script-defined message across the network.
To is the player network id of the recipient. None, nil, or 0 broadcasts to all players.
Type is a one-character string indicating the script-defined message type.
Other parameters will be sent as data and passed to the recipient's Receive function as parameters. Send supports nil, boolean, handle, integer, number, string, vector, and matrix data types. It does not support function, thread, or arbitrary userdata types.
The sent packet can contain up to 244 bytes of data (255 bytes maximum for an Anet packet minus 6 bytes for the packet header and 5 bytes for the reliable transmission header)
| Type | Bytes | |
|---|---|---|
| nil | 1 | |
| boolean | 1 | |
| handle | invalid (zero) | 1 |
| valid (nonzero) | 1 + sizeof(int) = 5 | |
| number | zero | 1 |
| char (integer -128 to 127) | 1 + sizeof(char) = 2 | |
| short (integer -32768 to 32767) | 1 + sizeof(short) = 3 | |
| int (integer) | 1 + sizeof(int) = 5 | |
| double (non-integer) | 1 + sizeof(double) = 9 | |
| string | length < 31 | 1 + length |
| length >= 31 | 2 + length | |
| table | count < 31 | 1 + count + size of keys and values |
| count >= 31 | 2 + count + size of keys and values | |
| userdata | VECTOR_3D | 1 + sizeof(VECTOR_3D) = 13 |
| MAT_3D | 1 + sizeof(REDUCED_MAT) = 12 | |
These functions read values from an external ODF, INI, or TRN file.
Opens the named file as an ODF. If the file name has no extension, the function will append ".odf" automatically.
If the file is not already open, the function reads in and parses the file into an internal database. If you need to read values from it relatively frequently, save the handle into a global variable to prevent it from closing.
Returns the file handle if it succeeded. Returns nil if it failed.
Reads a boolean value from the named label in the named section of the ODF file. Use a nil section to read labels that aren't in a section.
It considers values starting with 'Y', 'y', 'T', 't', or '1' to be true and value starting with 'N', 'n', 'F', 'f', or '0' to be false. Other values are considered undefined.
If a value is not found or is undefined, it uses the default value. If no default value is given, the default value is false.
Returns the value and whether the value was found.
Reads an integer value from the named label in the named section of the ODF file. Use nil as the section to read labels that aren't in a section.
If no value is found, it uses the default value. If no default value is given, the default value is 0.
Returns the value and whether the value was found.
Reads a floating-point value from the named label in the named section of the ODF file. Use nil as the section to read labels that aren't in a section.
If no value is found, it uses the default value. If no default value is given, the default value is 0.0.
Returns the value and whether the value was found.
Reads a string value from the named label in the named section of the ODF file. Use nil as the section to read labels that aren't in a section.
If a value is not found, it uses the default value. If no default value is given, the default value is nil.
Returns the value and whether the value was found.
These functions return height and normal from the terrain height field.
Returns the terrain height and normal vector at the location of the game object.
Returns the terrain height and normal vector at a point on the named path. It uses the start of the path if no point is given.
Returns the terrain height and normal vector at the position vector.
Returns the terrain height and normal vector at the position of the transform matrix.
These functions return height and normal from the terrain height field and the upward-facing polygons of any entities marked as floor owners.
Returns the floor height and normal vector at the location of the game object.
Returns the floor height and normal vector at a point on the named path. It uses the start of the path if no point is given.
Returns the floor height and normal vector at the position vector.
Returns the floor height and normal vector at the position of the transform matrix.
Returns the name of the BZN file for the map. This can be used to generate an ODF name for mission settings.
Returns the name of the TRN file for the map. This can be used with OpenODF() to read values from the TRN file.
Returns the contents of the named file as a string, or nil if the file could not be opened.
Starts a full screen color fade.
Ratio sets the opacity, with 0.0 transparent and 1.0 almost opaque
Rate sets how fast the opacity decreases over time.
R, G, and B set the color components and range from 0 to 255
This is a custom userdata representing a position or direction. It has three number components: x, y, and z.
Returns a vector whose components have the given number values. If no value is given for a component, the default value is 0.0.
Returns the dot product between vectors a and b.
Equivalent to a.x * b.x + a.y * b.y + a.z * b.z.
Returns the cross product between vectors a and b.
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).
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).
Returns the length of the vector.
Equivalent to sqrt(v.x2 + v.y2 + v.z2).
Returns the squared length of the vector.
Equivalent to v.x2 + v.y2 + v.z2.
Returns the 2D distance between vectors a and b.
Equivalent to sqrt((b.x - a.x)2 + (b.z - a.z)2).
Returns the squared 2D distance of the vector.
Equivalent to (b.x - a.x)2 + (b.z - a.z)2.
Returns the 3D distance between vectors a and b.
Equivalent to sqrt((b.x - a.x)2 + (b.y - a.y)2 + (b.z - a.z)2).
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.
Negate the vector.
Equivalent to SetVector(-vector.x, -vector.y, -vector.z).
Add two vectors.
Equivalent to SetVector(vector1.x + vector2.x, vector1.y + vector2.y, vector1.z + vector2.z).
Subtract two vectors.
Equivlent to SetVector(vector1.x - vector2.x, vector1.y - vector2.y, vector1.z - vector2.z).
Multiply a number by a vector.
Equivalent to SetVector( number * vector.x, number * vector.y, number * vector.z).
Multiply a vector by a number.
Equivalent to SetVector(vector.x * number, vector.y * number, vector.z * number).
Multiply two vectors.
Equivlent to SetVector(vector1.x * vector2.x, vector1.y * vector2.y, vector1.z * vector2.z)
Divide a number by a vector.
Equivalent to SetVector( number / vector.x, number / vector.y, number / vector.z).
Divide a vector by a number.
Equivalent to SetVector(vector.x / number, vector.y / number, vector.z / number).
Divide two vectors.
Equivlent to SetVector(vector1.x / vector2.x, vector1.y / vector2.y, vector1.z / vector2.z)
Check if two vectors are equal.
Check if two vectors are not equal.
This is a custom userdata representing an orientation and position in space. It has four vector components (right, up, front, and posit) sharing space with twelve number components (right_x, right_y, right_z, up_x, up_y, up_z, front_x, front_y, front_z, posit_x, posit_y, posit_z).
Returns a matrix whose components have the given number values. If no value is given for a component, the default value is zero. Be careful with this since it's easy to build a non-orthonormal matrix that will break all kinds of built-in assumptions.
Global value representing the identity matrix.
Equivalent to SetMatrix(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0).
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.
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, 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.
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.
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.
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.
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.
Multiply two matrices.
Transform a vector by a matrix.
These functions control the Portal building introduced in The Red Odyssey expansion.
Sets the specified Portal direction to "out", indicated by a blue visual effect while active.
Sets the specified Portal direction to "in", indicated by an orange visual effect while active.
Deactivates the specified Portal, stopping the visual effect.
Activates the specified Portal, starting the visual effect.
Returns true if the specified Portal direction is "in". Returns false otherwise.
Returns true if the specified Portal is active. Returns false otherwise.
Important: note the capitalization!
Creates a game object with the given odf name and team number at the location of a portal.
The object is created at the location of the visual effect and given a 50 m/s initial velocity.
These functions control the cloaking state of craft capable of cloaking.
Makes the specified unit cloak if it can.
Note: unlike SetCommand(h, AiCommand.CLOAK), this does not change the unit's current command.
Makes the specified unit de-cloak if it can.
Note: unlike SetCommand(h, AiCommand.DECLOAK), this does not change the unit's current command.
Instantly sets the unit as cloaked (with no fade out).
Instant sets the unit as uncloaked (with no fade in).
Returns true if the unit is cloaked. Returns false otherwise
Enable or disable cloaking for a specified cloaking-capable unit.
Note: this does not grant a non-cloaking-capable unit the ability to cloak.
Enable or disable cloaking for all cloaking-capable units.
Note: this does not grant a non-cloaking-capable unit the ability to cloak.
These functions hide and show game objects. When hidden, the object is invisible (similar to Phantom VIR and cloak) and undetectable on radar (similar to RED Field and cloak). The effect is similar to but separate from cloaking. For the most part, AI units ignore the hidden state.
Hides a game object.
Un-hides a game object.
These functions create explosions at a specified location. They do not return a handle because explosions are not game objects and thus not visible to the scripting system.
Creates an explosion with the given odf name at the location of a game object.
Creates an explosion with the given odf name at the start of the named path.
Creates an explosion with the given odf name at the given position vector.
Creates an explosion with the given odf name with the given transform matrix.