ScriptUtils
----BZ98R ScriptUtils Stub.
Stubs for ScriptUtils LDoc
Type declarations
A handle to a game object. This is a unique identifier for the object in the game world.
ODF ParameterDB
A handle to an audio message.
Team Number
Objective Color Label
TeamSlot Integer
The Lua scripting system defines some global variables that can be of use to user scripts.
Contains current build version
Battlezone 1.5 versions start with "1"
Battlezone 98 Redux versions start with "2"
For example "1.5.2.27u1" or "2.2.301"
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")
Contains the index of the current language.
- English
- French
- German
- Spanish
- Italian
- Portuguese
- Russian
These are functions you are expected to implement in your script. The game will call these functions if they exist for game logic events.
TYPE: function_callback
SPECIAL: field
GLYPH: glyph/tablericons/function
----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. Note that many game object functions may not work properly here. #callback
TYPE: function_callback
SPECIAL: field
GLYPH: glyph/tablericons/function
----Called when a player joins the game world. #callback
TYPE: function_callback
SPECIAL: field
GLYPH: glyph/tablericons/function
----Command #callback
TYPE: function_callback
SPECIAL: field
GLYPH: glyph/tablericons/function
----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. Note that many game object functions may not work properly here. #callback
TYPE: function_callback
SPECIAL: field
GLYPH: glyph/tablericons/function
----Called when a player joins the game world. #callback
TYPE: function_callback
SPECIAL: field
GLYPH: glyph/tablericons/function
----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. Note: This is called after the object is largely removed from the game, so most Get functions won't return a valid value. #callback
TYPE: function_callback
SPECIAL: field
GLYPH: glyph/tablericons/function
----Called when a player leaves the game world. #callback
TYPE: function_callback
SPECIAL: field
GLYPH: glyph/tablericons/function
----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). #callback
TYPE: function_callback
SPECIAL: field
GLYPH: glyph/tablericons/function
----Load is called when you load a game, or when a Resync is loaded. #callback
TYPE: function_callback
SPECIAL: field
GLYPH: glyph/tablericons/function
----Receive #callback
TYPE: function_callback
SPECIAL: field
GLYPH: glyph/tablericons/function
----Save is called when you save a game #callback
TYPE: function_callback
SPECIAL: field
GLYPH: glyph/tablericons/function
----Called when the mission starts for the first time. Use this function to perform any one-time script initialization. #callback
TYPE: function_callback
SPECIAL: field
GLYPH: glyph/tablericons/function
----Called once per tick after updating the network system and before simulating game objects. This function performs most of the mission script's game logic. #callback
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.
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.
Returns true if any audio message is playing. Returns false otherwise.
Repeat the last audio message.
Stops the given audio message.
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.
TYPE: UNK_enum ClassId
SPECIAL: field
GLYPH: bi bi-list-ul
----Position vector, transform matrix, Object, or path name.
If the location is a path this is the path point index, defaults to 0.
Creates a game object with the given odf name, team number, and location.
Returns the base config of the game object which determines what VDF/SDF model it uses. 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.
Returns the class label of the game object (e.g. "wingman"). Returns nil if none exists.
Returns the four-character class signature of the game object (e.g. "WING"). Returns nil if none exists.
Returns the handle of the game object with the given label. Returns nil if none exists.
Returns the label of the game object (e.g. "avtank0_wingman"). Returns nil if none exists.
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 the odf name of the game object. Returns nil if none exists.
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 building. Returns false otherwise.
Returns true if the game object exists and is a vehicle. Returns false otherwise.
float
Returns true if the game object exists and has less health than the threshold. Returns false otherwise.
Returns true if the game object's odf name matches the given odf name. Returns false otherwise.
Returns true if the game object exists and is a person. Returns false otherwise.
Returns true if the game object was recycled by a Construction Rig on the given team.
Returns true if the game object exists. Returns false otherwise.
Removes the game object with the given handle.
These functions get and set team number. Team 0 is the neutral or environment team.
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.
Returns the game object's team number.
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.
Returns the game object's target. Returns nil if it has none.
Returns the local player's target. Returns nil if it has none.
Sets the game object's target.
These functions get and set owner. The default owner for a game object is the game object that created it.
Returns the game object's owner. Returns nil if it has none.
These functions get and set vehicle pilot class.
Returns the odf name of the vehicle's pilot class. Returns nil if none exists.
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.
These functions get and set position and orientation.
Returns the game object's front vector. Returns nil if none exists.
If the target is a path this is the path point index, defaults to 0.
Returns the game object's or path point's position vector. Returns nil if none exists. @todo Can't depricate this because it's used for paths too, at least for now
Returns the game object's transform matrix. Returns nil if none exists.
If the target is a path this is the path point index, defaults to 0.
Teleports the game object to a target location.
These functions get and set linear velocity.
Returns the game object's linear velocity vector. Returns nil if none exists.
These functions get and set angular velocity.
Returns the game object's angular velocity vector. Returns nil if none exists.
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 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.
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.
Sets team alliances back to default.
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).
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).
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 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.
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.
Gets the game object's visible name.
Get the objective on status of object. [UNRELEASED]
Sets the game object's visible name. This function is effectively an alias for SetObjectiveName.
Sets the game object's visible name.
Sets the game object back to normal.
Sets the game object as an objective to all teams.
These functions measure and return the distance between a game object and a reference point.
If the target is a path this is the path point index, defaults to 0.
Returns the distance in meters between the game object and a position vector, transform matrix, another object, or point on a named path.
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.
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)
These functions find and return the game object of the requested type closest to a reference point.
Returns how many objects with the given team and odf name are closer than the given distance.
If the target is a path this is the path point index, defaults to 0.
Returns the building closest to a position vector, transform matrix, another object, or point on a named path.
If the target is a path this is the path point index, defaults to 0.
Returns the enemy closest to a position vector, transform matrix, another object, or point on a named path.
If the target is a path this is the path point index, defaults to 0.
Returns the friend closest to a position vector, transform matrix, another object, or point on a named path.
If the target is a path this is the path point index, defaults to 0.
Returns the game object closest to a position vector, transform matrix, another object, or point on a named path.
Returns the friend closest to the given reference point. Returns nil if none exists.
The path name.
The point on the path (optional).
If the target is a path this is the path point index, defaults to 0.
Returns the craft closest to a position vector, transform matrix, another object, or point on a named path.
These functions return iterator functions for use with Lua's "for
Enumerates all craft.
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 game objects marked as objectives.
If the target is a path this is the path point index, defaults to 0.
Enumerates game objects within the given distance a target.
Enumerates all game objects currently selected by the local player.
These functions remove scrap, either to reduce the global game object count or to remove clutter around a location.
Clear all scrap within the given distance of a position vector, transform matrix, game object, or named path. It uses the start of the path if no point is given.
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.
These functions look up game objects in team slots.
TYPE: UNK_enum TeamSlot
SPECIAL: field
GLYPH: bi bi-list-ul
----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.
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 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.
Get the game object in the specified team slot. It uses the local player team if no team is given. @note Team slots badly lag behind for remote players, even though the object will exist on the local machine as a remote tagged object. This affects all TeamSlot based functions.
These functions get and set pilot counts for a team.
Adds pilots to the team's maximum pilot count. Returns the new pilot count.
Adds pilots to the team's pilot count, clamped between zero and maximum count. Returns the new pilot count.
Returns the team's maximum pilot count.
Returns the team's pilot count.
Sets the team's maximum pilot count. Returns the new pilot count.
Sets the team's pilot count, clamped between zero and maximum count. Returns the new pilot count.
These functions get and set scrap values for a team.
Adds to the team's maximum scrap count. Returns the new maximum scrap count.
Adds to the team's scrap count, clamped between zero and maximum count. Returns the new scrap count.
Returns the team's maximum scrap count.
Returns the team's scrap count.
Sets the team's maximum scrap count. Returns the new maximum scrap count.
Sets the team's scrap count, clamped between zero and maximum count. Returns the new scrap count.
These functions control deployable craft (such as Turret Tanks or Producer units).
Tells the game object to deploy.
These functions access selection state (i.e. whether the player has selected a game object)
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.
Applies damage to the game object.
Tells the game object to fire at the given target.
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.
Remarks: Unsafe in CreateObject, will always return nil, should be deferred until the next Update
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.
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
These function report various global time values.
Returns the elapsed time in seconds since the start of the mission.
Returns the current system time in milliseconds. This is mostly useful for performance profiling.
Returns the simulation time step in seconds.
These functions control general mission properties like strategic AI and mission flow
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.
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. @function GetAIP
defaults to true
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.
Switches the team's AI plan. It uses team 2 if no team number is given.
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.
Unique name for objective, usually a filename ending with otf from which data is loaded
defaults to 8 seconds
Override text from the target objective file.
Adds an objective message with the given name and properties.
Clears all objective messages.
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.
Unique name for objective, usually a filename ending with otf from which data is loaded
defaults to 8 seconds
Override text from the target objective file.
Updates the objective message with the given name. If no objective exists with that name, it does nothing.
These functions control the large timer at the top of the screen.
Returns the current time in seconds on the cockpit timer.
Hides the cockpit timer.
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.
These functions control the global earthquake effect.
Starts a global earthquake effect.
Stops the global earthquake effect.
Changes the magnitude of an existing earthquake effect. Important: note the inconsistent capitalization, which matches the internal C++ script utility functions.
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.
- one-way
- round-trip
- loop
Returns the type of the named path.
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.
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 the given path type.
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 position vector, transform matrix, or object. Each full counterclockwise loop adds one and each full clockwise loop subtracts one.
Returns true if the given position vector, transform matrix, or object is inside the area bounded by the named path. Returns false otherwise. This function is equivalent to
GetWindingNumber( path, h ) ~= 0
These These functions send commands to units or query their command state.
TYPE: UNK_enum AiCommand
SPECIAL: field
GLYPH: bi bi-list-ul
----Commands the unit to attack the given target. 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 position vector, transform matrix, game object location, or 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.
Returns true if the game object is a producer that can build at the moment. Returns false otherwise.
Returns true if the game object can be commanded. Returns false otherwise.
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. @function Defend2
Commands the unit to drop off at the position vector, transform matrix, or 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 follow the given target. 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.
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.
Commands the pilot to get into the target vehicle. Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Gets the independence of a unit.
Commands the unit to go to the position vector, transform matrix, game object location, or named path. 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.
Returns true if the game object has reached the end of the named path. Returns false otherwise.
Returns true if the game object is a producer and currently busy. Returns false otherwise.
Returns true if the unit is currently following the given target.
Commands the unit to lay mines at the given position vector, transform matrix, or named path. 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 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 recycle. This function is equivalent to SetCommand(me, AiCommand.RECYCLE, priority). Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
Commands the unit to retreat to the given target or 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 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.
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 to stop at its current location. Priority 0 leaves the unit commandable while the default priority 1 makes it uncommandable.
These functions query Tug and 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.
Returns the vehicle that the pilot most recently hopped out of.
Kills the vehicle's pilot as if sniped.
These functions get and set health values on a game object.
Adds to the current health of the game object.
Returns the current health value of the game object.
Returns the fractional health of the game object between 0 and 1.
Returns the maximum health value of the game object.
Sets the unit's current health to maximum.
Sets the current health of the game object.
These functions get and set ammo values on a game object.
Adds to the current ammo of the 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 unit's current ammo to maximum.
Sets the current ammo of the game object.
These functions control the cinematic camera for in-engine cut scenes (or "cineractives" as the Interstate '76 team at Activision called them).
Returns true if the player canceled the cinematic. Returns false otherwise.
Finishes the cinematic camera and enables normal input. Always returns true.
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.
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.
Moves a cinematic camera along a path at a given height and speed while looking at a target path. Returns true when the camera arrives at its destination. Returns false otherwise.
Starts the cinematic camera and disables normal input. Always returns true.
Returns true when the camera arrives at its destination. Returns false otherwise.
Returns true if the game object inspected by the info display matches the given odf or is the given handle.
@note see _gameobject module.
LuaMission currently has limited network support, but can detect if the mission is being run in multiplayer and if the local machine is hosting.
Adds a system text message to the chat window on the local machine.
Returns true if the local machine is hosting a network game. Returns false otherwise.
Returns true if the game is local to the machine the script is running on. Returns false otherwise.
Returns true if the game is a network game. Returns false otherwise.
Returns true if the game object is remote to the machine the script is running on. Returns false otherwise.
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 | |
Sets the game object as local to the machine the script is running on, transferring ownership from its original owner if it was remote.
These functions read values from an external ODF, INI, or TRN file.
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 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 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 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.
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.
These functions return height and normal from the terrain height field.
Returns the terrain height and normal vector at a position vector, transform matrix, object, or point on a named path.
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 a position vector, transform matrix, object, or point on a named path.
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 name of the BZN file for the map. This can be used to generate an ODF name for mission settings.
Returns the contents of the named file as a string, or nil if the file could not be opened.
@function string UseItem
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.
A Vector in 3D space
This is a custom userdata representing a position or direction. It has three number components: x, y, and z.
The x-coordinate.
The y-coordinate.
The z-coordinate.
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 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.
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 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 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 a vector whose components have the given number values. If no value is given for a component, the default value is 0.0.
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).
A Matrix
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).
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 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.
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 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.
Global value representing the identity matrix. Equivalent to SetMatrix(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0). @function matrix IdentityMatrix
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.
These functions control the Portal building introduced in The Red Odyssey expansion.
Activates the specified Portal, starting the visual effect.
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.
Deactivates the specified Portal, stopping the visual effect.
Returns true if the specified Portal direction is "in". Returns false otherwise.
Sets the specified Portal direction to "in", indicated by an orange visual effect while active.
Sets the specified Portal direction to "out", indicated by a blue visual effect while active.
Returns true if the specified Portal is active. Returns false otherwise. Important: note the capitalization!
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.
Enable or disable cloaking for all cloaking-capable units. Note: this does not grant a non-cloaking-capable unit the ability to cloak.
Enable or disable cloaking for a specified cloaking-capable unit. Note: this does not grant a non-cloaking-capable unit the ability to cloak.
Returns true if the unit is cloaked. Returns false otherwise
Instantly sets the unit as cloaked (with no fade out).
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.
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 target position vector, transform matrix, object, or the start of the named path.
Bitwise operations on 32-bit integers.
TYPE: table
SPECIAL: field
GLYPH: bi bi-table
----Table of bitwise operation functions. @table bit
Bitwise operations on 32-bit integers.
Normalizes a number to the numeric range for bit operations and returns it. This function is usually not needed since all bit operations already normalize all of their input arguments. Check the operational semantics for details.
function printx(x) print("0x"..bit.tohex(x)) end
print(0xffffffff) --> 4294967295
print(bit.tobit(0xffffffff)) --> -1
printx(bit.tobit(0xffffffff)) --> 0xffffffff
print(bit.tobit(0xffffffff + 1)) --> 0
print(bit.tobit(2^40 + 1234)) --> 1234
Returns the bitwise not of its argument.
Returns the bitwise and of its arguments.
Returns the bitwise or of its arguments.
Returns the bitwise xor of its arguments.
The number to shift.
The number of bits to shift.
Bitwise logical left-shift.
The number to shift.
The number of bits to shift.
Bitwise logical right-shift.
The number to shift.
The number of bits to shift.
Bitwise arithmetic right-shift.
The number to rotate.
The number of bits to rotate.
Bitwise left rotation.
The number to rotate.
The number of bits to rotate.
Bitwise right rotation.
The number to convert to hex.
The number of hex digits to generate. Positive numbers generate lowercase hex digits, negative numbers generate uppercase hex digits.
hex string representation of the number.
Converts its first argument to a hex string. The number of hex digits is given by the absolute value of the optional second argument. Positive numbers between 1 and 8 generate lowercase hex digits. Negative numbers generate uppercase hex digits. Only the least-significant 4*|n| bits are used. The default is to generate 8 lowercase hex digits.
print(bit.tohex(1)) --> 00000001
print(bit.tohex(-1)) --> ffffffff
print(bit.tohex(0xffffffff)) --> ffffffff
print(bit.tohex(-1, -8)) --> FFFFFFFF
print(bit.tohex(0x21, 4)) --> 0021
print(bit.tohex(0x87654321, 4)) --> 4321