ScriptUtils
BZ98R ScriptUtils Stub.
Definitions for Lua Language Server
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
Many of these values likely never appear in game and are leftover from Interstate '76
Wooden Structures
A structure which can contain the floor
The floor in a bridge
Metal Structures
Wooden Structures
A structure which can contain the floor
The floor in a bridge
Metal Structures
For maintainability, always use this enum instead of raw team slot numbers. Slots starting with MIN_ and MAX_ represent the lower and upper bound of a range of slots.
For maintainability, always use this enum instead of raw command numbers.
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 index of the current language.
1. English
2. French
3. German
4. Spanish
5. Italian
6. Portuguese
7. Russian
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")
These are functions you are expected to implement in your script. The game will call these functions if they exist for game logic events.
Save is called when you save a game
Load is called when you load a game, or when a Resync is loaded.
Called when the mission starts for the first time. Use this function to perform any one-time script initialization.
The key that was pressed.
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 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.
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.
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.
The time since the last tick in seconds.
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.
DPID number for this player
name for this player
Team number for this player
Called when a player joins the game world.
DPID number for this player
name for this player
Team number for this player
Called when a player joins the game world.
DPID number for this player
name for this player
Team number for this player
Called when a player leaves the game world.
the command string
additional arguments
Command
x
x
data
Receive
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.
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.
Position vector, transform matrix, Object, or path name.
If the location is a path this is the path point index, defaults to 0.
Multiplayer: Objects built by the host are always synchronized, objects built by clients will always be desynchronized initially, but can be synchronized by calling SetLocal().
Extra Utilities: To build a desynchronized object as the host, use exu.BuildAsyncObject().
Creates a game object with the given odf name, team number, and location.
Unsafe to use on a handle passed in by CreateObject(h), doing so will crash the game. If you need this functionality, you should defer the deletion until the next Update(dt).
Multiplayer: Very dangerous. There are innumerable cases which can cause objects to be improperly deleted and/or spawn explosion chunks which may only be visible to certain players. In order to safely delete a distributed object, ALL players must call RemoveObject(h) on the target object simultaneously. Additionally, attempting to delete the starting recycler in a strategy or MPI game will crash the game.
Extra Utilities: If you need to remove the multiplayer starting recyclers use exu.DisableStartingRecycler().
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").
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. Many of these values likely never appear in game and are leftover from Interstate '76
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.
float
Returns true if the game object exists and has less health than the threshold. Returns false otherwise.
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. @todo confirm target can be nil, if it can't this should be depricated
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.
Sets the game object's owner. @todo confirm o can be nil
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.
These functions get and set position and orientation.
If the target is a path this is the path point index, defaults to 0.
Teleports the game object to a target location.
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 front vector. Returns nil if none exists.
Teleports the game object to the given transform matrix.
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 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.
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. {(i)(i)BZCC would require the use of Ally(1, 2) and Ally(2, 1) so if you are making portable code you will need both or will need to monkey-patch BZCC's version.}
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. {(i)(i)BZCC would require the use of UnAlly(1, 2) and UnAlly(2, 1) so if you are making portable code you will need both or will need to monkey-patch BZCC's version.}
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.
Multiplayer: The object h must be local to the caller and synchronized.
Calling this function on a desynchronized object will result in the status not being propagated to remote players.
Sets the game object as an objective to all teams.
Multiplayer: The object h must be local to the caller and synchronized.
Calling this function on a desynchronized object will result in the status not being propagated to remote players.
Sets the game object back to normal.
Get the objective on status of object. [UNRELEASED]
Gets the game object's visible name.
Sets the game object's visible name.
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 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.
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.
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.
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.
The path name.
The point on the path (optional).
Returns the friend closest to the given reference point. 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
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. 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 position vector, transform matrix, game object, or named path. It uses the start of the path if no point is given.
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. 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. @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.
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.
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.
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.
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.
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.
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.
Remarks: Unsafe in CreateObject, will always return nil, should be deferred until the next Update
Tells the game object to fire at the given target.
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
defaults to true
When: 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.
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.
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.
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.
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.
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.
- one-way
- round-trip
- loop
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 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.
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.
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 true if the game object has reached the end of the named path. 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 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 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 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 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 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 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 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.
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.
{(!!)Version(!!)While this was added in version 2.1 it is broken and must be monkey-patched to use SetCommand instead.
The game in error treats the function as if it was Formation(me, priority) before version 2.2.315+.}
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.
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.
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.
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.
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.
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.
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.
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.
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 or is the given handle.
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.
When: Only call this on one machine at a time!
Multiplayer: Safe to call in singleplayer, has no function. If called on a remote object, it will break their ai irreversibly.
Sets the game object as local to the machine the script is running on, transferring ownership from its original owner if it was remote.
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.
Multiplayer: The displayed message is entirely local regardless of hosting status, if you want a message to be visible to all players you should Send() a message to all players to display the given message.
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.
This will not fail if the file does not exist but will return an empty database. There is no way to proove the database is empty from Lua so use UseItem to check if the file exists.
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 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 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.
A Vector in 3D space
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).
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
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).
Angle in radians defaulting to 0
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.
Pitch angle in radians defaulting to 0
Yaw angle in radians defaulting to 0
Roll angle in radians defaulting to 0
X position defaulting to 0
Y position defaulting to 0
Z position defaulting to 0
Build a matrix with the given pitch, yaw, and roll angles and position.
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.
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.
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.
Multiplayer: Explosions are entirely local, this includes the visuals and the damage. This can be used to create clientside graphics.
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.
Table of bitwise operation functions.
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