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
===================================================
_api
----BZ98R LUA Extended API.
This API creates a full OOP wrapper and replacement the mission functions with an event based system for easier expansion.
data
data
===================================================
_camera
----BZ98R LUA Extended API Camera.
Camera API wrapper.
Returns true if the player canceled the cinematic. Returns false otherwise.
Finishes the cinematic camera and enables normal input. Does nothing if camera is not active.
Meters to the right of the base object.
Meters above the base object.
Meters in front of the base object.
true if the base or handle game object does not exist. Returns false otherwise.
Offsets a cinematic camera from a base game object while looking at a target game object. Returns true if the base or handle game object does not exist. Returns false otherwise.
meters above the ground
speed in meters per second
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 point. Returns true when the camera arrives at its destination. Returns false otherwise.
meters above the ground
speed in meters per second
defaults to the same as speed
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.
@todo this function badly needs testing
Camera is currently active
Returns true when the camera arrives at its destination. Returns false otherwise.
Resets the camera cancelled flag.
===================================================
_cheat_bzrave
----BZ98R LUA Extended API Cheat.
BZRAVE cheat
require("_cheat_bzrave");
===================================================
_color
----BZ98R LUA Extended API Color.
Crude custom type to make data not save/load exploiting the custom type system.
TYPE: UNK_table<string, string>
SPECIAL: inner_type
GLYPH: bi bi-table
----TYPE: UNK_table<string, string>
SPECIAL: inner_type
GLYPH: bi bi-table
----TYPE: UNK_table<string, integer>
SPECIAL: inner_type
GLYPH: bi bi-table
----The closest game color code
Convert RGBA color to the closest game color code. This function takes an RGBA color and finds the closest game color code.
TYPE: UNK_table<integer, integer>
SPECIAL: inner_type
GLYPH: bi bi-table
----The red component (0-255)
The green component (0-255)
The blue component (0-255)
The alpha component (0-255)
The ANSI 24-bit color escape code
Convert RGBA color to ANSI 24-bit color escape code. This function takes an RGBA color and converts it to an ANSI 24-bit color escape code.
The ANSI 256 color code (0-255)
Convert RGBA color to ANSI 256 color escape code. This function takes an RGBA color and converts it to an ANSI 256 color code. It uses a color cube and grayscale range to find the closest match.
The ANSI 256 color escape code
Convert RGBA color to ANSI 256 color escape code. This function takes an RGBA color and converts it to an ANSI 256 color escape code.
===================================================
_customsavetype
----BZ98R LUA Extended API CustomSaveType.
Crude custom type to make data not save/load exploiting the custom type system.
local customsavetype = require("_customsavetype");
customsavetype.Register(ObjectDef);
TYPE: UNK_CustomSavableType?
SPECIAL: inner_type
GLYPH: bi bi-question-circle
----The base type to inherit from, if any.
If true, the type will not undergo checks for shared or looped references when saving.
If true, the type will not be saved or loaded, a nil will be saved instead.
The type name of the custom savable type.
TYPE: UNK_table<string, CustomSavableType>
SPECIAL: inner_type
GLYPH: bi bi-table
----Does this custom savable type implement the given type?
Register a custom savable type.
===================================================
_deque
----BZ98R LUA Extended API dequeue library.
https://github.com/catwell/cw-lua/blob/master/deque/deque.lua
Deque implementation by Pierre 'catwell' Chapuis
Copyright (C) by Pierre Chapuis
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
TYPE: UNK_any
SPECIAL: inner_type
GLYPH: bi bi-braces
----The elements stored in the deque.
The index of the first element.
The index of the last element.
Load event function.
Save event function.
===================================================
_fix
----BZ98R LUA Extended API Lua Bug Fixer.
Contains fixes for bugs in the game's lua implementation and other polyfils.
- Polyfill:
table.unpackfor Lua 5.1 compatibility - Fix/Polyfill: Remap
SettLabeltoSetLabelfor BZ1.5 - Fix: Works around the possible stuck iterator in
ObjectiveObjects - Fix/Polyfill: TeamSlot missing "PORTAL" = 90
- Fix: Tugs not respecting DropOff command due to invalid deploy state
- Fix/Polyfill: Fix for broken
Formationorder function - Fix: Powerups not using thrusters when falling if on an AI team
===================================================
_gameobject
----BZ98R LUA Extended API GameObject.
GameObject wrapper functions.
GameObject An object containing all functions and data related to a game object.
GameObject.__index = GameObject; -- failed table lookups on the instances should fallback to the class table, to get methods
GameObject An object containing all functions and data related to a game object.
TYPE: table
SPECIAL: inner_type
GLYPH: bi bi-table
----Extended data saved into the object
TYPE: table
SPECIAL: inner_type
GLYPH: bi bi-table
----Unsaved data used for housekeeping that is regenerated at load
TYPE: UNK_Handle
SPECIAL: inner_type
GLYPH: bi bi-question-circle
----Handle used by BZ98R
GameObject An object containing all functions and data related to a game object.
Object data
BulkLoad event function.
GameObject An object containing all functions and data related to a game object.
BulkSave event function.
Get Handle used by BZ98R.
Get the SeqNo of the GameObject. Note that the SeqNo is rather useless.
GameObject An object containing all functions and data related to a game object.
Handle
Load event function.
Save event function.
Remove GameObject from world.
Returns true if the game object inspected by the info display matches the current game object.
identifier for race
Get base of GameObject
number
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.
label string
Returns the class label of the game object (e.g. "wingman"). Returns nil if none exists.
string
Returns the four-character class signature of the game object (e.g. "WING"). Returns nil if none exists.
name string
Get label of GameObject
identifier for race
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".
Get odf of GameObject
Is the GameObject alive and is still pilot controlled? Returns true if the game object exists and (if the object is a vehicle) controlled. Returns false otherwise.
Is the GameObject alive and piloted? Returns true if the game object exists and (if the object is a vehicle) controlled and piloted. Returns false otherwise.
Returns true if it's a Building. Does not include guntowers.
Returns true if it's a Craft.
float
Returns true if the game object exists and has less health than the threshold. Returns false otherwise.
ODF filename
Is the GameObject this odf?
enemy1:IsOdf("svturr")
Returns true if it's a person.
Returns true if the game object was recycled by a Construction Rig on the given team.
Does the GameObject exist in the world? Returns true if the game object exists. Returns false otherwise.
Label
Is the GameObject this odf?
enemy1:SetLabel("special_object_7")
These functions get and set team number. Team 0 is the neutral or environment team.
number
Get perceived team number of the GameObject.
number
Returns the game object's team number.
Set perceived team number of the GameObject.
Sets the game object's team number.
These function get and set a unit's target.
Returns the game object's target. Returns nil if it has none.
Sets the game object's target. @todo confirm target can be nil
Sets the local player'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.
Sets the game object's owner. @todo confirm owner can be nil
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.
Get front vector.
Get object's omega.
Get object's position vector.
Get object's tranform matrix.
Get object's velocity vector.
Set the omega of the GameObject.
Index of the path point in the path (optional)
Set the position of the GameObject.
Set the tranform matrix of the GameObject.
Set the velocity of the GameObject.
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.
Returns who scored the most recent hit on the game object. Returns nil if none exists.
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.
Do we consider this an ally?
Order GameObject to Attack target GameObject.
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.
of the objective/object
Sets the game object's visible name.
if the game object is an objective
If the game object an objective?
Name of the objective
Sets the game object's visible name. (Technicly a unique function, but effectively an alias for SetObjectiveName) See: GameObject.SetObjectiveName
Name of the objective
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.
Position vector, ransform matrix, Object, or path name.
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.
Returns the building closest to self.
Returns the enemy closest to self.
Returns the friend closest to self.
Returns the game object closest to self.
Returns the friend closest to self. Returns nil if none exists.
Returns the craft closest to self.
These functions look up game objects in team slots.
GameObject An object containing all functions and data related to a game object.
Slot number, see TeamSlot
The new game object formerly in the slot, or nil if the slot was empty
Set the game object in the specified team slot. This could have major sideffects so be careful with it.
Sets the game object in the specified team slot.
See: ~ScriptUtils.TeamSlot~
These functions control deployable craft (such as Turret Tanks or Producer units).
Tells the game object to deploy. @function Deploy
Returns true if the game object is a deployed craft. Returns false otherwise. @function IsDeployed
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.
defaults to true
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.
damage amount
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.
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 functions send commands to units or query their command state.
Order priority, >0 removes user control
Order GameObject to Attack target GameObject.
Object Definition
Order priority, >0 removes user control
Order GameObject to Build target config. Oddly this function does not include a location for the action, might want to use the far more powerful orders system.
Object Definition
Target GameObject instance, vector, matrix, or path name
Order priority, >0 removes user control
Order GameObject to BuildAt target GameObject.
Returns true if the game object is a producer that can build at the moment. Returns false otherwise. The concept here is that the builder either A: Does not need to deploy or B: Does need to deploy but is deployed.
Returns true if the game object can be commanded. Returns false otherwise.
Order priority, >0 removes user control
Order GameObject to Defend area.
Order priority, >0 removes user control
Order GameObject to Defend2 target GameObject.
Order priority, >0 removes user control
Order GameObject to Pickup target path name.
Order priority, >0 removes user control
Order GameObject to Follow target GameObject.
Order priority, >0 removes user control
Order GameObject to Formation follow target GameObject.
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.
Order priority, >0 removes user control
Order GameObject to GetIn target GameObject.
Gets the independence of a unit.
Order priority, >0 removes user control
Order GameObject to Goto target Vector, Matrix, GameObject, or Path. @function GameObject:Goto
Order priority, >0 removes user control
Order GameObject to Hunt area.
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. An undeployed builder that needs to deploy will always indicate false. A deployed (if needed) producer with a buildClass set is considered busy. The buildClass may be cleared after the CreateObject call.
true if following, false otherwise
Is the GameObject following the target GameObject?
Order priority, >0 removes user control
Order GameObject to Mine target Path.
Target Path name
Order priority, >0 removes user control
Order GameObject to Patrol target path.
Order priority, >0 removes user control
Order GameObject to Pickup target GameObject.
Order priority, >0 removes user control
Order GameObject to Recycle.
Order priority, >0 removes user control
Order GameObject to Retreat.
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.
Order priority, >0 removes user control
Order GameObject to Stop.
These functions query Tug and Cargo.
Returns the GameObject of the cargo if the GameObject is a tug carrying cargo. Returns nil otherwise.
Returns the GameObject of the tug carrying the object. Returns nil if not carried.
Returns true if the GameObject is a tug carrying cargo.
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 GameObject most recently hopped out of.
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.
health amount
Adds the health to the GameObject.
current health or nil
Returns the current health value of the game object.
health ratio
Returns the fractional health of the game object between 0 and 1.
if friend1:GetHealth() < 0.5 then
friend1:Retreat("retreat_path");
end
max health or nil
Returns the maximum health value of the game object.
GiveMaxHealth
health amount
Sets the current health of the game object.
health amount
Sets the max health of the GameObject to the NewHealth value.
These functions get and set ammo values on a game object.
ammo amount
Adds to the current ammo of the game object.
ammo ratio
Returns the fractional ammo of the game object between 0 and 1.
current ammo or nil
Returns the current ammo value of the game object.
max ammo or nil
Returns the maximum ammo value of the game object.
Sets the unit's current ammo to maximum.
ammo amount
Sets the current ammo of the game object.
ammo amount
Sets the maximum ammo of the game object.
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 object is initialized, meaning it has been created and is either local or 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.
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!
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.
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.
Returns true if the specified Portal is active. Returns false otherwise. Important: note the capitalization!
Sets the specified Portal direction to "out", indicated by a blue visual effect while active.
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.
Returns true if the unit is cloaked. Returns false otherwise
Instantly sets the unit as cloaked (with no fade out).
Instant sets the unit as uncloaked (with no fade in).
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.
Object in question
Is this object an instance of GameObject?
Create new GameObject Intance.
Sequence number of the object
Create a new GameObject instance. This works via a lookup table so it can fail easily.
Object Definition File (without ".odf")
index
Creates a GameObject with the given odf name, team number, and location.
Label
Get GameObject by Label.
These function get and set a unit's target.
Returns the local player's target. Returns nil if it has none.
These functions find and return the game object of the requested type closest to a reference point.
Position vector, ransform matrix, Object, or path name.
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.
Position vector, ransform matrix, Object, or path name.
Position vector, ransform matrix, Object, or path name.
Position vector, ransform matrix, Object, or path name.
Position vector, ransform matrix, Object, or path name.
Position vector, ransform matrix, Object, or path name.
If the target is a path this is the path point index, defaults to 0.
Position vector, ransform matrix, Object, or path name.
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.
Position vector, ransform matrix, Object, or path name.
Position vector, ransform matrix, Object, or path name.
Position vector, ransform matrix, Object, or path name.
Position vector, ransform matrix, Object, or path name.
Position vector, ransform matrix, Object, or path name.
If the target is a path this is the path point index, defaults to 0.
Position vector, ransform matrix, Object, or path name.
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.
Position vector, ransform matrix, Object, or path name.
Position vector, ransform matrix, Object, or path name.
Position vector, ransform matrix, Object, or path name.
Position vector, ransform matrix, Object, or path name.
Position vector, ransform matrix, Object, or path name.
If the target is a path this is the path point index, defaults to 0.
Position vector, ransform matrix, Object, or path name.
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.
Position vector, ransform matrix, Object, or path name.
Position vector, ransform matrix, Object, or path name.
Position vector, ransform matrix, Object, or path name.
Position vector, ransform matrix, Object, or path name.
Position vector, ransform matrix, Object, or path name.
If the target is a path this is the path point index, defaults to 0.
Returns the friend closest to the given reference point. Returns nil if none exists.
Position vector, ransform matrix, Object, or path name.
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.
Position vector, ransform matrix, Object, or path name.
Position vector, ransform matrix, Object, or path name.
Position vector, ransform matrix, Object, or path name.
Position vector, ransform matrix, Object, or path name.
Position vector, ransform matrix, Object, or path name.
If the target is a path this is the path point index, defaults to 0.
These functions return iterator functions for use with Lua's "for
Iterator of GameObject values
Enumerates all craft.
Iterator of GameObject values
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.
Iterator of GameObject values
Enumerates all game objects marked as objectives.
Position vector, ransform matrix, Object, or path name.
If the target is a path this is the path point index, defaults to 0.
Iterator of GameObject values
Enumerates game objects within the given distance a target.
Iterator of GameObject values
Enumerates all game objects currently selected by the local player.
These functions look up game objects in team slots.
Get Armory GameObject of team.
Get Factory GameObject of team.
Get Factory GameObject of team.
Get Player GameObject of team. @todo depricate functions like this and move them to a team manager, because of the issue noted on scriptutils for GetTeamSlot.
Get Recycler GameObject of team.
Get the game object in the specified team slot.
See: ~ScriptUtils.TeamSlot~
===================================================
_hook
----BZ98R LUA Extended API Hook.
Event hook for event observer pattern.
local hook = require("_hook");
-- optional priority overrides, only applies when adding hooks
-- consider removing this now that we have a centralized _config.lua
_api_hook_priority_override = {
["Update"] = {
["_statemachine_Update"] = 10000;
["_funcarray_Update"] = 10000;
},
["DeleteObject"] = {
["GameObject_DeleteObject"] = -10000;
}
};
hook.Add("InitialSetup", "Custom_InitialSetup", function(turn)
end);
hook.Add("Update", "Custom_Update", function(turn)
end);
hook.AddSaveLoad("Custom_SaveLoad",
function()
return MissionData;
end,
function(savedData)
MissionData = savedData;
end);
-- 10% of the time players will just respawn instead of eject, this overrides all other event hooks
hook.Add("PlayerEjected", function(DeadObject)
if object:IsPlayer() and GetRandomFloat(10) > 9 then
return hook.AbortResult(EjectKillRetCodes.DoRespawnSafest);
end
end, 9999)
Function to be executed when the event is triggered.
Identifier for this hook observer.
Higher numbers are higher priority.
Flag to abort the hook chain.
TYPE: UNK_any[]
SPECIAL: inner_type
GLYPH: bi bi-question-circle
----Return values passed from hook function.
Type of the object, used for type checking. "HookResult"
Return values passed from hook function
Create an Abort HookResult @function _hook.AbortResult
Event to be hooked
Identifier for this hook observer
Function to be executed
Higher numbers are higher priority
Add a hook to listen to the specified event. @function _hook.Add
Identifier for this hook observer
Function to be executed for Save
Function to be executed for Load
Function to be executed after all Load hooks are called
Add a hook to listen to the Save and Load event. @function _hook.AddSaveLoad
Event to be hooked
Parameters passed to every hooked function
true if stopped early, else nil
Calls hooks associated with the hook name ignoring any return values. @todo Consider redoing the return value as nothing uses it right now. @function _hook.CallAllNoReturn
Event to be hooked
Parameters passed to every hooked function
nil if no hooks are called, a HookResult if the chain is aborted, or the return values from the last hook function.
Calls hooks associated with the hook name passing each return to the next. Hooked functions may return multiple values. The return value is always passed to the next hook wrapped in an EventResult. If the value is generated by one of the hook library's event functions it will be parsed and passed along without wrapping. This allows for the hook chain to be broken early through the use of the AbortResult function. The best action here is to nil check and test your last Parameter with hook.isresult before processing it. @function _hook.CallAllPassReturn
Calls hooks associated with Load. @function _hook.CallLoad
Calls hooks associated with Save. @function _hook.CallSave
Table of all hooks.
Event to be hooked
Identifier for this hook observer
Removes the hook with the given identifier. @function _hook.Remove
Identifier for this hook observer
Removes the Save and Load hooks with the given identifier. @function _hook.RemoveSaveLoad
Return values passed from hook function
Create an basic HookResult
This wraps a return value similarly to _hook.AbortResult and
can be used optionally to wrap return values. This is primarily used internally
to wrap the prior return value to be passed as the next Parameter in
_hook.CallAllPassReturn based event triggers as event
handler return values are auto-unwrapped by the event handler if wrapping is
detected but process fine if unwrapped.
@function _hook.WrapResult
See:
Object in question
Is this object an instance of HookResult?
===================================================
_logger
----BZ98R LUA Extended API Debug.
System for handling debugging and logging.
TYPE: UNK_LogFormat
SPECIAL: inner_type
GLYPH: bi bi-question-circle
----Log Format
TYPE: UNK_InterceptPrint
SPECIAL: inner_type
GLYPH: bi bi-question-circle
----Print Intercept Mode
TYPE: UNK_LogLevel
SPECIAL: inner_type
GLYPH: bi bi-question-circle
----Log Levels
TYPE: UNK_string[]
SPECIAL: inner_type
GLYPH: bi bi-question-circle
----Patterns to suppress in log messages
TYPE: UNK_enum InterceptPrint
SPECIAL: inner_type
GLYPH: bi bi-list-ul
----TYPE: UNK_enum LogFormat
SPECIAL: inner_type
GLYPH: bi bi-list-ul
----TYPE: UNK_enum LogLevel
SPECIAL: inner_type
GLYPH: bi bi-list-ul
----Print log line Ignores wrapping setting for normal print. Will strip colors if not supported.
TYPE: UNK_DebugSettings
SPECIAL: inner_type
GLYPH: bi bi-question-circle
----@todo make this readonly (at least through this window)
===================================================
_navmanager
----BZ98R LUA Extended API NavManager.
Manage navs
local navmanager = require("_navmanager");
navmanager.SetCompactionStrategy(navmanager.CompactionStrategy.ImportantFirstChronologicalToGap);
@todo Determine if network handling is needed. @todo Look into soft-loading native module that gives nav data access.
Adds custom data to GameObject for this module.
TYPE: table
SPECIAL: inner_type
GLYPH: bi bi-table
----A table containing custom data for this module.
Team number to enumerate
If true "Overflow Navs" will be included in the enumeration after the initial 10.
function yielding index and nav object
Enumerates all navs for a team. At least 10 indexes will be iterated, even if there are no navs in those slots. Navs not in the nav list, known internally as "Overflow Navs", will be returned with indexes above 10.
for i, nav in navmanager.AllNavGameObjects(1, true) do
print("Nav " .. i .. ": " .. tostring(nav));
end
local active_navs = utility.IteratorToArray(navmanager.AllNavGameObjects(1));
ODF of the nav to build, if nil uses the default nav ODF
Team number of the nav to build
Position vector, Transform matrix, or Object.
path point index, defaults to 0.
Build an important nav and add it to the collection. Important navs will push non-important navs out of the way in the list.
TYPE: table
SPECIAL: inner_type
GLYPH: bi bi-table
----What to do when empty slots exist and excess navs exist @table _navmanager.CompactionStrategy
current compaction strategy. See @{_navmanager.CompactionStrategy} for options.
Get the current compaction strategy for navs.
The strategy to use. See @{_navmanager.CompactionStrategy} for options.
Set the compaction strategy for navs. @function _navmanager.SetCompactionStrategy
===================================================
_objective
----BZ98R LUA Extended API Objective Manager.
Note that this module cannot manage manually created objectives.
@todo write example usage
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.
Sort position of the objective. Defaults to the next available ID.
If true, the objective will not be removed when the objectives are cleared. Defaults to false.
Adds an objective message with the given name and properties.
Clear all objectives except for persistant ones.
Unique name for objective, usually a filename ending with otf from which data is loaded
Sort position of the objective.
Get the objective position of 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.
Unique name for objective, usually a filename ending with otf from which data is loaded
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.
Sort position of the objective. Defaults to the removed objective's position or next available ID.
If true, the objective will not be removed when the objectives are cleared. Defaults to false.
Replaces the objective message with the given name. If no objective exists with that name, it does nothing.
Unique name for objective, usually a filename ending with otf from which data is loaded
Sort position of the objective.
Set the objective position of the given name. If no objective exists with that 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.
Sort position of the objective. Defaults to the next available ID.
If true, the objective will not be removed when the objectives are cleared. Defaults to false.
Updates the objective message with the given name. If no objective exists with that name, it does nothing.
===================================================
_optional
----BZ98R LUA Extended API Optional loader.
Load a lua module optionally.
local optional = require("_optional");
local missingSuccess, missingMod = optional("_missing");
missingMod = missingSuccess and missingMod or nil;
local missing2Success, missingMod2 = require("_optional")("_missing2");
missingMod2 = missing2Success and missingMod2 or nil;
===================================================
_paramdb
----BZ98R LUA Extended API ODF Handler.
Tracks objects by class and odf.
ODF file name
@todo This might not need to exist since it doesn't have special class code
ODF file name
ODF file name
ODF file name
cost
ODF file name
cost
ODF file name
Section name
Key name
Default value if the key is not found
Get a general string without handling of class defaults.
===================================================
_paths
----BZ98R LUA Extended API Paths.
Object in question
Is this object a table?
Path name
Iterate the vectors along the path. Return LUA style 1 based indexes for the path points.
===================================================
_patrol
----BZ98R LUA Extended API Patrol Engine.
Patrol Engine
@todo usage example
TYPE: table
SPECIAL: inner_type
GLYPH: bi bi-table
----TYPE: UNK_table<string>
SPECIAL: inner_type
GLYPH: bi bi-table
----TYPE: UNK_table<string, table>
SPECIAL: inner_type
GLYPH: bi bi-table
----TYPE: UNK_table<GameObject_patrol, boolean>
SPECIAL: inner_type
GLYPH: bi bi-table
----Creates a new PatrolEngine instance.
===================================================
_producer
----BZ98R LUA Extended API Producer.
Queues the building of objects by producers.
Object to build.
Location to build the object if from an armory or constructor.
Event data to be fired with the creation event.
A table mapping teams (0–15) to ProductionQueue lists. This should be scanned every update if any producers are not busy to look for work for said producer. Consider this a priority queue, even though right now it's just a normal queue. Note that price is not a good reason to skip something, instead it should inject a block event into that build queue unless it's deemed impossible to get that much scrap.
TYPE: UNK_(-1|0|1|14|15...(+24))?
SPECIAL: inner_type
GLYPH: bi bi-question-circle
----The producer that will build the object.
TYPE: UNK_any
SPECIAL: inner_type
GLYPH: bi bi-question-circle
----The event data to be fired with the creation event.
TYPE: UNK_string|Vector|{ [1]: string, [2]: integer }|nil
SPECIAL: inner_type
GLYPH: bi bi-question-circle
----The location where the object should be built, or "0 0 0" if not specified.
The ODF of the object to be built.
TYPE: UNK_ProducerData?
SPECIAL: inner_type
GLYPH: bi bi-question-circle
----TYPE: UNK_GameObject?
SPECIAL: inner_type
GLYPH: bi bi-question-circle
----GameObject An object containing all functions and data related to a game object.
===================================================
_statemachine
----BZ98R LUA Extended API StateMachineIter.
State Machine and State Machine Iterator for serial event sequences across game turns.
local statemachine = require("_statemachine");
statemachine.Create("TestMachine",
{
["state_a"] = function(state)
print("test " .. state.test1);
state:switch("state_b");
end,
["state_b"] = statemachine.SleepSeconds(10,"state_c"),
["state_c"] = function(state)
print("test " .. state.test2);
state:switch("state_d");
end,
["state_d"] = statemachine.SleepSeconds(15,"state_e"),
["state_e"] = function(state)
print("test " .. state.test3);
state:switch("state_f");
end
});
-- ordered state machine that supports state:next()
statemachine.Create("OrderedTestMachine",
{
-- named state function
{ "state_a", function(state)
print("test " .. state.test1);
state:switch("state_b");
end },
-- named magic state function (SleepSeconds)
-- note nil next_state means next state by index
{ "state_b", statemachine.SleepSeconds(10) },
-- named state function with automatic name
{ nil, function(state)
print("test " .. state.test2);
state:switch("state_d");
end },
-- named state function with automatic name
{ function(state)
print("test " .. state.test2);
state:switch("state_d");
end },
-- magic state function (SleepSeconds)
statemachine.SleepSeconds(15,"nonexistent_state"),
-- stsate function with automatic name
function(state)
print("test " .. state.test3);
state:next();
end
});
hook.Add("InitialSetup", "Custom_InitialSetup", function(turn)
MissionData.TestSMI1 = statemachine.Start("TestMachine","state_a",{test1='d',test2="e",test3="f"});
MissionData.TestSMI2 = statemachine.Start("OrderedTestMachine","state_a",{test1='d',test2="e",test3="f"});
end);
hook.Add("Update", "Custom_Update", function(turn)
MissionData.TestSMI1:run();
MissionData.TestSMI2:run();
end);
An object containing all functions and data related to an StateMachineIter.
How many seconds to wait
If true the timer will still return true when the time has passed, but will "lap" instead of "stop" and keep counting.
If true the timer returns true when it starts, requires lap to be true.
True if the time is up
Check if a set period of time has passed. This first time this is called the target time is latched in until true is returned. Ensure you call state:SecondsHavePassed() or state:SecondsHavePassed(nil) to clear the timer if it did not return true and you need to move on.
GameObject.__index = GameObject; -- failed table lookups on the instances should fallback to the class table, to get methods
TYPE: nil
TYPE: table
SPECIAL: inner_type
GLYPH: bi bi-table
----Table of values embeded in the StateMachineIter
TYPE: table
SPECIAL: inner_type
GLYPH: bi bi-table
----StateMachineIter index to name mapping, only if the StateMachineIter is ordered
Next StateMachineIter State. This only works if the StateMachineIter is ordered.
Arguments to pass to the state function
True if the state function was called, false if the state function was not found, a wrapper instance if the state function was called and returned a wrapper
The return value of the state function, if it was called. If the result was wrapped it's unwraped and returned here
Run StateMachineIter.
Time to wait before running next state, kept to allow altering target_time if set_wait_time changes
TYPE: UNK_string|integer|nil
SPECIAL: inner_type
GLYPH: bi bi-question-circle
----Current state, string name or integer index if state machine is ordered
State to switch to (will also accept state index if the StateMachineIter is ordered)
Switch StateMachineIter State.
Timer's value, nil for not set
Target time if sleeping, nil if not set
StateMachineIter template name
BulkLoad event function.
StateMachineIter template name
Timer's value, nil for not set
TargetTurn's value, nil for not set
Time to wait before running next state, kept to allow altering target_time if set_wait_time changes
Current state, string name or integer index if state machine is ordered
Addon data, if any
Load event function.
@param template string StateMachineIter template name @param target_call integer? Timer's value, nil for not set @param target_time number? TargetTurn's value, nil for not set @param set_wait_time number? Time to wait before running next state, kept to allow altering target_time if set_wait_time changes @param state_key string|integer|nil Current state, string name or integer index if state machine is ordered @param addonData table Addon data, if any
Save event function.
@param self StateMachineIter instance @return template string StateMachineIter template name @return target_call integer? Timer's value, nil for not set @return target_time number? TargetTurn's value, nil for not set @return set_wait_time number? Time to wait before running next state, kept to allow altering target_time if set_wait_time changes @return state_key string|integer|nil Current state, string name or integer index if state machine is ordered @return addonData table Addon data, if any
If true the machine should be considered aborted, allowing for cleanup
If true the machine will attempt to run the next state immediately
Simple construct for a state function with a name
TYPE: UNK_string|nil
SPECIAL: inner_type
GLYPH: bi bi-question-circle
----name
TYPE: UNK_WrappedObjectForStateMachineIter|fun(self: StateMachineIter, ...any):any
SPECIAL: inner_type
GLYPH: bi bi-question-circle
----State function
A truncated version without the name, name is constructed at runtime from index
TYPE: UNK_WrappedObjectForStateMachineIter|fun(self: StateMachineIter, ...any):any
SPECIAL: inner_type
GLYPH: bi bi-question-circle
----State function
A simple ordered set of states
TYPE: UNK_StateMachineNamedState|StateMachineNamedStateTruncated|WrappedObjectForStateMachineIter|fun(self: StateMachineIter, ...any):any
SPECIAL: inner_type
GLYPH: bi bi-braces
----State function
A simple name-only set of states
TYPE: UNK_WrappedObjectForStateMachineIter|fun(self: StateMachineIter, ...any):any
SPECIAL: inner_type
GLYPH: bi bi-braces
----State function
State function to call
TYPE: table
SPECIAL: inner_type
GLYPH: bi bi-table
----Parameters to pass to the state function
Return values passed from hook function
Create an Abort HookResult
Name of the StateMachineIter Template (string)
State descriptor and/or state descriptor collections, can be a table of named state functions or an array of state descriptors.
Creates an StateMachineIter Template with the given indentifier.
State descriptors are tables with the first element being the state name and the second element being the state function.
If the second element is nil, the first element is considered the state function and the state name is generated automatically.
If the state descriptor is instead a function it is treated as a nil state and the state name is generated automatically.
The first paramater of the state function is the StateMachineIter itself where the current state may be accessed via self.state_key.
TYPE: UNK_table<string, { is_ordered: boolean, index_to_name: table, name_to_index: table }>
SPECIAL: inner_type
GLYPH: bi bi-table
----Table of flags for each StateMachineIter template, key is the template name and value is the flags table
TYPE: UNK_table<string, StateMachineIter>
SPECIAL: inner_type
GLYPH: bi bi-table
----Table of StateMachineIter instances, key is the template name and value is the StateMachineIter instance
How many calls to wait
Next state when timer hits zero
Function to check if the state should be exited early, return false, true, or next state name
Wait a set period of time on this state.
How many seconds to wait
Next state when timer hits zero
Function to check if the state should be exited early, return false, true, or next state name
Wait a set period of time on this state.
Name of the StateMachineIter Template
Initial state, if nil the first state will be used if the StateMachineIter is ordered, can be an integer is the StateMachineIter is ordered
Initial data
Starts an StateMachineIter based on the StateMachineIter Template with the given indentifier.
Game time in seconds, used for state machine timing
Object in question
Is this object an instance of StateMachineIter?
===================================================
_stateset
----BZ98R LUA Extended API StateSetRunner.
Simplistic system to run multiple functions or "states" in a single call. The main use case of this is to hold multiple toggelable objectives. If you want to do something more complex, use the hook module instead. Like most similar constructs State Set Runners have internal data storage and can be saved and loaded.
local stateset = require("_stateset");
stateset.Create("TestSet")
:Add("state_a", function(runner, a, b)
print("test " .. runner.test1 .. " " .. tostring(a) .. " " .. tostring(b));
end)
:Add("state_a", function(runner, a, b)
print("test " .. runner.test2 .. " " .. tostring(a) .. " " .. tostring(b));
end, true);
hook.Add("InitialSetup", "Custom_InitialSetup", function(turn)
MissionData.TestSet = statemachine.Start("TestSet",{test1='d',test2="e");
MissionData.TestSet:on("state_a"); -- state true
MissionData.TestSet:on("state_b"); -- state 1
MissionData.TestSet:on("state_b"); -- state 2
MissionData.TestSet:off("state_b"); -- state 1, still on as this is a permit based state
end);
hook.Add("Update", "Custom_Update", function(turn)
MissionData.TestSMI:run(1, 2);
end);
Name of the state
Function to be called when the state is active, should return true if the state did something.
If true, the state is permit based
Add a state to the StateSet. If the state is basic either active or inactive based on last on/off call. If the state is permit based it is active if the on count is greater than 0.
TYPE: table
SPECIAL: inner_type
GLYPH: bi bi-table
----Table of StateMachineIter instances, key is the state name and value is the StateMachineIter instance
TYPE: UNK_StateSet
SPECIAL: inner_type
GLYPH: bi bi-question-circle
----Name of the StateSet template
An object containing all functions and data related to an StateSetRunner.
TYPE: table
SPECIAL: inner_type
GLYPH: bi bi-table
----Table of active states, key is the state name and value is the state activation flag or permit count
TYPE: table
SPECIAL: inner_type
GLYPH: bi bi-table
----Custom context data stored in the StateSetRunner
Name of the state
If true, the state is set off regardless of the current permits
Set state off.
Name of the state
Set state on.
Arguments to pass to the state function
if at least one state was found and executed and returned true
Run StateSetRunner.
Name of the StateSet template the runner is using
Load event function.
@param template @param active_states @param addonData
Save event function.
@param self StateSetRunner instance @return ...
TYPE: UNK_fun(self: StateSetRunner, name: string, params: table, ...any)
SPECIAL: inner_type
GLYPH: glyph/tablericons/math-function
----Function to be called when the state is active, should return true if the state did something.
TYPE: table
SPECIAL: inner_type
GLYPH: bi bi-table
----Parameters to pass to the state machine, first parameter is the StateSetRunner instance
Name of the StateSetRunner Template
Creates an StateSetRunner Template with the given indentifier.
TYPE: UNK_table<string, StateSet>
SPECIAL: inner_type
GLYPH: bi bi-table
----Table of StateSet instances, key is the template name and value is the StateSet instance
Name of the StateSetRunner Template
Initial data
Starts an StateSetRunner based on the StateSetRunner Template with the given indentifier.
Name of the state machine
Initial state, if nil the first state will be used if the StateMachineIter is ordered, can be an integer is the StateMachineIter is ordered
Initial data for the state machine, if nil uses empty table
Wrap a state machine definition so it can be used in a StateSet. This causes the StateMachineIter to be constructed and run in the context of the StateSetRunner. The first paramater to the StateMachineIter after the default paramaters is the StateSetRunner instance, those after are the extras passed to the StateSetRunner's run function. Externally the StateMachineIter's state can be accessed via the StateSetRunner's StateMachines table under the key of the StateSet's state name.
Object in question
Is this object an instance of StateSetRunner?
===================================================
_tracker
----BZ98R LUA Extended API Tracker.
Tracks objects by class and odf.
@todo deal with team swapping
local tracker = require("_tracker");
-- if no filters are set all objects will be tracked
tracker.setFilterTeam(1, true);
tracker.setFilterClass("TANK", true);
ClassName name to count.
Team number to count for.
Count object by ClassName @todo add protections
ClassSig name to count.
Team number to count for.
Count object by ClassSig @todo add protections
Odf name to count.
Team number to count for.
Count object by class @todo add protections
Class name to track.
Enable or disable tracking for the class. Defaults to true.
Enable tracking for a class. Note that items that no longer fit the filter will remain in the tracker. Note that on the next update if needed an AllObjects scan will be performed to update the tracker for new filtered items. Note that the odf and class filters are independent, so if you set a class filter to true and an odf filter to false, the class will be tracked but the odf will not.
Odf name to track.
Enable or disable tracking for the odf. Defaults to true.
Enable tracking for an odf. Note that items that no longer fit the filter will remain in the tracker. Note that on the next update if needed an AllObjects scan will be performed to update the tracker for new filtered items. Note that the odf and class filters are independent, so if you set a class filter to true and an odf filter to false, the class will be tracked but the odf will not.
Team number to track.
Enable or disable tracking for the team. Defaults to true.
Enable tracking for a team. Note that items that no longer fit the filter will remain in the tracker. Note that on the next update if needed an AllObjects scan will be performed to update the tracker for new filtered items.
===================================================
_unsaved
----BZ98R LUA Extended API Unsaved.
Crude custom type to make data not save/load exploiting the custom type system.
local unsaved = require("_unsaved");
data.unsavable = unsaved(data.unsavable);
Marks the table as unsaved, don't even bother with metatables
===================================================
_utility
----BZ98R LUA Extended API Utility.
TYPE: UNK_enum ClassLabel
SPECIAL: inner_type
GLYPH: bi bi-list-ul
----TYPE: UNK_enum ClassSig
SPECIAL: inner_type
GLYPH: bi bi-list-ul
----The class label or class signature.
The class label.
Get the ClassLabel string for any ClassSig or ClassLabel.
The class label or class signature.
The class signature.
Get the ClassSig string for any ClassLabel or ClassSig.
TYPE: UNK_enum TeamSlotIntegerEnum
SPECIAL: inner_type
GLYPH: bi bi-list-ul
----TYPE: UNK_enum TeamSlotRange
SPECIAL: inner_type
GLYPH: bi bi-list-ul
----@todo _fix uses this module, but _fix sets portal, so this needs some reorganization
TYPE: UNK_enum TeamSlotString
SPECIAL: inner_type
GLYPH: bi bi-list-ul
----Object in question
Is this object a Handle?
Object in question
Is this object a Matrix?
Object in question
Is this object a Vector?
Object in question
Is this object a boolean?
Object in question
Is this object a function?
Object in question
Is this object an integer?
Object in question
Is this object a number?
Object in question
Is this object a string?
Object in question
Is this object a table?
The items to choose from.
The chosen item.
Chooses a random item from a list of items.
The chosen item.
Chooses a random item from a list of weighted items.
The iterator to convert
The resulting array or table
Convert an iterator to an array or table. If the iterator returns only values, returns an array. If the iterator returns key-value pairs, returns a table.
The weight of the item.
TYPE: UNK_any
SPECIAL: inner_type
GLYPH: bi bi-question-circle
----The item to be chosen.
===================================================
_version
----BZ98R LUA Extended API Version Utility.
function iterating over all versions for easy output
Iterate all versions in a simple format. This function returns an iterator that yields key, label, and version for each version token.
The first version string
The second version string
-1, 0, or 1 depending on the comparison result
Compare two version strings.
This function compares two version strings in the format d, d.d, d.d.d, d.d.d.d, d.d.d.da, and d.d.d.dad where d is a digit and a is an alphanumeric character.
It returns -1 if version1 is less than version2, 1 if version1 is greater than version2, and 0 if they are equal.
The first version string
The second version string
The version of this LUA Extended API, e.g. "0.1.1"
The BZCP version, if available, e.g. "0.3"
The game version, e.g. "2.2.315"
The Lua version, e.g. "Lua 5.1"
The BZCP shim version, if available, e.g. 1
===================================================
_waves
----BZ98R LUA Extended API Wave Spawner.
Wave Spawner
@todo usage example
Checks if the WaveSpawner is alive. (Has waves left to spawn)
Loads the WaveSpawner state.
Saves the WaveSpawner state.
TYPE: table
SPECIAL: inner_type
GLYPH: bi bi-table
----OLD: A list of factions from which a random will be selected.
The frequency of waves.
TYPE: table
SPECIAL: inner_type
GLYPH: bi bi-table
----OLD: A list of locations where waves can spawn, considered if the name is not the same as a faction name, or it is the same as a selected faction.
The name of the wave spawner. "WaveSpawner:Spawned" event fired
The variance of wave frequency.
The time to wait before the next wave.
TYPE: table
SPECIAL: inner_type
GLYPH: bi bi-table
----OLD: Array of weighted formation tables
The number of waves left to spawn.
Array of strings, each string is a row, numbers are unit indices in 'units'
List of unit ODFs, indexed by number in formation
-- Distance between units (optional, default 10)
Spawns units in a specified formation at a location, facing a direction.
Creates a new WaveSpawner instance.