FreeSpace Wiki - User contributions [en]

Scripting functions

2012-07-15T12:08:35Z

Aginor: /* HudGauge */

This page explains all the functions mentioned in the scripting.html file, including their syntax, remarks on their use and common errors modders may encounter when they use them.

----

Script Output - FSO v3.6.13 (FS2_Open Scripting)

==Conditional Hooks==

===Conditions===
*State
*Campaign
*Mission
*Object Type
*Ship
*Ship class
*Ship type
*Weapon class
*KeyPress
*Version
*Application
**''Usually: $Application: FS2_Open''

===Actions===
*On Game Init
*On Splash Screen
*On State Start
*On Frame
*On Key Pressed
*On Key Released
*On Mouse Moved
*On Mouse Pressed
*On Mouse Released
*On State End
*On Mission Start
*On HUD Draw
*On Ship Collision
*On Weapon Collision
*On Debris Collision
*On Asteroid Collision
*On Object Render
*On Warp In
*On Warp Out
*On Death
*On Mission End
*On Weapon Delete
*On Weapon Equipped
*On Weapon Fired
*On Weapon Selected
*On Weapon Deselected
*On Gameplay Start
*On Turret Fired
*On Primary Fire
*On Secondary Fire

==Types==
===vector===
:'''Vector object'''
 
:''number [] x,y,z or 1-3''
::*Vector component
::*'''Returns:''' Value at index, or 0 if vector handle is invalid
 
:''[[Scripting_functions#vector|vector]] + number/vector''
::*Adds vector by another vector, or adds all axes by value
::*'''Returns:''' Final vector, or null vector if error occurs
 
:''[[Scripting_functions#vector|vector]] - number/vector''
::*Subtracts vector from another vector, or subtracts all axes by value
::*'''Returns:''' Final vector, or null vector if error occurs
 
:''[[Scripting_functions#vector|vector]] * number/vector''
::*Scales vector object (Multiplies all axes by number), or multiplies each axes by the other vector's axes.
::*''' Returns:''' Final vector, or null vector if error occurs
 
:''[[Scripting_functions#vector|vector]] / number/vector''
::*Scales vector object (Divide all axes by number), or divides each axes by the dividing vector's axes.
::*'''Returns:''' Final vector, or null vector if error occurs
 
:''string (string)''
::*Converts a vector to string with format "(x,y,z)"
::*'''Returns:''' Vector as string, or empty string if handle is invalid
 
:''[[Scripting_functions#orientation|orientation]]'' '''getOrientation()'''
::*Returns orientation object representing the direction of the vector. Does not require vector to be normalized.
::*'''Returns:''' Orientation object, or null orientation object if handle is invalid
 
:''number'' '''getMagnitude()'''
::*Returns the magnitude of a vector (Total regardless of direction)
::*'''Returns:''' Magnitude of vector, or 0 if handle is invalid
 
:''number'' '''getDistance('''''Vector''''')'''
::*Distance
::*'''Returns:''' Returns distance from another vector
 
:''number'' '''getDotProduct('''''vector OtherVector''''')'''
::*Returns dot product of vector object with vector argument
::*'''Returns:''' Dot product, or 0 if a handle is invalid
 
:''[[Scripting_functions#vector|vector]]'' '''getCrossProduct('''''vector OtherVector''''')'''
::*Returns cross product of vector object with vector argument
::*'''Returns:''' Cross product, or null vector if a handle is invalid
 
:''number,number'' '''getScreenCoords()'''
::*Gets screen cordinates of a world vector
::*'''Returns:''' X (number), Y (number), or false if off-screen
 
:''vector'' '''getNormalized()'''
::*Returns a normalized version of the vector
::*'''Returns:''' Normalized Vector, or NIL if invalid
 
===orientation===
Orientation matrix object

number [] p,b,h or 1-9
Orientation component - pitch, bank, heading, or index into 3x3 matrix (1-9)
Returns: Number at the specified index, or 0 if index is invalid.

orientation * orientation
Multiplies two matrix objects)
Returns: matrix, or empty matrix if unsuccessful

string (string)
Converts a matrix to a string with format "[r1c1 r2c1 r3c1 | r1c2 r2c2 r3c2| r1c3 r2c3 r3c3]"
Returns: Formatted string or "

orientation getInterpolated(orientation Final, number Factor)
Returns orientation that has been interpolated to Final by Factor (0.0-1.0)
Returns: Interpolated orientation, or null orientation on failure

orientation getTranspose()
Returns a transpose version of the specified orientation
Returns: Transpose matrix, or null orientation on failure

vector rotateVector(vector Input)
Returns rotated version of given vector
Returns: Rotated vector, or empty vector on error

vector unrotateVector(vector Input)
Returns unrotated version of given vector
Returns: Unrotated vector, or empty vector on error

===enumeration===
Enumeration object

enumeration = enumeration
Sets enumeration to specified value (if it is not a global
Returns: enumeration

string (string)
Returns enumeration name
Returns: Enumeration name, or "" if invalid

===event===
Mission event handle

string Name = string
Mission event name
Value: (null)

string DirectiveText = string
Directive text
Value: (null)

string DirectiveKeypressText = string
Raw directive keypress text, as seen in FRED.
Value: (null)

number Interval = number
Time for event to repeat (in seconds)
Value: Repeat time, or 0 if invalid handle

number ObjectCount = number
Number of objects left for event
Value: Repeat count, or 0 if invalid handle

number RepeatCount = number
Event repeat count
Value: Repeat count, or 0 if invalid handle

number Score = number
Event score
Value: Event score, or 0 if invalid handle

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===file===
File handle

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

nil close()
Instantly closes file and invalidates all file handles
Returns: Nothing

boolean flush()
Flushes file buffer to disk.
Returns: True for success, false on failure

string getPath()
Determines path of the given file
Returns: Path string of the file handle, or an empty string if it doesn't have one, or the handle is invalid

number or string, ... read(number or string, ...)
Reads part of or all of a file, depending on arguments passed. Based on basic Lua file:read function.Returns nil when the end of the file is reached.

* "*n" - Reads a number.
* "*a" - Reads the rest of the file and returns it as a string.
* "*l" - Reads a line. Skips the end of line markers.
* (number) - Reads given number of characters, then returns them as a string.

Returns: Requested data, or nil if the function fails

number seek([string Whence="cur", number Offset=0])
# Changes position of file, or gets location.Whence can be:"set" - File start.
# "cur" - Current position in file.
# "end" - File end.
Returns: new offset, or false or nil on failure

number write(string or number, ...)
Writes a series of Lua strings or numbers to the current file.
Returns: Number of items successfully written.

===font===
font handle

string (string)
Filename of font
Returns: Font filename, or an empty string if the handle is invalid

string Filename = string
Filename of font (including extension)
Value: (null)

number Height = number
Height of font (in pixels)
Value: Font height, or 0 if the handle is invalid

boolean isValid()
True if valid, false or nil if not
Returns: Detects whether handle is valid

===gameevent===
Game event

string (string)
Game event name
Returns: Game event name, or empty string if handle is invalid

string Name = string
Game event name
Value: Game event name, or empty string if handle is invalid

===gamestate===
:'''Game state'''
 
:''string (string)''
::*Game state name
::*'''Value:''' Game state name, or empty string if handle is invalid
 
:''string Name = string''
::*Game state name
::*'''Value:''' Game state name, or empty string if handle is invalid
 

===HudGauge===
:'''HUD Gauge handle'''
 
:''string Name = string''
::*Custom HUD Gauge name
::*'''Value:''' Custom HUD Gauge name, or nil if handle is invalid
 
:''string Text = string''
::*Custom HUD Gauge text
::*'''Value:''' Custom HUD Gauge text, or nil if handle is invalid
 

===eyepoint===
Eyepoint handle

vector Normal = vector
Eyepoint normal
Value: Eyepoint normal, or null vector if handle is invalid

vector Position = vector
Eyepoint location (Local vector)
Value: Eyepoint location, or null vector if handle is invalid

boolean IsValid()
Detect whether this handle is valid
Returns: true if valid false otherwise

===model===
3D Model (POF) handle

modeltextures_h Textures = modeltextures_h
Model textures
Value: Model textures, or an invalid modeltextures handle if the model handle is invalid

thrusters Thrusters = thrusters
Model thrusters
Value: Thrusters of the model or invalid handle

eyepoints Eyepoints = eyepoints
Model eyepoints
Value: Array of eyepoints or invalid handle on error

vector BoundingBoxMax = vector
Model bounding box maximum
Value: Model bounding box, or an empty vector if the handle is invalid

vector BoundingBoxMin = vector
Model bounding box minimum
Value: Model bounding box, or an empty vector if the handle is invalid

string Filename = string
Model filename
Value: Model filename, or an empty string if the handle is invalid

number Mass = number
Model mass
Value: Model mass, or 0 if the model handle is invalid

orientation MomentOfInertia = orientation
Model moment of inertia
Value: Moment of Inertia matrix or identity matrix if invalid

number Radius = number
Model radius (Used for collision & culling detection)
Value: Model Radius or 0 if invalid

boolean isValid()
True if valid, false or nil if not
Returns: Detects whether handle is valid

===modeltextures_h===
Array of materials

number #
Number of textures on model
Returns: Number of model textures

texture [] texture
number Index/string TextureName
Returns: Model textures, or invalid modeltextures handle if model handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===eyepoints===
Array of model eye points

number #
Gets the number of eyepoints on this model
Returns: Number of eyepoints on this model or 0 on error

eyepoint [] eyepoint
Gets en eyepoint handle
Returns: eye handle or invalid handle on error

boolean isValid()
Detects whether handle is valid or not
Returns: true if valid false otherwise

===thrusters===
The thrusters of a model

number #
Number of thruster banks on the model
Returns: Number of thrusterbanks

thrusterbank [] number Index
Array of all thrusterbanks on this thruster
Returns: Handle to the thrusterbank or invalid handle if index is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===thrusterbank===
A model thrusterbank

number #
Number of thrusters on this thrusterbank
Returns: Number of thrusters on this bank or 0 if handle is invalid

glowpoint [] number Index
Array of glowpoint
Returns: Glowpoint, or invalid glowpoint handle on failure

boolean isValid()
Detectes if this handle is valid
Returns: true if this handle is valid, false otherwise

===glowpoint===
A model glowpoint

vector Position
The (local) vector to the position of the glowpoint

number Radius
The radius of the glowpoint

boolean isValid()
Returns wether this handle is valid or not
Returns: True if handle is valid, false otherwise

===order===
order handle

boolean remove()
Removes the given order from the ship's priority queue.
Returns: True if order was successfully removed, otherwise false or nil.

===shiporders===
Ship orders

number #
Number of textures on ship
Returns: Number of textures on ship, or 0 if handle is invalid

order [] number Index/string TextureFilename
Array of ship orders
Returns: Order, or invalid texture handle on failure

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===physics===
Physics handle

number AfterburnerAccelerationTime = number
Afterburner acceleration time
Value: Afterburner acceleration time, or 0 if handle is invalid

vector AfterburnerVelocityMax = vector
Afterburner max velocity (Local vector)
Value: Afterburner max velocity, or null vector if handle is invalid

number BankingConstant = number
Banking constant
Value: Banking constant, or 0 if handle is invalid

number ForwardAccelerationTime = number
Forward acceleration time
Value: Forward acceleration time, or 0 if handle is invalid

number ForwardDecelerationTime = number
Forward deceleration time
Value: Forward decleration time, or 0 if handle is invalid

number ForwardThrust = number
Forward thrust amount (0-1), used primarily for thruster graphics
Value: Forward thrust, or 0 if handle is invalid

number Mass = number
Object mass
Value: Object mass, or 0 if handle is invalid

vector RotationalVelocity = vector
Rotational velocity (Local vector)
Value: Rotational velocity, or null vector if handle is invalid

number RotationalVelocityDamping = number
Rotational damping, ie derivative of rotational speed
Value: Rotational damping, or 0 if handle is invalid

number RotationalVelocityDesired = lvector
Desired rotational velocity
Value: Desired rotational velocity, or 0 if handle is invalid

vector RotationalVelocityMax = vector
Maximum rotational velocity (Local vector)
Value: Maximum rotational velocity, or null vector if handle is invalid

number ShockwaveShakeAmplitude = number
How much shaking from shockwaves is applied to object
Value: Shockwave shake amplitude, or 0 if handle is invalid

number SideThrust = number
Side thrust amount (0-1), used primarily for thruster graphics
Value: Side thrust amount, or 0 if handle is invalid

number SlideAccelerationTime = number
Time to accelerate to maximum slide velocity
Value: Sliding acceleration time, or 0 if handle is invalid

number SlideDecelerationTime = number
Time to decelerate from maximum slide speed
Value: Sliding deceleration time, or 0 if handle is invalid

vector Velocity = vector
Object world velocity (World vector)
Value: Object velocity, or null vector if handle is invalid

vector VelocityDesired = vector
Desired velocity (World vector)
Value: Desired velocity, or null vector if handle is invalid

vector VelocityMax = vector
Object max local velocity (Local vector)
Value: Maximum velocity, or null vector if handle is invalid

number VerticalThrust = number
Vertical thrust amount (0-1), used primarily for thruster graphics
Value: Vertical thrust amount, or 0 if handle is invalid

boolean AfterburnerActive = boolean
Specifies if the afterburner is active or not
Value: true if afterburner is active false otherwise

boolean isValid()
True if valid, false or nil if not
Returns: Detects whether handle is valid

number getSpeed()
Gets total speed as of last frame
Returns: Total speed, or 0 if handle is invalid

number getForwardSpeed()
Gets total speed in the ship's 'forward' direction as of last frame
Returns: Total forward speed, or 0 if handle is invalid

boolean isAfterburnerActive()
True if Afterburners are on, false or nil if not
Returns: Detects whether afterburner is active

boolean isGliding()
True if glide mode is on, false or nil if not
Returns: Detects if ship is gliding

===sexpvariable===
SEXP Variable handle

enumeration Persistence = enumeration
SEXP Variable persistance, uses SEXPVAR_*_PERSISTENT enumerations
Value: SEXPVAR_*_PERSISTENT enumeration, or invalid numeration if handle is invalid

enumeration Type = enumeration
SEXP Variable type, uses SEXPVAR_TYPE_* enumerations
Value: SEXPVAR_TYPE_* enumeration, or invalid numeration if handle is invalid

string Value = number/string
SEXP variable value
Value: SEXP variable contents, or nil if the variable is of an invalid type or the handle is invalid

string (string)
Returns SEXP name
Returns: SEXP name, or empty string if handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

boolean delete()
Deletes a SEXP Variable
Returns: True if successful, false if the handle is invalid

===shields===
Shields handle

number [] enumeration/number
Gets or sets shield quadrant strength. Use "SHIELD_*" enumeration or 1-4 for a specific quadrant, or NONE for the entire shield
Returns: Quadrant/shield strength, or 0 if handle is invalid

number CombinedLeft = number
Total shield hitpoints left (for all quadrants combined)
Value: Combined shield strength, or 0 if handle is invalid

number CombinedMax = number
Maximum shield hitpoints (for all quadrants combined)
Value: Combined maximum shield strength, or 0 if handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===shiptype===
Ship type handle

string Name = string
Ship type name
Value: Ship type name, or empty string if handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===species===
Species handle

string Name = string
Species name
Value: Species name, or empty string if handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===team===
Team handle

boolean == team, team
Checks whether two teams are the same team
Returns: true if equal

string Name = string
Team name
Value: Team name, or empty string if handle is invalid

number, number, number getColor()
Gets the IFF color of the specified Team
Returns: rgb color for the specified team or nil if invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===texture===
Texture handle

nil __gc
Auto-deletes texture
Returns: Nothing

boolean == texture, texture
Checks if two texture handles refer to the same texture
Returns: True if textures are equal

texture [] number
Returns texture handle to specified frame number in current texture's animation.This means that [1] will always return the first frame in an animation, no matter what frame an animation is.You cannot change a texture animation frame.
Returns: Texture handle, or invalid texture handle if index is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

nil unload()
Unloads a texture from memory
Returns: Nothing

string getFilename()
Returns filename for texture
Returns: Filename, or empty string if handle is invalid

number getWidth()
Gets texture width
Returns: Texture width, or 0 if handle is invalid

number getHeight()
Gets texture height
Returns: Texture height, or 0 if handle is invalid

number getFPS()
Gets frames-per-second of texture
Returns: Texture FPS, or 0 if handle is invalid

number getFramesLeft()
Gets number of frames left, from handle's position in animation
Returns: Frames left, or 0 if handle is invalid

===material===
Texture map, including diffuse, glow, and specular textures

texture BaseMap = texture
Base texture
Value: Base texture, or invalid texture handle if material handle is invalid

texture GlowMap = texture
Glow texture
Value: Glow texture, or invalid texture handle if material handle is invalid

texture SpecularMap = texture
Specular texture
Value: Texture handle, or invalid texture handle if material handle is invalid

===weaponclass===
Weapon class handle

string (string)
Weapon class name
Returns: Weapon class name, or an empty string if handle is invalid

string Name = string
Weapon class name
Value: Weapon class name, or empty string if handle is invalid

string Title = string
Weapon class title
Value: Weapon class title, or empty string if handle is invalid

string Description = string
Weapon class description string
Value: Description string, or empty string if handle is invalid

string TechTitle = string
Weapon class tech title
Value: Tech title, or empty string if handle is invalid

string TechAnimationFilename = string
Weapon class animation filename
Value: Filename, or empty string if handle is invalid

string TechDescription = string
Weapon class tech description string
Value: Description string, or empty string if handle is invalid

model Model = model
Model
Value: Weapon class model, or invalid model handle if weaponclass handle is invalid

number ArmorFactor = number
Amount of weapon damage applied to ship hull (0-1.0)
Value: Armor factor, or empty string if handle is invalid

number Damage = number
Amount of damage that weapon deals
Value: Damage amount, or 0 if handle is invalid

number FireWait = number
Weapon fire wait (cooldown time) in seconds
Value: Fire wait time, or 0 if handle is invalid

number FreeFlightTime = number
The time the weapon will fly before turing onto its target
Value: Free flight time or emty string if invalid

number LifeMax = number
Life of weapon in seconds
Value: Life of weapon, or 0 if handle is invalid

number Range = number
Range of weapon in meters
Value: Weapon Range, or 0 if handle is invalid

number Mass = number
Weapon mass
Value: Weapon mass, or 0 if handle is invalid

number ShieldFactor = number
Amount of weapon damage applied to ship shields (0-1.0)
Value: Shield damage factor, or 0 if handle is invalid

number SubsystemFactor = number
Amount of weapon damage applied to ship subsystems (0-1.0)
Value: Subsystem damage factor, or 0 if handle is invalid

number TargetLOD = number
LOD used for weapon model in the targeting computer
Value: LOD number, or 0 if handle is invalid

number Speed = number
Weapon max speed, aka $Velocity in weapons.tbl
Value: Weapon speed, or 0 if handle is invalid

boolean Bomb = boolean
Is weapon class flagged as bomb
Value: New flag

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

number getWeaponClassIndex()
Gets the index value of the weapon class
Returns: index value of the weapon class

boolean isLaser()
Return true if the weapon is a laser (this includes balistic primaries)
Returns: true if the weapon is a laser, false otherwise

boolean isMissile()
Return true if the weapon is a missile
Returns: true if the weapon is a missile, false otherwise

boolean isBeam()
Return true if the weapon is a beam
Returns: true if the weapon is a beam, false otherwise

===collision info===
Information about a collision

nil __gc
Removes the allocated reference of this handle
Returns: Nothing

model Model = model
The model this collision info is about
Value: The model

number getCollisionDistance()
The distance to the closest collision point
Returns: distance or -1 on error

vector getCollisionPoint([boolean local])
The collision point of this information (local to the object if boolean is set to true)
Returns: The collision point or nil of none

vector getCollisionNormal([boolean local])
The collision normal of this information (local to object if boolean is set to true)
Returns: The collision normal or nil of none

boolean isValid()
Detects if this handle is valid
Returns: true if valid false otherwise

===object===
Object handle

boolean == object, object
Checks whether two object handles are for the same object
Returns: True if equal, false if not or a handle is invalid

string (string)
Returns name of object (if any)
Returns: Object name, or empty string if handle is invalid

object Parent = object
Parent of the object. Value may also be a deriviative of the 'object' class, such as 'ship'.
Value: Parent handle, or invalid handle if object is invalid

vector Position = vector
Object world position (World vector)
Value: World position, or null vector if handle is invalid

vector LastPosition = vector
Object world position as of last frame (World vector)
Value: World position, or null vector if handle is invalid

orientation Orientation = orientation
Object world orientation (World orientation)
Value: Orientation, or null orientation if handle is invalid

orientation LastOrientation = orientation
Object world orientation as of last frame (World orientation)
Value: Orientation, or null orientation if handle is invalid

physics Physics = physics
Physics data used to move ship between frames
Value: Physics data, or invalid physics handle if object handle is invalid

number HitpointsLeft = number
Hitpoints an object has left
Value: Hitpoints left, or 0 if handle is invalid

shields Shields = shields
Shields
Value: Shields handle, or invalid shields handle if object handle is invalid

number getSignature()
Gets the object's unique signature
Returns: Returns the objects unique numeric signature, or -1 if invalid. useful for creating a metadata sytem

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

string getBreedName()
Gets object type
Returns: Object type name, or empty string if handle is invalid

number CollisionGroups = number
Collision group data
Value: Current collision group signature. NOTE: This is a bitfield, NOT a normal number.

vector getfvec([boolean normalize])
Returns the objects' current fvec.
Returns: Objects' forward vector, or nil if invalid. If called with a true argument, vector will be normalized.

vector getuvec([boolean normalize])
Returns the objects' current uvec.
Returns: Objects' up vector, or nil if invalid. If called with a true argument, vector will be normalized.

vector getrvec([boolean normalize])
Returns the objects' current rvec.
Returns: Objects' rvec, or nil if invalid. If called with a true argument, vector will be normalized.

vector, collision info checkRayCollision(vector Start Point, vector End Point, [boolean Local])
Checks the collisions between the polygons of the current object and a ray
Returns: World collision point (local if boolean is set to true) and the specific collsision info, nil if no collisions

===asteroid:object===
Asteroid handle

object Target = object
Asteroid target object; may be object derivative, such as ship.
Value: Target object, or invalid handle if asteroid handle is invalid

boolean kill([ship killer=nil, wvector hitpos=nil])
Kills the asteroid. Set "killer" to designate a specific ship as having been the killer, and "hitpos" to specify the world position of the hit location; if nil, the asteroid center is used.
Returns: True if successful, false or nil otherwise

===shipclass===
Ship class handle

string (string)
Ship class name
Returns: Ship class name, or an empty string if handle is invalid

string Name = string
Ship class name
Value: Ship class name, or an empty string if handle is invalid

string ShortName = string
Ship class short name
Value: Ship short name, or empty string if handle is invalid

string TypeString = string
Ship class type string
Value: Type string, or empty string if handle is invalid

string ManeuverabilityString = string
Ship class maneuverability string
Value: Maneuverability string, or empty string if handle is invalid

string ArmorString = string
Ship class armor string
Value: Armor string, or empty string if handle is invalid

string ManufacturerString = string
Ship class manufacturer
Value: Manufacturer, or empty string if handle is invalid

string Description = string
Ship class description
Value: Description, or empty string if handle is invalid

string TechDescription = string
Ship class tech description
Value: Tech description, or empty string if handle is invalid

number AfterburnerFuelMax = number
Afterburner fuel capacity
Value: Afterburner capacity, or 0 if handle is invalid

number CountermeasuresMax = number
Maximum number of countermeasures the ship can carry
Value: Countermeasure capacity, or 0 if handle is invalid

model Model = model
Model
Value: Ship class model, or invalid model handle if shipclass handle is invalid

model CockpitModel = model
Model used for first-person cockpit
Value: Cockpit model

number HitpointsMax = number
Ship class hitpoints
Value: Hitpoints, or 0 if handle is invalid

species Species = Species
Ship class species
Value: Ship class species, or invalid species handle if shipclass handle is invalid

shiptype Type = shiptype
Ship class type
Value: Ship type, or invalid handle if shipclass handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

boolean isInTechroom()
Gets whether or not the ship class is available in the techroom
Returns: Whether ship has been revealed in the techroom, false if handle is invalid

boolean renderTechModel(X1, Y1, X2, Y2, [Rotation %, Pitch %, Bank %, Zoom multiplier])
Draws ship model as if in techroom
Returns: Whether ship was rendered

boolean renderTechModel2(X1, Y1, X2, Y2, orientation Orientation=null, [Zoom multiplier])
Draws ship model as if in techroom
Returns: Whether ship was rendered

boolean isModelLoaded([boolean Load = false])
Checks if the model used for this shipclass is loaded or not and optionally loads the model, which might be a slow operation.
Returns: If the model is loaded or not

number getShipClassIndex()
Gets the index valus of the ship class
Returns: index value of the ship class

===debris:object===
Debris handle

boolean IsHull = boolean
Whether or not debris is a piece of hull
Value: Whether debris is a hull fragment, or false if handle is invalid

shipclass OriginClass = shipclass
The shipclass of the ship this debris originates from
Value: The shipclass of the ship that created this debris

number getDebrisRadius()
The radius of this debris piece
Returns: The radius of this debris piece or -1 if invalid

boolean isValid()
Return if this debris handle is valid
Returns: true if valid false otherwise

===waypoint:object===
waypoint handle

===waypointlist===
waypointlist handle

waypoint [] number Index
Array of waypoints that are part of the waypoint list
Returns: Waypoint, or invalid handle if the index or waypointlist handle is invalid

number #
Number of waypoints in the list. Note that the value returned cannot be relied on for more than one frame.
Returns: Number of waypoints in the list, or 0 if handle is invalid

string Name = string
Name of WaypointList
Value: Waypointlist name, or empty string if handle is invalid

===weaponbank===
Ship/subystem weapons bank handle

weaponclass WeaponClass = weaponclass
Class of weapon mounted in the bank
Value: Weapon class, or an invalid weaponclass handle if bank handle is invalid

number AmmoLeft = number
Ammo left for the current bank
Value: Ammo left, or 0 if handle is invalid

number AmmoMax = number
Maximum ammo for the current bank
Value: Ammo capacity, or 0 if handle is invalid

boolean Armed = boolean
Weapon armed status. Does not take linking into account.
Value: True if armed, false if unarmed or handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===weaponbanktype===
Ship/subsystem weapons bank type handle

weaponbank [] number Index
Array of weapon banks
Returns: Weapon bank, or invalid handle on failure

boolean Linked = boolean
Whether bank is in linked or unlinked fire mode (Primary-only)
Value: Link status, or false if handle is invalid

boolean DualFire = boolean
Whether bank is in dual fire mode (Secondary-only)
Value: Dual fire status, or false if handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

number #
Number of weapons in the mounted bank
Returns: Number of bank weapons, or 0 if handle is invalid

===subsystem===
Ship subsystem handle

string (string)
Returns name of subsystem
Returns: Subsystem name, or empty string if handle is invalid

string ArmorClass = string
Current Armor class
Value: Armor class name, or empty string if none is set

number AWACSIntensity = number
Subsystem AWACS intensity
Value: AWACS intensity, or 0 if handle is invalid

number AWACSRadius = number
Subsystem AWACS radius
Value: AWACS radius, or 0 if handle is invalid

orientation Orientation = orientation
Orientation of subobject or turret base
Value: Subsystem orientation, or null orientation if handle is invalid

orientation GunOrientation = orientation
Orientation of turret gun
Value: Gun orientation, or null orientation if handle is invalid

number HitpointsLeft = number
Subsystem hitpoints left
Value: Hitpoints left, or 0 if handle is invalid. Setting a value of 0 will disable it - set a value of -1 or lower to actually blow it up.

number HitpointsMax = number
Subsystem hitpoints max
Value: Max hitpoints, or 0 if handle is invalid

vector Position = vector
Subsystem position with regards to main ship (Local Vector)
Value: Subsystem position, or null vector if subsystem handle is invalid

vector GunPosition = vector
Subsystem gun position with regards to main ship (Local vector)
Value: Gun position, or null vector if subsystem handle is invalid

string Name = string
Subsystem name
Value: Subsystem name, or an empty string if handle is invalid

string getModelName()
Returns the original name of the subsystem in the model file
Returns: name or empty string on error

weaponbanktype PrimaryBanks = weaponbanktype
Array of primary weapon banks
Value: Primary banks, or invalid weaponbanktype handle if subsystem handle is invalid

weaponbanktype SecondaryBanks = weaponbanktype
Array of secondary weapon banks
Value: Secondary banks, or invalid weaponbanktype handle if subsystem handle is invalid

object Target = object
Object targetted by this subsystem. If used to set a new target, AI targeting will be switched off.
Value: Targeted object, or invalid object handle if subsystem handle is invalid

boolean TurretResets = boolean
Specifies wether this turrets resets after a certain time of inactivity
Value: true if turret resets, false otherwise

number TurretResetDelay = number
The time (in milliseconds) after that the turret resets itself
Value: Reset delay

number TurnRate = number
The turn rate
Value: Turnrate or -1 on error

boolean TurretLocked = boolean
Whether the turret is locked. Setting to true locks the turret, setting to false frees it.
Value: True if turret is locked, false otherwise

number NextFireTimestamp = number
The next time the turret may attempt to fire
Value: Mission time (seconds) or -1 on error

boolean targetingOverride(boolean)
If set to true, AI targeting for this turret is switched off. If set to false, the AI will take over again.
Returns: Returns true if successful, false otherwise

boolean hasFired()
Determine if a subsystem has fired
Returns: true if if fired, false if not fired, or nil if invalid. resets fired flag when called.

boolean isTurret()
Determines if this subsystem is a turret
Returns: true if subsystem is turret, false otherwise or nil on error

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

nil fireWeapon([Turret weapon index = 1, Flak range = 100])
Fires weapon on turret
Returns: Nothing

boolean rotateTurret(vector Pos[, boolean reset=false)
Rotates the turret to face Pos or resets the turret to its original state
Returns: true on success false otherwise

vector getTurretHeading()
Returns the turrets forward vector
Returns: Returns a normalized version of the forward vector or null vector on error

number, number, number getFOVs()
Returns current turrets FOVs
Returns: Standard FOV, maximum barrel elevation, turret base fov.

matrix getTurretMatrix()
Returns current subsystems turret matrix
Returns: Turret matrix.

===shiptextures===
Ship textures handle

number #
Number of textures on ship
Returns: Number of textures on ship, or 0 if handle is invalid

texture [] number Index/string TextureFilename
Array of ship textures
Returns: Texture, or invalid texture handle on failure

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===ship:object===
Ship handle

subsystem [] string Name/number Index
Array of ship subsystems
Returns: Subsystem handle, or invalid subsystem handle if index or ship handle is invalid

number #
Number of subsystems on ship
Returns: Subsystem number, or 0 if handle is invalid

string ShieldArmorClass = string
Current Armor class of the ships' shield
Value: Armor class name, or empty string if none is set

string ArmorClass = string
Current Armor class
Value: Armor class name, or empty string if none is set

string Name = string
Ship name
Value: Ship name, or empty string if handle is invalid

number AfterburnerFuelLeft = number
Afterburner fuel left
Value: Afterburner fuel left, or 0 if handle is invalid

number AfterburnerFuelMax = number
Afterburner fuel capacity
Value: Afterburner fuel capacity, or 0 if handle is invalid

shipclass Class = shipclass
Ship class
Value: Ship class, or invalid shipclass handle if ship handle is invalid

number CountermeasuresLeft = number
Number of countermeasures left
Value: Countermeasures left, or 0 if ship handle is invalid

weaponclass CountermeasureClass = weaponclass
Weapon class mounted on this ship's countermeasure point
Value: Countermeasure hardpoint weapon class, or invalid weaponclass handle if no countermeasure class or ship handle is invalid

number HitpointsMax = number
Total hitpoints
Value: Ship maximum hitpoints, or 0 if handle is invalid

number WeaponEnergyLeft = number
Current weapon energy reserves
Value: Ship current weapon energy reserve level, or 0 if invalid

number WeaponEnergyMax = number
Maximum weapon energy
Value: Ship maximum weapon energy reserve level, or 0 if invalid

boolean PrimaryTriggerDown = boolean
Determines if primary trigger is pressed or not
Value: True if pressed, false if not, nil if ship handle is invalid

weaponbanktype PrimaryBanks = weaponbanktype
Array of primary weapon banks
Value: Primary weapon banks, or invalid weaponbanktype handle if ship handle is invalid

weaponbanktype SecondaryBanks = weaponbanktype
Array of secondary weapon banks
Value: Secondary weapon banks, or invalid weaponbanktype handle if ship handle is invalid

weaponbanktype TertiaryBanks = weaponbanktype
Array of tertiary weapon banks
Value: Tertiary weapon banks, or invalid weaponbanktype handle if ship handle is invalid

object Target = object
Target of ship. Value may also be a deriviative of the 'object' class, such as 'ship'.
Value: Target object, or invalid object handle if no target or ship handle is invalid

subsystem TargetSubsystem = subsystem
Target subsystem of ship.
Value: Target subsystem, or invalid subsystem handle if no target or ship handle is invalid

team Team = team
Ship's team
Value: Ship team, or invalid team handle if ship handle is invalid

shiptextures Textures = shiptextures
Gets ship textures
Value: Ship textures, or invalid shiptextures handle if ship handle is invalid

boolean FlagAffectedByGravity = boolean
Checks for the "affected-by-gravity" flag
Value: True if flag is set, false if flag is not set and nil on error

boolean Disabled = boolean
The disabled state of this ship
Value: true if ship is diabled, false otherwise

boolean kill([object Killer])
Kills the ship. Set "Killer" to the ship you are killing to self-destruct
Returns: True if successful, false or nil otherwise

boolean addShipEffect(string name, int duration (in milliseconds))
Activates an effect for this ship. Effect names are defined in Post_processing.tbl, and need to be implemented in the main shader. This functions analogous to the ship-effect sexp. NOTE: only one effect can be active at any time, adding new effects will override effects already in progress.
Returns: Returns true if the effect was successfully added, false otherwise

number hasShipExploded()
Checks if the ship explosion event has already happened
Returns: Returns 1 if first explosion timestamp is passed, 2 if second is passed, 0 otherwise

boolean fireCountermeasure()
Launches a countermeasure from the ship
Returns: Whether countermeasure was launched or not

number firePrimary()
Fires ship primary bank(s)
Returns: Number of primary banks fired

number fireSecondary()
Fires ship secondary bank(s)
Returns: Number of secondary banks fired

number getAnimationDoneTime(number Type, number Subtype)
Gets time that animation will be done
Returns: Time (seconds), or 0 if ship handle is invalid

boolean clearOrders()
Clears a ship's orders list
Returns: True if successful, otherwise false or nil

boolean giveOrder(enumeration Order, [object Target=nil, subsystem TargetSubsystem=nil, number Priority=1.0])
Uses the goal code to execute orders
Returns: True if order was given, otherwise false or nil

boolean doManeuver(number Duration, number Heading, number Pitch, number Bank, boolean Force Rotation, number Vertical, number Horizontal, number Forward, boolean Force Movement)
Sets ship maneuver over the defined time period
Returns: True if maneuver order was given, otherwise false or nil

boolean triggerAnimation(string Type, [number Subtype, boolean Forwards])
Triggers an animation. Type is the string name of the animation type, Subtype is the subtype number, such as weapon bank #, and Forwards is boolean.
IMPORTANT: Function is in testing and should not be used with official mod releases
Returns: True if successful, false or nil otherwise

boolean warpIn()
Warps ship in
Returns: True if successful, or nil if ship handle is invalid

boolean warpOut()
Warps ship out
Returns: True if successful, or nil if ship handle is invalid

boolean isWarpingIn()
Checks if ship is warping in
Returns: True if the ship is warping in, false or nil otherwise

number getEMP()
Returns the current emp effect strength acting on the object
Returns: Current EMP effect strength or NIL if object is invalid

number getTimeUntilExplosion()
Returns the time in seconds until the ship explodes
Returns: Time until explosion or -1, if invalid handle or ship isn't exploding

===weapon:object===
Weapon handle

weaponclass Class = weaponclass
Weapon's class
Value: Weapon class, or invalid weaponclass handle if weapon handle is invalid

boolean DestroyedByWeapon = boolean
Whether weapon was destroyed by another weapon
Value: True if weapon was destroyed by another weapon, false if weapon was destroyed by another object or if weapon handle is invalid

number LifeLeft = number
Weapon life left (in seconds)
Value: Life left (seconds) or 0 if weapon handle is invalid

number FlakDetonationRange = number
Range at which flak will detonate (meters)
Value: Detonation range (meters) or 0 if weapon handle is invalid

object Target = object
Target of weapon. Value may also be a deriviative of the 'object' class, such as 'ship'.
Value: Weapon target, or invalid object handle if weapon handle is invalid

subsystem ParentTurret = subsystem
Turret which fired this weapon.
Value: Turret subsystem handle, or an invalid handle if the weapon not fired from a turret

object HomingObject = object
Object that weapon will home in on. Value may also be a deriviative of the 'object' class, such as 'ship'
Value: Object that weapon is homing in on, or an invalid object handle if weapon is not homing or the weapon handle is invalid

vector HomingPosition = vector
Position that weapon will home in on (World vector)
Value: Homing point, or null vector if weapon handle is invalid

subsystem HomingSubsystem = subsystem
Subsystem that weapon will home in on.
Value: Homing subsystem, or invalid subsystem handle if weapon is not homing or weapon handle is invalid

team Team = team
Weapon's team
Value: Weapon team, or invalid team handle if weapon handle is invalid

boolean isArmed([boolean Hit target])
Checks if the weapon is armed.
Returns: boolean value of the weapon arming status

collision info getCollisionInformation()
Returns the collision information for this weapon
Returns: The collision information or invalid handle if none

===beam:object===
Beam handle

weaponclass Class = weaponclass
Weapon's class
Value: Weapon class, or invalid weaponclass handle if beam handle is invalid

vector LastShot = vector
End point of the beam
Value: vector or null vector if beam handle is not valid

vector LastStart = vector
Start point of the beam
Value: vector or null vector if beam handle is not valid

object Target = object
Target of beam. Value may also be a deriviative of the 'object' class, such as 'ship'.
Value: Beam target, or invalid object handle if beam handle is invalid

subsystem TargetSubsystem = subsystem
Subsystem that beam is targeting.
Value: Target subsystem, or invalid subsystem handle if beam handle is invalid

object ParentShip = object
Parent of the beam.
Value: Beam parent, or invalid object handle if beam handle is invalid

subsystem ParentSubsystem = subsystem
Subsystem that beam is fired from.
Value: Parent subsystem, or invalid subsystem handle if beam handle is invalid

number getCollisionCount()
Get the number of collisions in frame.
Returns: Number of beam collisions

vector getCollisionPosition(number)
Get the position of the defined collision.
Returns: World vector

collision info getCollisionInformation(number)
Get the collision information of the specified collision
Returns: handle to information or invalid handle on error

object getCollisionObject(number)
Get the target of the defined collision.
Returns: Object the beam collided with

boolean isExitCollision(number)
Checks if the defined collision was exit collision.
Returns: True if the collision was exit collision, false if entry, nil otherwise

vector getStartDirectionInfo()
Gets the start information about the direction. The vector is a normalized vector from LastStart showing the start direction of a slashing beam
Returns: The start direction or null vector if invalid

vector getEndDirectionInfo()
Gets the end information about the direction. The vector is a normalized vector from LastStart showing the end direction of a slashing beam
Returns: The start direction or null vector if invalid

===wing===
Wing handle

ship [] number Index
Array of ships in the wing
Returns: Ship handle, or invalid ship handle if index is invawing handle is invalid

number #
Number of wings in mission
Returns: Number of wings in mission

===player===
Player handle

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

string getName()
Gets current player name
Returns: Player name, or empty string if handle is invalid

string getCampaignFilename()
Gets current player campaign filename
Returns: Campaign name, or empty string if handle is invalid

string getImageFilename()
Gets current player image filename
Returns: Player image filename, or empty string if handle is invalid

number getMainHall()
Gets player's main hall number
Returns: Main hall index, or 1 if handle is invalid

string getSquadronName()
Gets current player squad name
Returns: Squadron name, or empty string if handle is invalid

===camera===
Camera handle

string (string)
Camera name
Returns: Camera name, or an empty string if handle is invalid

boolean isValid()
True if valid, false or nil if not
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

string Name = string
New camera name
Value: Camera name

number FOV = number
New camera FOV (in radians)
Value: Camera FOV (in radians)

orientation Orientation = orientation
New camera orientation
Value: Camera orientation

vector Position = vector
New camera position
Value: Camera position

object Self = object
New mount object
Value: Camera object

subsystem SelfSubsystem = subsystem
New mount object subsystem
Value: Subsystem that the camera is mounted on

object Target = object
New target object
Value: Camera target object

subsystem TargetSubsystem = subsystem
New target subsystem
Value: Subsystem that the camera is pointed at

boolean setFOV([number FOV, number Zoom Time, number Zoom Acceleration Time, number Zoom deceleration Time])
Sets camera FOV
FOV is the final field of view, in radians, of the camera.
Zoom Time is the total time to take zooming in or out.
Acceleration Time is the total time it should take the camera to get up to full zoom speed.
Deceleration Time is the total time it should take the camera to slow down from full zoom speed.
Returns: true if successful, false or nil otherwise

boolean setOrientation([world orientation Orientation, number Rotation Time, number Acceleration Time, number Deceleration time])
Sets camera orientation and velocity data.
Orientation is the final orientation for the camera, after it has finished moving. If not specified, the camera will simply stop at its current orientation.
Rotation time is how long total, including acceleration, the camera should take to rotate. If it is not specified, the camera will jump to the specified orientation.
Acceleration time is how long it should take the camera to get 'up to speed'. If not specified, the camera will instantly start moving.
Deceleration time is how long it should take the camera to slow down. If not specified, the camera will instantly stop moving.
Returns: true if successful, false or nil otherwise

boolean setPosition([wvector Position, number Translation Time, number Acceleration Time, number Deceleration Time])
Sets camera position and velocity data.
Position is the final position for the camera. If not specified, the camera will simply stop at its current position.
Translation time is how long total, including acceleration, the camera should take to move. If it is not specified, the camera will jump to the specified position.
Acceleration time is how long it should take the camera to get 'up to speed'. If not specified, the camera will instantly start moving.
Deceleration time is how long it should take the camera to slow down. If not specified, the camera will instantly stop moving.
Returns: true if successful, false or nil otherwise

===soundentry===
sounds.tbl table entry handle

number DefaultVolume = number
The default volume of this game sound
Value: Volume in the range from 1 to 0 or -1 on error

string getFilename()
Returns the filename of this sound
Returns: filename or empty string on error

number getDuration()
Gives the length of the sound in seconds.
Returns: the length, or -1 on error

number, number get3DValues(vector Postion[, number radius=0.0])
Computes the volume and the panning of the sound when it would be played from the specified position.
If range is given then the volume will diminish when the listener is withing that distance to the source.
The position of the listener is always the the current viewing position.
Returns: The volume and the panning, in that sequence, or both -1 on error

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===sound===
sound instance handle

number Pitch = number
Pitch of sound, from 100 to 100000
Value: Pitch, or 0 if handle is invalid

number getRemainingTime()
The remaining time of this sound handle
Returns: Remaining time, or -1 on error

boolean setVolume(number)
Sets the volume of this sound instance
Returns: true if succeeded, false otherwise

boolean setPanning(number)
Sets the panning of this sound. Argument ranges from -1 for left to 1 for right
Returns: true if succeeded, false otherwise

boolean setPosition(number[,boolean = true])
Sets the absolute position of the sound. If boolean argument is true then the value is given as a percentage
Returns: true if successfull, false otherwise

boolean rewind(number)
Rewinds the sound by the given number of seconds
Returns: true if succeeded, false otherwise

boolean skip(number)
Skips the given number of seconds of the sound
Returns: true if succeeded, false otherwise

boolean isPlaying()
Specifies if this handle is currently playing
Returns: true if playing, false if otherwise

boolean stop()
Stops the sound of this handle
Returns: true if succeeded, false otherwise

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===3Dsound:sound===
3D sound instance handle

boolean updatePosition(vector Position[, number radius = 0.0])
Updates the given 3D sound with the specified position and an optional range value
Returns: true if succeesed, false otherwise

===control info===
control info handle

number Pitch = number
Pitch of the player ship
Value: Pitch

number Heading = number
Heading of the player ship
Value: Heading

number Bank = number
Bank of the player ship
Value: Bank

number Vertical = number
Vertical control of the player ship
Value: Vertical control

number Sideways = number
Sideways control of the player ship
Value: Sideways control

number Forward = number
Forward control of the player ship
Value: Forward

number ForwardCruise = number
Forward control of the player ship
Value: Forward

number PrimaryCount = number
Number of primary weapons that will fire
Value: Number of weapons to fire, or 0 if handle is invalid

number SecondaryCount = number
Number of secondary weapons that will fire
Value: Number of weapons to fire, or 0 if handle is invalid

number CountermeasureCount = number
Number of countermeasures that will launch
Value: Number of countermeasures to launch, or 0 if handle is invalid

nil clearLuaButtonInfo()
Clears the lua button control info
Returns: Nothing

number, number, number,number getButtonInfo()
Access the four bitfields containing the button info
Returns: Four bitfields

number, number, number,number accessButtonInfo(number, number, number, number)
Access the four bitfields containing the button info
Returns: Four bitfields

nil useButtonControl(number, string)
Adds the defined button control to lua button control data, if number is -1 it tries to use the string
Returns: Nothing

string getButtonControlName(number)
Gives the name of the command corresponding with the given number
Returns: Name of the command

number getButtonControlNumber(string)
Gives the number of the command corresponding with the given string
Returns: Number of the command

boolean AllButtonPolling = boolean
Toggles the all button polling for lua
Value: If the all button polling is enabled or not

number, number, number,number pollAllButtons()
Access the four bitfields containing the button info
Returns: Four bitfields

===particle===
Handle to a particle

vector Position = vector
The current position of the particle (world vector)
Value: The current position

vector Velocity = vector
The current velocity of the particle (world vector)
Value: The current velocity

number Age = number
The time this particle already lives
Value: The current age or -1 on error

number MaximumLife = number
The time this particle can live
Value: The maximal life or -1 on error

number Radius = number
The radius of the particle
Value: The radius or -1 on error

number TracerLength = number
The tracer legth of the particle
Value: The radius or -1 on error

object AttachedObject = object
The object this particle is attached to. If valid the position will be relativ to this object and the velocity will be ignored.
Value: Attached object or invalid object handle on error

boolean isValid()
Detects whether this handle is valid
Returns: true if valid false if not

==Libraries==
===Audio (ad)===
Sound/Music Library

soundentry getSoundentry(string/number)
Return a sound entry matching the specified index or name. If you are using a number then the first valid index is 1
Returns: soundentry or invalid handle on error

sound playSound(soundentry)
Plays the specified sound entry handle
Returns: A handle to the playing sound

sound playLoopingSound(soundentry)
Plays the specified sound as a looping sound
Returns: A handle to the playing sound or invalid handle if playback failed

3Dsound play3DSound(soundentry[, vector source[, vector listener]])
Plays the specified sound entry handle. Source if by default 0, 0, 0 and listener is by default the current viewposition
Returns: A handle to the playing sound

boolean playGameSound(Sound index, [Panning (-1.0 left to 1.0 right), Volume %, Priority 0-3, Voice Message?])
Plays a sound from #Game Sounds in sounds.tbl. A priority of 0 indicates that the song must play; 1-3 will specify the maximum number of that sound that can be played
Returns: True if sound was played, false if not (Replaced with a sound instance object in the future)

boolean playInterfaceSound(Sound index)
Plays a sound from #Interface Sounds in sounds.tbl
Returns: True if sound was played, false if not

number playMusic(string Filename, [float volume = 1.0, bool looping = true])
Plays a music file using FS2Open's builtin music system. Volume should be in the 0.0 - 1.0 range, and is capped at 1.0. Files passed to this function are looped by default.
Returns: Audiohandle of the created audiostream, or -1 on failure

nil stopMusic(int audiohandle, [bool fade = false])
Stops a playing music file, provided audiohandle is valid
Returns: Nothing

===Base (ba)===
Base FreeSpace 2 functions

nil print(string Message)
Prints a string
Returns: Nothing

nil warning(string Message)
Displays a FreeSpace warning (debug build-only) message with the string provided
Returns: Nothing

nil error(string Message)
Displays a FreeSpace error message with the string provided
Returns: Nothing

orientation createOrientation([p/r1c1, b/r1c2, h/r1c3, r2c1, r2c2, r2c3, r3c1, r3c2, r3c3])
Given 0, 3, or 9 arguments, creates an orientation object with that orientation.
Returns: New orientation object, or null orientation on failure

vector createVector([x, y, z])
Creates a vector object
Returns: Vector object

number getFrametime([Do not adjust for time compression (Boolean)])
Gets how long this frame is calculated to take. Use it to for animations, physics, etc to make incremental changes.
Returns: Frame time (seconds)

state getCurrentGameState([Depth (number)])
Gets current FreeSpace state; if a depth is specified, the state at that depth is returned. (IE at the in-game options game, a depth of 1 would give you the game state, while the function defaults to 0, which would be the options screen.
Returns: Current game state at specified depth, or invalid handle if no game state is active yet

string getCurrentMPStatus(NIL)
Gets this computers current MP status
Returns: Current MP status

string setControlMode(NIL or enumeration LE_*_CONTROL)
Sets the current control mode for the game.
Returns: Current control mode

string setButtonControlMode(NIL or enumeration LE_*_BUTTON_CONTROL)
Sets the current control mode for the game.
Returns: Current control mode

control info getControlInfo()
Gets the control info handle.
Returns: control info handle

boolean postGameEvent(gameevent Event)
Sets current game event. Note that you can crash FreeSpace 2 by posting an event at an improper time, so test extensively if you use it.
Returns: True if event was posted, false if passed event was invalid

gameevent GameEvents[] number Index/string Name
Array of game events
Returns: Game event, or invalid gameevent handle if index is invalid

number #
Number of events
Returns: Number of events

gamestate GameStates[] number Index/string Name
Array of game states
Returns: Game state, or invalid gamestate handle if index is invalid

number #
Number of states
Returns: Number of states

===CFile (cf)===
CFile FS2 filesystem access

boolean deleteFile(string Filename, string Path)
Deletes given file. Path must be specified. Use a slash for the root directory.
Returns: True if deleted, false

boolean fileExists(string Filename, [string Path = "", boolean CheckVPs = false])
Checks if a file exists. Use a blank string for path for any directory, or a slash for the root directory.
Returns: True if file exists, false or nil otherwise

file openFile(string Filename, [string Mode="r", string Path = ""])
Opens a file. 'Mode' uses standard C fopen arguments. Use a blank string for path for any directory, or a slash for the root directory.Be EXTREMELY CAREFUL when using this function, as you may PERMANENTLY delete any file by accident
Returns: File handle, or invalid file handle if the specified file couldn't be opened

file openTempFile()
Opens a temp file that is automatically deleted when closed
Returns: File handle, or invalid file handle if tempfile couldn't be created

boolean renameFile(string CurrentFilename, string NewFilename, string Path)
Renames given file. Path must be specified. Use a slash for the root directory.
Returns: True if file was renamed, otherwise false

===Controls (io)===
Controls library

number getMouseX()
Gets Mouse X pos
Returns: Mouse x position, or 0 if mouse is not initialized yet

number getMouseY()
Gets Mouse Y pos
Returns: Mouse y position, or 0 if mouse is not initialized yet

boolean isMouseButtonDown({MOUSE_*_BUTTON enumeration}, [..., ...])
Returns whether the specified mouse buttons are up or down
Returns: Whether specified mouse buttons are down, or false if mouse is not initialized yet

nil setCursorImage(Image filename, [LOCK or UNLOCK])
Sets mouse cursor image, and allows you to lock/unlock the image. (A locked cursor may only be changed with the unlock parameter)
Returns: Nothing

nil setCursorHidden(True to hide mouse, false to show it)
Shows or hides mouse cursor
Returns: Nothing

boolean forceMousePosition(number, number (coordinates))
function to force mouse position
Returns: if the operation succeeded or not

boolean MouseControlStatus = boolean
Gets and sets the retail mouse control status
Value: if the retail mouse is on or off

boolean updateTrackIR()
Updates Tracking Data. Call before using get functions
Returns: Checks if trackir is available and updates variables, returns true if successful, otherwise false

number getTrackIRPitch()
Gets pitch axis from last update
Returns: Pitch value -1 to 1, or 0 on failure

number getTrackIRYaw()
Gets yaw axis from last update
Returns: Yaw value -1 to 1, or 0 on failure

number getTrackIRRoll()
Gets roll axis from last update
Returns: Roll value -1 to 1, or 0 on failure

number getTrackIRX()
Gets x position from last update
Returns: X value -1 to 1, or 0 on failure

number getTrackIRY()
Gets y position from last update
Returns: Y value -1 to 1, or 0 on failure

number getTrackIRZ()
Gets z position from last update
Returns: Z value -1 to 1, or 0 on failure

===HUD (hu)===
HUD library

boolean HUDDrawn = boolean
Current HUD draw status
Value: If the HUD is drawn or not

boolean setHUDGaugeColor(number (index number of the gauge), [number red, number green, number blue, number alpha])
Color used to draw the gauge
Returns: If the operation was successful

number, number, number, number getHUDGaugeColor(number (index number of the gauge))
Color used to draw the gauge
Returns: Red, green, blue, and alpha of the gauge

HudGauge getHUDGaugeHandle(string Name)
Returns a handle to a specified HUD gauge
Returns: HUD Gauge handle, or nil if invalid

===Graphics (gr)===
Graphics Library

camera Cameras[] number Index/string Name
Gets camera
Returns: Ship handle, or invalid ship handle if index was invalid

number #
Gets number of cameras
Returns: Number of cameras

font Fonts[] number Index/string Filename
Array of loaded fonts
Returns: Font handle, or invalid font handle if index is invalid

number #
Number of loaded fonts
Returns: Number of loaded fonts

font CurrentFont = font
Current font
Value: (null)

enumeration CurrentOpacityType = enumeration
Current alpha blending type; uses ALPHABLEND_* enumerations
Value: (null)

texture CurrentRenderTarget = texture
Current rendering target
Value: Current rendering target, or invalid texture handle if screen is render target

nil clearScreen([number Red, number green, number blue, number alpha])
Clears the screen to black, or the color specified.
Returns: Nothing

camera createCamera(string Name, [wvector Position, orientation Orientation])
Creates a new camera using the specified position and orientation (World)
Returns: Camera handle, or invalid camera handle if camera couldn't be created

number getScreenWidth()
Gets screen width
Returns: Width in pixels, or 0 if graphics are not initialized yet

number getScreenHeight()
Gets screen height
Returns: Height in pixels, or 0 if graphics are not initialized yet

vector getVectorFromCoords([number X=center, number Y=center, number Depth, boolean normalize = false])
Returns a vector through screen coordinates x and y. If depth is specified, vector is extended to Depth units into spaceIf normalize is true, vector will be normalized.
Returns: Vector, or zero vector on failure

boolean setTarget([texture Texture])
If texture is specified, sets current rendering surface to a texture.Otherwise, sets rendering surface back to screen.
Returns: True if successful, false otherwise

boolean setCamera([camera handle Camera])
Sets current camera, or resets camera if none specified
Returns: true if successful, false or nil otherwise

nil setColor(number Red, number Green, number Blue, [number Alpha])
Sets 2D drawing color; each color number should be from 0 (darkest) to 255 (brightest)
Returns: Nothing

nil drawCircle(number Radius, number X, number Y)
Draws a circle
Returns: Nothing

nil drawCurve(number X, number Y, number Radius)
Draws a curve
Returns: Nothing

nil drawGradientLine(number X1, number Y1, number X2, number Y2)
Draws a line from (x1,y1) to (x2,y2) with the CurrentColor that steadily fades out
Returns: Nothing

nil drawLine(number X1, number Y1, number X2, number Y2)
Draws a line from (x1,y1) to (x2,y2) with CurrentColor
Returns: Nothing

nil drawPixel(number X, number Y)
Sets pixel to CurrentColor
Returns: Nothing

nil drawPolygon(texture Texture, [vector Position={0,0,0}, orientation Orientation=null, number Width=1.0, number Height=1.0])
Draws a polygon
Returns: Nothing

nil drawRectangle(number X1, number Y1, number X2, number Y2, [boolean Filled=true])
Draws a rectangle with CurrentColor
Returns: Nothing

boolean drawSphere([number Radius = 1.0, vector Position])
Draws a sphere with radius Radius at world vector Position
Returns: True if successful, false or nil otherwise

int drawModel(model, position, orientation)
Draws the given model with the specified position and orientation - Use with extreme care, may not work properly in all scripting hooks.
Returns: Zero if successful, otherwise an integer error code

int drawModelOOR(model Model, vector Position, matrix Orientation, integer Flags)
Draws the given model with the specified position and orientation - Use with extreme care, designer to operate properly only in On Object Render hook.
Returns: Zero if successful, otherwise an integer error code

number,number,number,number drawTargetingBrackets(object Object, [boolean draw=true, int padding=5])
Gets the edge positions of targeting brackets for the specified object. The brackets will only be drawn if draw is true or the default value of draw is used. Brackets are drawn with the current color. The brackets will have a padding (distance from the actual bounding box); the default value (used elsewhere in FS2) is 5.
Returns: Left, top, right, and bottom positions of the brackets, or nil if invalid

number drawString(string Message, [number X1, number Y1, number X2, number Y2])
Draws a string. Use x1/y1 to control position, x2/y2 to limit textbox size.Text will automatically move onto new lines, if x2/y2 is specified.Additionally, calling drawString with only a string argument will automaticallydraw that string below the previously drawn string (or 0,0 if no stringshave been drawn yet
Returns: Number of lines drawn, or 0 on failure

number getStringWidth(string String)
Gets string width
Returns: String width, or 0 on failure

texture createTexture([number Width=512, number Height=512, enumeration Type=TEXTURE_DYNAMIC])
Creates a texture for rendering to.Types are TEXTURE_STATIC - for infrequent rendering - and TEXTURE_DYNAMIC - for frequent rendering.
Returns: New texture handle, or invalid texture handle if texture couldn't be created

texture loadTexture(string Filename, [boolean LoadIfAnimation, boolean NoDropFrames])
Gets a handle to a texture. If second argument is set to true, animations will also be loaded.If third argument is set to true, every other animation frame will not be loaded if system has less than 48 MB memory.
IMPORTANT: Textures will not be unload themselves unless you explicitly tell them to do so.When you are done with a texture, call the Unload() function to free up memory.
Returns: Texture handle, or invalid texture handle if texture couldn't be loaded

boolean drawImage(string Filename/texture Texture, [number X1=0, Y1=0, number X2, number Y2, number UVX1 = 0.0, number UVY1 = 0.0, number UVX2=1.0, number UVY2=1.0, number alpha=1.0])
Draws an image or texture. Any image extension passed will be ignored.The UV variables specify the UV value for each corner of the image. In UV coordinates, (0,0) is the top left of the image; (1,1) is the lower right.
Returns: Whether image was drawn

boolean drawMonochromeImage(string Filename/texture Texture, number X1, number Y1, [number X2, number Y2, number alpha=1.0])
Draws a monochrome image using the current color
Returns: Whether image was drawn

number getImageWidth(string Filename)
Gets image width
Returns: Image width, or 0 if filename is invalid

number getImageHeight(Image name)
Gets image height
Returns: Image height, or 0 if filename is invalid

nil flashScreen(number Red, number Green, number Blue)
Flashes the screen
Returns: Nothing

model loadModel(string Filename)
Loads the model - will not setup subsystem data, DO NOT USE FOR LOADING SHIP MODELS
Returns: Handle to a model

boolean hasViewmode(enumeration)
Specifies if the current viemode has the specified flag, see VM_* enumeration
Returns: true if flag is present, false otherwise

===HookVariables (hv)===
Hook variables repository

string Globals[] number Index
Array of current HookVariable names
Returns: Hookvariable name, or empty string if invalid index specified

number #
Number of HookVariables
Returns: Number of HookVariables

===Mission (mn)===
Mission library

object getObjectFromSignature(number Signature)
Gets a handle of an object from its signature
Returns: Handle of object with signaure, invalid handle if signature is not in use

boolean evaluateSEXP(string)
Runs the defined SEXP script
Returns: if the operation was successful

boolean runSEXP(string)
Runs the defined SEXP script
Returns: if the operation was successful

asteroid Asteroids[] number Index
Gets asteroid
Returns: Asteroid handle, or invalid handle if invalid index specified

number #
Number of asteroids in mission. Note that the value returned is only good until an asteroid is destroyed, and so cannot be relied on for more than one frame.
Returns: Number of asteroids in the mission, or 0 if asteroids are not enabled

debris Debris[] number Index
Array of debris in the current mission
Returns: Debris handle, or invalid debris handle if index wasn't valid

number #
Number of debris pieces in the mission. Note that the value returned is only good until a piece of debris is destroyed, and so cannot be relied on for more than one frame.
Returns: Current number of debris particles

ship EscortShips[] number Index
Gets escort ship at specified index on escort list
Returns: Specified ship, or invalid ship handle if invalid index

number #
Current number of escort ships
Returns: Current number of escort ships

event Events[] number Index/string Name
Indexes events list
Returns: Event handle, or invalid event handle if index was invalid

number #
Number of events in mission
Returns: Number of events in mission

sexpvariable SEXPVariables[] number Index/string Name
Array of SEXP variables. Note that you can set a sexp variable using the array, eg 'SEXPVariables[1] = "newvalue"'
Returns: Handle to SEXP variable, or invalid sexpvariable handle if index was invalid

number #
Current number of SEXP variables
Returns: Counts number of loaded SEXP Variables. May be slow.

ship Ships[] number Index/string Name
Gets ship
Returns: Ship handle, or invalid ship handle if index was invalid

number #
Number of ships in the mission. This function is somewhat slow, and should be set to a variable for use in looping situations. Note that the value returned is only good until a ship is destroyed, and so cannot be relied on for more than one frame.
Returns: Number of ships in the mission, or 0 if ships haven't been initialized yet

waypoint Waypoints[] number Index
Array of waypoints in the current mission
Returns: Waypoint handle, or invalid waypoint handle if index was invalid

number #
Gets number of waypoints in mission. Note that this is only accurate for one frame.
Returns: Number of waypoints in the mission

waypointlist WaypointLists[] number Index/string WaypointListName
Array of waypoint lists
Returns: Gets waypointlist handle

number #
Number of waypoint lists in mission. Note that this is only accurate for one frame.
Returns: Number of waypoint lists in the mission

weapon Weapons[] number Index
Gets handle to a weapon object in the mission.
Returns: Weapon handle, or invalid weapon handle if index is invalid

number #
Number of weapon objects in mission. Note that this is only accurate for one frame.
Returns: Number of weapon objects in mission

beam Beams[] number Index
Gets handle to a beam object in the mission.
Returns: Beam handle, or invalid beam handle if index is invalid

number #
Number of beam objects in mission. Note that this is only accurate for one frame.
Returns: Number of beam objects in mission

wing Wings[] number Index/string WingName
Wings in the mission
Returns: Wing handle, or invalid wing handle if index or name was invalid

number #
Number of wings in mission
Returns: Number of wings in mission

ship createShip([string Name, shipclass Class=Shipclass[1], orientation Orientation=null, vector Position={0,0,0}])
Creates a ship and returns a handle to it using the specified name, class, world orientation, and world position
Returns: Ship handle, or invalid ship handle if ship couldn't be created

waypoint createWaypoint([vector Position, waypointlist List])
Creates a waypoint
Returns: Waypoint handle, or invalid waypoint handle if waypoint couldn't be created

weapon createWeapon([weaponclass Class=WeaponClass[1], orientation Orientation=null, world vector Position={0,0,0}, object Parent = nil, number Group = -1)
Creates a weapon and returns a handle to it. 'Group' is used for lighting grouping purposes; for example, quad lasers would only need to act as one light source.
Returns: Weapon handle, or invalid weapon handle if weapon couldn't be created.

string getMissionFilename()
Gets mission filename
Returns: Mission filename, or empty string if game is not in a mission

boolean startMission([Filename or MISSION_* enumeration, Briefing = true])
Starts the defined mission
Returns: True, or false if the function fails

number getMissionTime()
Game time in seconds since the mission was started; is affected by time compression
Returns: Mission time (seconds), or 0 if game is not in a mission

boolean loadMission(Mission name)
Loads a mission
Returns: True if mission was loaded, otherwise false

nil unloadMission()
Stops the current mission and unloads it
Returns: Nothing

nil simulateFrame()
Simulates mission frame
Returns: Nothing

nil renderFrame()
Renders mission frame, but does not move anything
Returns: Nothing

===BitOps (bit)===
Bitwise Operations library

number AND(number, number)
Values for which bitwise boolean AND operation is performed
Returns: Result of the AND operation

number OR(number, number)
Values for which bitwise boolean OR operation is performed
Returns: Result of the OR operation

number XOR(number, number)
Values for which bitwise boolean XOR operation is performed
Returns: Result of the XOR operation

number toggleBit(number, number (bit))
Toggles the value of the set bit in the given number for 32 bit integer
Returns: Result of the operation

boolean checkBit(number, number (bit))
Checks the value of the set bit in the given number for 32 bit integer
Returns: Was the bit true of false

number addBit(number, number (bit))
Performs inclusive or (OR) operation on the set bit of the value
Returns: Result of the operation

===Tables (tb)===
Tables library

ship ShipClasses[] number Index/string Name
Array of ship classes
Returns: Ship handle, or invalid ship handle if index is invalid

number #
Number of ship classes
Returns: Number of ship classes, or 0 if ship classes haven't been loaded yet

weapon WeaponClasses[] number Index/string WeaponName
Array of weapon classes
Returns: Weapon class handle, or invalid weaponclass handle if index is invalid

number #
Number of weapon classes
Returns: Number of weapon classes, or 0 if weapon classes haven't been loaded yet

===Testing (ts)===
Experimental or testing stuff

nil avdTest()
Test the AVD Physics code
Returns: Nothing

particle createParticle(vector Position, vector Velocity, number Lifetime, number Radius, enumeration Type, [number Tracer length=-1, boolean Reverse=false, texture Texture=Nil, object Attached Object=Nil])
Creates a particle. Use PARTICLE_* enumerations for type.Reverse reverse animation, if one is specifiedAttached object specifies object that Position will be (and always be) relative to.
Returns: Handle to the created particle

string getStack()
Generates an ADE stackdump
Returns: Current Lua stack

boolean isCurrentPlayerMulti()
Returns whether current player is a multiplayer pilot or not.
Returns: Whether current player is a multiplayer pilot or not

boolean isPXOEnabled()
Returns whether PXO is currently enabled in the configuration.
Returns: Whether PXO is enabled or not

==Enumerations==
ALPHABLEND_FILTER
ALPHABLEND_NONE
CFILE_TYPE_NORMAL
CFILE_TYPE_MEMORY_MAPPED
MOUSE_LEFT_BUTTON
MOUSE_RIGHT_BUTTON
MOUSE_MIDDLE_BUTTON
ORDER_ATTACK
ORDER_ATTACK_ANY
ORDER_DEPART
ORDER_DISABLE
ORDER_DISARM
ORDER_DOCK
ORDER_EVADE
ORDER_FLY_TO
ORDER_FORM_ON_WING
ORDER_GUARD
ORDER_IGNORE_SHIP
ORDER_KEEP_SAFE_DISTANCE
ORDER_PLAY_DEAD
ORDER_REARM
ORDER_STAY_NEAR
ORDER_STAY_STILL
ORDER_UNDOCK
ORDER_WAYPOINTS
ORDER_WAYPOINTS_ONCE
PARTICLE_DEBUG
PARTICLE_BITMAP
PARTICLE_FIRE
PARTICLE_SMOKE
PARTICLE_SMOKE2
PARTICLE_PERSISTENT_BITMAP
SEXPVAR_CAMPAIGN_PERSISTENT
SEXPVAR_NOT_PERSISTENT
SEXPVAR_PLAYER_PERSISTENT
SEXPVAR_TYPE_NUMBER
SEXPVAR_TYPE_STRING
TEXTURE_STATIC
TEXTURE_DYNAMIC
LOCK
UNLOCK
NONE
SHIELD_FRONT
SHIELD_LEFT
SHIELD_RIGHT
SHIELD_BACK
MISSION_REPEAT
NORMAL_CONTROLS
LUA_STEERING_CONTROLS
LUA_FULL_CONTROLS
NORMAL_BUTTON_CONTROLS
LUA_ADDITIVE_BUTTON_CONTROL
LUA_OVERRIDE_BUTTON_CONTROL
VM_INTERNAL
VM_EXTERNAL
VM_TRACK
VM_DEAD_VIEW
VM_CHASE
VM_OTHER_SHIP
VM_EXTERNAL_CAMERA_LOCKED
VM_WARP_CHASE
VM_PADLOCK_UP
VM_PADLOCK_REAR
VM_PADLOCK_LEFT
VM_PADLOCK_RIGHT
VM_WARPIN_ANCHOR
VM_TOPDOWN
VM_FREECAMERA

Scripting functions

2012-07-15T12:07:45Z

Aginor: /* gamestate */

This page explains all the functions mentioned in the scripting.html file, including their syntax, remarks on their use and common errors modders may encounter when they use them.

----

Script Output - FSO v3.6.13 (FS2_Open Scripting)

==Conditional Hooks==

===Conditions===
*State
*Campaign
*Mission
*Object Type
*Ship
*Ship class
*Ship type
*Weapon class
*KeyPress
*Version
*Application
**''Usually: $Application: FS2_Open''

===Actions===
*On Game Init
*On Splash Screen
*On State Start
*On Frame
*On Key Pressed
*On Key Released
*On Mouse Moved
*On Mouse Pressed
*On Mouse Released
*On State End
*On Mission Start
*On HUD Draw
*On Ship Collision
*On Weapon Collision
*On Debris Collision
*On Asteroid Collision
*On Object Render
*On Warp In
*On Warp Out
*On Death
*On Mission End
*On Weapon Delete
*On Weapon Equipped
*On Weapon Fired
*On Weapon Selected
*On Weapon Deselected
*On Gameplay Start
*On Turret Fired
*On Primary Fire
*On Secondary Fire

==Types==
===vector===
:'''Vector object'''
 
:''number [] x,y,z or 1-3''
::*Vector component
::*'''Returns:''' Value at index, or 0 if vector handle is invalid
 
:''[[Scripting_functions#vector|vector]] + number/vector''
::*Adds vector by another vector, or adds all axes by value
::*'''Returns:''' Final vector, or null vector if error occurs
 
:''[[Scripting_functions#vector|vector]] - number/vector''
::*Subtracts vector from another vector, or subtracts all axes by value
::*'''Returns:''' Final vector, or null vector if error occurs
 
:''[[Scripting_functions#vector|vector]] * number/vector''
::*Scales vector object (Multiplies all axes by number), or multiplies each axes by the other vector's axes.
::*''' Returns:''' Final vector, or null vector if error occurs
 
:''[[Scripting_functions#vector|vector]] / number/vector''
::*Scales vector object (Divide all axes by number), or divides each axes by the dividing vector's axes.
::*'''Returns:''' Final vector, or null vector if error occurs
 
:''string (string)''
::*Converts a vector to string with format "(x,y,z)"
::*'''Returns:''' Vector as string, or empty string if handle is invalid
 
:''[[Scripting_functions#orientation|orientation]]'' '''getOrientation()'''
::*Returns orientation object representing the direction of the vector. Does not require vector to be normalized.
::*'''Returns:''' Orientation object, or null orientation object if handle is invalid
 
:''number'' '''getMagnitude()'''
::*Returns the magnitude of a vector (Total regardless of direction)
::*'''Returns:''' Magnitude of vector, or 0 if handle is invalid
 
:''number'' '''getDistance('''''Vector''''')'''
::*Distance
::*'''Returns:''' Returns distance from another vector
 
:''number'' '''getDotProduct('''''vector OtherVector''''')'''
::*Returns dot product of vector object with vector argument
::*'''Returns:''' Dot product, or 0 if a handle is invalid
 
:''[[Scripting_functions#vector|vector]]'' '''getCrossProduct('''''vector OtherVector''''')'''
::*Returns cross product of vector object with vector argument
::*'''Returns:''' Cross product, or null vector if a handle is invalid
 
:''number,number'' '''getScreenCoords()'''
::*Gets screen cordinates of a world vector
::*'''Returns:''' X (number), Y (number), or false if off-screen
 
:''vector'' '''getNormalized()'''
::*Returns a normalized version of the vector
::*'''Returns:''' Normalized Vector, or NIL if invalid
 
===orientation===
Orientation matrix object

number [] p,b,h or 1-9
Orientation component - pitch, bank, heading, or index into 3x3 matrix (1-9)
Returns: Number at the specified index, or 0 if index is invalid.

orientation * orientation
Multiplies two matrix objects)
Returns: matrix, or empty matrix if unsuccessful

string (string)
Converts a matrix to a string with format "[r1c1 r2c1 r3c1 | r1c2 r2c2 r3c2| r1c3 r2c3 r3c3]"
Returns: Formatted string or "

orientation getInterpolated(orientation Final, number Factor)
Returns orientation that has been interpolated to Final by Factor (0.0-1.0)
Returns: Interpolated orientation, or null orientation on failure

orientation getTranspose()
Returns a transpose version of the specified orientation
Returns: Transpose matrix, or null orientation on failure

vector rotateVector(vector Input)
Returns rotated version of given vector
Returns: Rotated vector, or empty vector on error

vector unrotateVector(vector Input)
Returns unrotated version of given vector
Returns: Unrotated vector, or empty vector on error

===enumeration===
Enumeration object

enumeration = enumeration
Sets enumeration to specified value (if it is not a global
Returns: enumeration

string (string)
Returns enumeration name
Returns: Enumeration name, or "" if invalid

===event===
Mission event handle

string Name = string
Mission event name
Value: (null)

string DirectiveText = string
Directive text
Value: (null)

string DirectiveKeypressText = string
Raw directive keypress text, as seen in FRED.
Value: (null)

number Interval = number
Time for event to repeat (in seconds)
Value: Repeat time, or 0 if invalid handle

number ObjectCount = number
Number of objects left for event
Value: Repeat count, or 0 if invalid handle

number RepeatCount = number
Event repeat count
Value: Repeat count, or 0 if invalid handle

number Score = number
Event score
Value: Event score, or 0 if invalid handle

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===file===
File handle

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

nil close()
Instantly closes file and invalidates all file handles
Returns: Nothing

boolean flush()
Flushes file buffer to disk.
Returns: True for success, false on failure

string getPath()
Determines path of the given file
Returns: Path string of the file handle, or an empty string if it doesn't have one, or the handle is invalid

number or string, ... read(number or string, ...)
Reads part of or all of a file, depending on arguments passed. Based on basic Lua file:read function.Returns nil when the end of the file is reached.

* "*n" - Reads a number.
* "*a" - Reads the rest of the file and returns it as a string.
* "*l" - Reads a line. Skips the end of line markers.
* (number) - Reads given number of characters, then returns them as a string.

Returns: Requested data, or nil if the function fails

number seek([string Whence="cur", number Offset=0])
# Changes position of file, or gets location.Whence can be:"set" - File start.
# "cur" - Current position in file.
# "end" - File end.
Returns: new offset, or false or nil on failure

number write(string or number, ...)
Writes a series of Lua strings or numbers to the current file.
Returns: Number of items successfully written.

===font===
font handle

string (string)
Filename of font
Returns: Font filename, or an empty string if the handle is invalid

string Filename = string
Filename of font (including extension)
Value: (null)

number Height = number
Height of font (in pixels)
Value: Font height, or 0 if the handle is invalid

boolean isValid()
True if valid, false or nil if not
Returns: Detects whether handle is valid

===gameevent===
Game event

string (string)
Game event name
Returns: Game event name, or empty string if handle is invalid

string Name = string
Game event name
Value: Game event name, or empty string if handle is invalid

===gamestate===
:'''Game state'''
 
:''string (string)''
::*Game state name
::*'''Value:''' Game state name, or empty string if handle is invalid
 
:''string Name = string''
::*Game state name
::*'''Value:''' Game state name, or empty string if handle is invalid
 

===HudGauge===
:'''HUD Gauge handle'''
 
:''string Name = string''
::*Custom HUD Gauge name
::*'''Returns:''' Custom HUD Gauge name, or nil if handle is invalid
 
:''string Text = string''
::*Custom HUD Gauge text
::*'''Returns:''' Value: Custom HUD Gauge text, or nil if handle is invalid
 

===eyepoint===
Eyepoint handle

vector Normal = vector
Eyepoint normal
Value: Eyepoint normal, or null vector if handle is invalid

vector Position = vector
Eyepoint location (Local vector)
Value: Eyepoint location, or null vector if handle is invalid

boolean IsValid()
Detect whether this handle is valid
Returns: true if valid false otherwise

===model===
3D Model (POF) handle

modeltextures_h Textures = modeltextures_h
Model textures
Value: Model textures, or an invalid modeltextures handle if the model handle is invalid

thrusters Thrusters = thrusters
Model thrusters
Value: Thrusters of the model or invalid handle

eyepoints Eyepoints = eyepoints
Model eyepoints
Value: Array of eyepoints or invalid handle on error

vector BoundingBoxMax = vector
Model bounding box maximum
Value: Model bounding box, or an empty vector if the handle is invalid

vector BoundingBoxMin = vector
Model bounding box minimum
Value: Model bounding box, or an empty vector if the handle is invalid

string Filename = string
Model filename
Value: Model filename, or an empty string if the handle is invalid

number Mass = number
Model mass
Value: Model mass, or 0 if the model handle is invalid

orientation MomentOfInertia = orientation
Model moment of inertia
Value: Moment of Inertia matrix or identity matrix if invalid

number Radius = number
Model radius (Used for collision & culling detection)
Value: Model Radius or 0 if invalid

boolean isValid()
True if valid, false or nil if not
Returns: Detects whether handle is valid

===modeltextures_h===
Array of materials

number #
Number of textures on model
Returns: Number of model textures

texture [] texture
number Index/string TextureName
Returns: Model textures, or invalid modeltextures handle if model handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===eyepoints===
Array of model eye points

number #
Gets the number of eyepoints on this model
Returns: Number of eyepoints on this model or 0 on error

eyepoint [] eyepoint
Gets en eyepoint handle
Returns: eye handle or invalid handle on error

boolean isValid()
Detects whether handle is valid or not
Returns: true if valid false otherwise

===thrusters===
The thrusters of a model

number #
Number of thruster banks on the model
Returns: Number of thrusterbanks

thrusterbank [] number Index
Array of all thrusterbanks on this thruster
Returns: Handle to the thrusterbank or invalid handle if index is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===thrusterbank===
A model thrusterbank

number #
Number of thrusters on this thrusterbank
Returns: Number of thrusters on this bank or 0 if handle is invalid

glowpoint [] number Index
Array of glowpoint
Returns: Glowpoint, or invalid glowpoint handle on failure

boolean isValid()
Detectes if this handle is valid
Returns: true if this handle is valid, false otherwise

===glowpoint===
A model glowpoint

vector Position
The (local) vector to the position of the glowpoint

number Radius
The radius of the glowpoint

boolean isValid()
Returns wether this handle is valid or not
Returns: True if handle is valid, false otherwise

===order===
order handle

boolean remove()
Removes the given order from the ship's priority queue.
Returns: True if order was successfully removed, otherwise false or nil.

===shiporders===
Ship orders

number #
Number of textures on ship
Returns: Number of textures on ship, or 0 if handle is invalid

order [] number Index/string TextureFilename
Array of ship orders
Returns: Order, or invalid texture handle on failure

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===physics===
Physics handle

number AfterburnerAccelerationTime = number
Afterburner acceleration time
Value: Afterburner acceleration time, or 0 if handle is invalid

vector AfterburnerVelocityMax = vector
Afterburner max velocity (Local vector)
Value: Afterburner max velocity, or null vector if handle is invalid

number BankingConstant = number
Banking constant
Value: Banking constant, or 0 if handle is invalid

number ForwardAccelerationTime = number
Forward acceleration time
Value: Forward acceleration time, or 0 if handle is invalid

number ForwardDecelerationTime = number
Forward deceleration time
Value: Forward decleration time, or 0 if handle is invalid

number ForwardThrust = number
Forward thrust amount (0-1), used primarily for thruster graphics
Value: Forward thrust, or 0 if handle is invalid

number Mass = number
Object mass
Value: Object mass, or 0 if handle is invalid

vector RotationalVelocity = vector
Rotational velocity (Local vector)
Value: Rotational velocity, or null vector if handle is invalid

number RotationalVelocityDamping = number
Rotational damping, ie derivative of rotational speed
Value: Rotational damping, or 0 if handle is invalid

number RotationalVelocityDesired = lvector
Desired rotational velocity
Value: Desired rotational velocity, or 0 if handle is invalid

vector RotationalVelocityMax = vector
Maximum rotational velocity (Local vector)
Value: Maximum rotational velocity, or null vector if handle is invalid

number ShockwaveShakeAmplitude = number
How much shaking from shockwaves is applied to object
Value: Shockwave shake amplitude, or 0 if handle is invalid

number SideThrust = number
Side thrust amount (0-1), used primarily for thruster graphics
Value: Side thrust amount, or 0 if handle is invalid

number SlideAccelerationTime = number
Time to accelerate to maximum slide velocity
Value: Sliding acceleration time, or 0 if handle is invalid

number SlideDecelerationTime = number
Time to decelerate from maximum slide speed
Value: Sliding deceleration time, or 0 if handle is invalid

vector Velocity = vector
Object world velocity (World vector)
Value: Object velocity, or null vector if handle is invalid

vector VelocityDesired = vector
Desired velocity (World vector)
Value: Desired velocity, or null vector if handle is invalid

vector VelocityMax = vector
Object max local velocity (Local vector)
Value: Maximum velocity, or null vector if handle is invalid

number VerticalThrust = number
Vertical thrust amount (0-1), used primarily for thruster graphics
Value: Vertical thrust amount, or 0 if handle is invalid

boolean AfterburnerActive = boolean
Specifies if the afterburner is active or not
Value: true if afterburner is active false otherwise

boolean isValid()
True if valid, false or nil if not
Returns: Detects whether handle is valid

number getSpeed()
Gets total speed as of last frame
Returns: Total speed, or 0 if handle is invalid

number getForwardSpeed()
Gets total speed in the ship's 'forward' direction as of last frame
Returns: Total forward speed, or 0 if handle is invalid

boolean isAfterburnerActive()
True if Afterburners are on, false or nil if not
Returns: Detects whether afterburner is active

boolean isGliding()
True if glide mode is on, false or nil if not
Returns: Detects if ship is gliding

===sexpvariable===
SEXP Variable handle

enumeration Persistence = enumeration
SEXP Variable persistance, uses SEXPVAR_*_PERSISTENT enumerations
Value: SEXPVAR_*_PERSISTENT enumeration, or invalid numeration if handle is invalid

enumeration Type = enumeration
SEXP Variable type, uses SEXPVAR_TYPE_* enumerations
Value: SEXPVAR_TYPE_* enumeration, or invalid numeration if handle is invalid

string Value = number/string
SEXP variable value
Value: SEXP variable contents, or nil if the variable is of an invalid type or the handle is invalid

string (string)
Returns SEXP name
Returns: SEXP name, or empty string if handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

boolean delete()
Deletes a SEXP Variable
Returns: True if successful, false if the handle is invalid

===shields===
Shields handle

number [] enumeration/number
Gets or sets shield quadrant strength. Use "SHIELD_*" enumeration or 1-4 for a specific quadrant, or NONE for the entire shield
Returns: Quadrant/shield strength, or 0 if handle is invalid

number CombinedLeft = number
Total shield hitpoints left (for all quadrants combined)
Value: Combined shield strength, or 0 if handle is invalid

number CombinedMax = number
Maximum shield hitpoints (for all quadrants combined)
Value: Combined maximum shield strength, or 0 if handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===shiptype===
Ship type handle

string Name = string
Ship type name
Value: Ship type name, or empty string if handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===species===
Species handle

string Name = string
Species name
Value: Species name, or empty string if handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===team===
Team handle

boolean == team, team
Checks whether two teams are the same team
Returns: true if equal

string Name = string
Team name
Value: Team name, or empty string if handle is invalid

number, number, number getColor()
Gets the IFF color of the specified Team
Returns: rgb color for the specified team or nil if invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===texture===
Texture handle

nil __gc
Auto-deletes texture
Returns: Nothing

boolean == texture, texture
Checks if two texture handles refer to the same texture
Returns: True if textures are equal

texture [] number
Returns texture handle to specified frame number in current texture's animation.This means that [1] will always return the first frame in an animation, no matter what frame an animation is.You cannot change a texture animation frame.
Returns: Texture handle, or invalid texture handle if index is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

nil unload()
Unloads a texture from memory
Returns: Nothing

string getFilename()
Returns filename for texture
Returns: Filename, or empty string if handle is invalid

number getWidth()
Gets texture width
Returns: Texture width, or 0 if handle is invalid

number getHeight()
Gets texture height
Returns: Texture height, or 0 if handle is invalid

number getFPS()
Gets frames-per-second of texture
Returns: Texture FPS, or 0 if handle is invalid

number getFramesLeft()
Gets number of frames left, from handle's position in animation
Returns: Frames left, or 0 if handle is invalid

===material===
Texture map, including diffuse, glow, and specular textures

texture BaseMap = texture
Base texture
Value: Base texture, or invalid texture handle if material handle is invalid

texture GlowMap = texture
Glow texture
Value: Glow texture, or invalid texture handle if material handle is invalid

texture SpecularMap = texture
Specular texture
Value: Texture handle, or invalid texture handle if material handle is invalid

===weaponclass===
Weapon class handle

string (string)
Weapon class name
Returns: Weapon class name, or an empty string if handle is invalid

string Name = string
Weapon class name
Value: Weapon class name, or empty string if handle is invalid

string Title = string
Weapon class title
Value: Weapon class title, or empty string if handle is invalid

string Description = string
Weapon class description string
Value: Description string, or empty string if handle is invalid

string TechTitle = string
Weapon class tech title
Value: Tech title, or empty string if handle is invalid

string TechAnimationFilename = string
Weapon class animation filename
Value: Filename, or empty string if handle is invalid

string TechDescription = string
Weapon class tech description string
Value: Description string, or empty string if handle is invalid

model Model = model
Model
Value: Weapon class model, or invalid model handle if weaponclass handle is invalid

number ArmorFactor = number
Amount of weapon damage applied to ship hull (0-1.0)
Value: Armor factor, or empty string if handle is invalid

number Damage = number
Amount of damage that weapon deals
Value: Damage amount, or 0 if handle is invalid

number FireWait = number
Weapon fire wait (cooldown time) in seconds
Value: Fire wait time, or 0 if handle is invalid

number FreeFlightTime = number
The time the weapon will fly before turing onto its target
Value: Free flight time or emty string if invalid

number LifeMax = number
Life of weapon in seconds
Value: Life of weapon, or 0 if handle is invalid

number Range = number
Range of weapon in meters
Value: Weapon Range, or 0 if handle is invalid

number Mass = number
Weapon mass
Value: Weapon mass, or 0 if handle is invalid

number ShieldFactor = number
Amount of weapon damage applied to ship shields (0-1.0)
Value: Shield damage factor, or 0 if handle is invalid

number SubsystemFactor = number
Amount of weapon damage applied to ship subsystems (0-1.0)
Value: Subsystem damage factor, or 0 if handle is invalid

number TargetLOD = number
LOD used for weapon model in the targeting computer
Value: LOD number, or 0 if handle is invalid

number Speed = number
Weapon max speed, aka $Velocity in weapons.tbl
Value: Weapon speed, or 0 if handle is invalid

boolean Bomb = boolean
Is weapon class flagged as bomb
Value: New flag

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

number getWeaponClassIndex()
Gets the index value of the weapon class
Returns: index value of the weapon class

boolean isLaser()
Return true if the weapon is a laser (this includes balistic primaries)
Returns: true if the weapon is a laser, false otherwise

boolean isMissile()
Return true if the weapon is a missile
Returns: true if the weapon is a missile, false otherwise

boolean isBeam()
Return true if the weapon is a beam
Returns: true if the weapon is a beam, false otherwise

===collision info===
Information about a collision

nil __gc
Removes the allocated reference of this handle
Returns: Nothing

model Model = model
The model this collision info is about
Value: The model

number getCollisionDistance()
The distance to the closest collision point
Returns: distance or -1 on error

vector getCollisionPoint([boolean local])
The collision point of this information (local to the object if boolean is set to true)
Returns: The collision point or nil of none

vector getCollisionNormal([boolean local])
The collision normal of this information (local to object if boolean is set to true)
Returns: The collision normal or nil of none

boolean isValid()
Detects if this handle is valid
Returns: true if valid false otherwise

===object===
Object handle

boolean == object, object
Checks whether two object handles are for the same object
Returns: True if equal, false if not or a handle is invalid

string (string)
Returns name of object (if any)
Returns: Object name, or empty string if handle is invalid

object Parent = object
Parent of the object. Value may also be a deriviative of the 'object' class, such as 'ship'.
Value: Parent handle, or invalid handle if object is invalid

vector Position = vector
Object world position (World vector)
Value: World position, or null vector if handle is invalid

vector LastPosition = vector
Object world position as of last frame (World vector)
Value: World position, or null vector if handle is invalid

orientation Orientation = orientation
Object world orientation (World orientation)
Value: Orientation, or null orientation if handle is invalid

orientation LastOrientation = orientation
Object world orientation as of last frame (World orientation)
Value: Orientation, or null orientation if handle is invalid

physics Physics = physics
Physics data used to move ship between frames
Value: Physics data, or invalid physics handle if object handle is invalid

number HitpointsLeft = number
Hitpoints an object has left
Value: Hitpoints left, or 0 if handle is invalid

shields Shields = shields
Shields
Value: Shields handle, or invalid shields handle if object handle is invalid

number getSignature()
Gets the object's unique signature
Returns: Returns the objects unique numeric signature, or -1 if invalid. useful for creating a metadata sytem

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

string getBreedName()
Gets object type
Returns: Object type name, or empty string if handle is invalid

number CollisionGroups = number
Collision group data
Value: Current collision group signature. NOTE: This is a bitfield, NOT a normal number.

vector getfvec([boolean normalize])
Returns the objects' current fvec.
Returns: Objects' forward vector, or nil if invalid. If called with a true argument, vector will be normalized.

vector getuvec([boolean normalize])
Returns the objects' current uvec.
Returns: Objects' up vector, or nil if invalid. If called with a true argument, vector will be normalized.

vector getrvec([boolean normalize])
Returns the objects' current rvec.
Returns: Objects' rvec, or nil if invalid. If called with a true argument, vector will be normalized.

vector, collision info checkRayCollision(vector Start Point, vector End Point, [boolean Local])
Checks the collisions between the polygons of the current object and a ray
Returns: World collision point (local if boolean is set to true) and the specific collsision info, nil if no collisions

===asteroid:object===
Asteroid handle

object Target = object
Asteroid target object; may be object derivative, such as ship.
Value: Target object, or invalid handle if asteroid handle is invalid

boolean kill([ship killer=nil, wvector hitpos=nil])
Kills the asteroid. Set "killer" to designate a specific ship as having been the killer, and "hitpos" to specify the world position of the hit location; if nil, the asteroid center is used.
Returns: True if successful, false or nil otherwise

===shipclass===
Ship class handle

string (string)
Ship class name
Returns: Ship class name, or an empty string if handle is invalid

string Name = string
Ship class name
Value: Ship class name, or an empty string if handle is invalid

string ShortName = string
Ship class short name
Value: Ship short name, or empty string if handle is invalid

string TypeString = string
Ship class type string
Value: Type string, or empty string if handle is invalid

string ManeuverabilityString = string
Ship class maneuverability string
Value: Maneuverability string, or empty string if handle is invalid

string ArmorString = string
Ship class armor string
Value: Armor string, or empty string if handle is invalid

string ManufacturerString = string
Ship class manufacturer
Value: Manufacturer, or empty string if handle is invalid

string Description = string
Ship class description
Value: Description, or empty string if handle is invalid

string TechDescription = string
Ship class tech description
Value: Tech description, or empty string if handle is invalid

number AfterburnerFuelMax = number
Afterburner fuel capacity
Value: Afterburner capacity, or 0 if handle is invalid

number CountermeasuresMax = number
Maximum number of countermeasures the ship can carry
Value: Countermeasure capacity, or 0 if handle is invalid

model Model = model
Model
Value: Ship class model, or invalid model handle if shipclass handle is invalid

model CockpitModel = model
Model used for first-person cockpit
Value: Cockpit model

number HitpointsMax = number
Ship class hitpoints
Value: Hitpoints, or 0 if handle is invalid

species Species = Species
Ship class species
Value: Ship class species, or invalid species handle if shipclass handle is invalid

shiptype Type = shiptype
Ship class type
Value: Ship type, or invalid handle if shipclass handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

boolean isInTechroom()
Gets whether or not the ship class is available in the techroom
Returns: Whether ship has been revealed in the techroom, false if handle is invalid

boolean renderTechModel(X1, Y1, X2, Y2, [Rotation %, Pitch %, Bank %, Zoom multiplier])
Draws ship model as if in techroom
Returns: Whether ship was rendered

boolean renderTechModel2(X1, Y1, X2, Y2, orientation Orientation=null, [Zoom multiplier])
Draws ship model as if in techroom
Returns: Whether ship was rendered

boolean isModelLoaded([boolean Load = false])
Checks if the model used for this shipclass is loaded or not and optionally loads the model, which might be a slow operation.
Returns: If the model is loaded or not

number getShipClassIndex()
Gets the index valus of the ship class
Returns: index value of the ship class

===debris:object===
Debris handle

boolean IsHull = boolean
Whether or not debris is a piece of hull
Value: Whether debris is a hull fragment, or false if handle is invalid

shipclass OriginClass = shipclass
The shipclass of the ship this debris originates from
Value: The shipclass of the ship that created this debris

number getDebrisRadius()
The radius of this debris piece
Returns: The radius of this debris piece or -1 if invalid

boolean isValid()
Return if this debris handle is valid
Returns: true if valid false otherwise

===waypoint:object===
waypoint handle

===waypointlist===
waypointlist handle

waypoint [] number Index
Array of waypoints that are part of the waypoint list
Returns: Waypoint, or invalid handle if the index or waypointlist handle is invalid

number #
Number of waypoints in the list. Note that the value returned cannot be relied on for more than one frame.
Returns: Number of waypoints in the list, or 0 if handle is invalid

string Name = string
Name of WaypointList
Value: Waypointlist name, or empty string if handle is invalid

===weaponbank===
Ship/subystem weapons bank handle

weaponclass WeaponClass = weaponclass
Class of weapon mounted in the bank
Value: Weapon class, or an invalid weaponclass handle if bank handle is invalid

number AmmoLeft = number
Ammo left for the current bank
Value: Ammo left, or 0 if handle is invalid

number AmmoMax = number
Maximum ammo for the current bank
Value: Ammo capacity, or 0 if handle is invalid

boolean Armed = boolean
Weapon armed status. Does not take linking into account.
Value: True if armed, false if unarmed or handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===weaponbanktype===
Ship/subsystem weapons bank type handle

weaponbank [] number Index
Array of weapon banks
Returns: Weapon bank, or invalid handle on failure

boolean Linked = boolean
Whether bank is in linked or unlinked fire mode (Primary-only)
Value: Link status, or false if handle is invalid

boolean DualFire = boolean
Whether bank is in dual fire mode (Secondary-only)
Value: Dual fire status, or false if handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

number #
Number of weapons in the mounted bank
Returns: Number of bank weapons, or 0 if handle is invalid

===subsystem===
Ship subsystem handle

string (string)
Returns name of subsystem
Returns: Subsystem name, or empty string if handle is invalid

string ArmorClass = string
Current Armor class
Value: Armor class name, or empty string if none is set

number AWACSIntensity = number
Subsystem AWACS intensity
Value: AWACS intensity, or 0 if handle is invalid

number AWACSRadius = number
Subsystem AWACS radius
Value: AWACS radius, or 0 if handle is invalid

orientation Orientation = orientation
Orientation of subobject or turret base
Value: Subsystem orientation, or null orientation if handle is invalid

orientation GunOrientation = orientation
Orientation of turret gun
Value: Gun orientation, or null orientation if handle is invalid

number HitpointsLeft = number
Subsystem hitpoints left
Value: Hitpoints left, or 0 if handle is invalid. Setting a value of 0 will disable it - set a value of -1 or lower to actually blow it up.

number HitpointsMax = number
Subsystem hitpoints max
Value: Max hitpoints, or 0 if handle is invalid

vector Position = vector
Subsystem position with regards to main ship (Local Vector)
Value: Subsystem position, or null vector if subsystem handle is invalid

vector GunPosition = vector
Subsystem gun position with regards to main ship (Local vector)
Value: Gun position, or null vector if subsystem handle is invalid

string Name = string
Subsystem name
Value: Subsystem name, or an empty string if handle is invalid

string getModelName()
Returns the original name of the subsystem in the model file
Returns: name or empty string on error

weaponbanktype PrimaryBanks = weaponbanktype
Array of primary weapon banks
Value: Primary banks, or invalid weaponbanktype handle if subsystem handle is invalid

weaponbanktype SecondaryBanks = weaponbanktype
Array of secondary weapon banks
Value: Secondary banks, or invalid weaponbanktype handle if subsystem handle is invalid

object Target = object
Object targetted by this subsystem. If used to set a new target, AI targeting will be switched off.
Value: Targeted object, or invalid object handle if subsystem handle is invalid

boolean TurretResets = boolean
Specifies wether this turrets resets after a certain time of inactivity
Value: true if turret resets, false otherwise

number TurretResetDelay = number
The time (in milliseconds) after that the turret resets itself
Value: Reset delay

number TurnRate = number
The turn rate
Value: Turnrate or -1 on error

boolean TurretLocked = boolean
Whether the turret is locked. Setting to true locks the turret, setting to false frees it.
Value: True if turret is locked, false otherwise

number NextFireTimestamp = number
The next time the turret may attempt to fire
Value: Mission time (seconds) or -1 on error

boolean targetingOverride(boolean)
If set to true, AI targeting for this turret is switched off. If set to false, the AI will take over again.
Returns: Returns true if successful, false otherwise

boolean hasFired()
Determine if a subsystem has fired
Returns: true if if fired, false if not fired, or nil if invalid. resets fired flag when called.

boolean isTurret()
Determines if this subsystem is a turret
Returns: true if subsystem is turret, false otherwise or nil on error

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

nil fireWeapon([Turret weapon index = 1, Flak range = 100])
Fires weapon on turret
Returns: Nothing

boolean rotateTurret(vector Pos[, boolean reset=false)
Rotates the turret to face Pos or resets the turret to its original state
Returns: true on success false otherwise

vector getTurretHeading()
Returns the turrets forward vector
Returns: Returns a normalized version of the forward vector or null vector on error

number, number, number getFOVs()
Returns current turrets FOVs
Returns: Standard FOV, maximum barrel elevation, turret base fov.

matrix getTurretMatrix()
Returns current subsystems turret matrix
Returns: Turret matrix.

===shiptextures===
Ship textures handle

number #
Number of textures on ship
Returns: Number of textures on ship, or 0 if handle is invalid

texture [] number Index/string TextureFilename
Array of ship textures
Returns: Texture, or invalid texture handle on failure

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===ship:object===
Ship handle

subsystem [] string Name/number Index
Array of ship subsystems
Returns: Subsystem handle, or invalid subsystem handle if index or ship handle is invalid

number #
Number of subsystems on ship
Returns: Subsystem number, or 0 if handle is invalid

string ShieldArmorClass = string
Current Armor class of the ships' shield
Value: Armor class name, or empty string if none is set

string ArmorClass = string
Current Armor class
Value: Armor class name, or empty string if none is set

string Name = string
Ship name
Value: Ship name, or empty string if handle is invalid

number AfterburnerFuelLeft = number
Afterburner fuel left
Value: Afterburner fuel left, or 0 if handle is invalid

number AfterburnerFuelMax = number
Afterburner fuel capacity
Value: Afterburner fuel capacity, or 0 if handle is invalid

shipclass Class = shipclass
Ship class
Value: Ship class, or invalid shipclass handle if ship handle is invalid

number CountermeasuresLeft = number
Number of countermeasures left
Value: Countermeasures left, or 0 if ship handle is invalid

weaponclass CountermeasureClass = weaponclass
Weapon class mounted on this ship's countermeasure point
Value: Countermeasure hardpoint weapon class, or invalid weaponclass handle if no countermeasure class or ship handle is invalid

number HitpointsMax = number
Total hitpoints
Value: Ship maximum hitpoints, or 0 if handle is invalid

number WeaponEnergyLeft = number
Current weapon energy reserves
Value: Ship current weapon energy reserve level, or 0 if invalid

number WeaponEnergyMax = number
Maximum weapon energy
Value: Ship maximum weapon energy reserve level, or 0 if invalid

boolean PrimaryTriggerDown = boolean
Determines if primary trigger is pressed or not
Value: True if pressed, false if not, nil if ship handle is invalid

weaponbanktype PrimaryBanks = weaponbanktype
Array of primary weapon banks
Value: Primary weapon banks, or invalid weaponbanktype handle if ship handle is invalid

weaponbanktype SecondaryBanks = weaponbanktype
Array of secondary weapon banks
Value: Secondary weapon banks, or invalid weaponbanktype handle if ship handle is invalid

weaponbanktype TertiaryBanks = weaponbanktype
Array of tertiary weapon banks
Value: Tertiary weapon banks, or invalid weaponbanktype handle if ship handle is invalid

object Target = object
Target of ship. Value may also be a deriviative of the 'object' class, such as 'ship'.
Value: Target object, or invalid object handle if no target or ship handle is invalid

subsystem TargetSubsystem = subsystem
Target subsystem of ship.
Value: Target subsystem, or invalid subsystem handle if no target or ship handle is invalid

team Team = team
Ship's team
Value: Ship team, or invalid team handle if ship handle is invalid

shiptextures Textures = shiptextures
Gets ship textures
Value: Ship textures, or invalid shiptextures handle if ship handle is invalid

boolean FlagAffectedByGravity = boolean
Checks for the "affected-by-gravity" flag
Value: True if flag is set, false if flag is not set and nil on error

boolean Disabled = boolean
The disabled state of this ship
Value: true if ship is diabled, false otherwise

boolean kill([object Killer])
Kills the ship. Set "Killer" to the ship you are killing to self-destruct
Returns: True if successful, false or nil otherwise

boolean addShipEffect(string name, int duration (in milliseconds))
Activates an effect for this ship. Effect names are defined in Post_processing.tbl, and need to be implemented in the main shader. This functions analogous to the ship-effect sexp. NOTE: only one effect can be active at any time, adding new effects will override effects already in progress.
Returns: Returns true if the effect was successfully added, false otherwise

number hasShipExploded()
Checks if the ship explosion event has already happened
Returns: Returns 1 if first explosion timestamp is passed, 2 if second is passed, 0 otherwise

boolean fireCountermeasure()
Launches a countermeasure from the ship
Returns: Whether countermeasure was launched or not

number firePrimary()
Fires ship primary bank(s)
Returns: Number of primary banks fired

number fireSecondary()
Fires ship secondary bank(s)
Returns: Number of secondary banks fired

number getAnimationDoneTime(number Type, number Subtype)
Gets time that animation will be done
Returns: Time (seconds), or 0 if ship handle is invalid

boolean clearOrders()
Clears a ship's orders list
Returns: True if successful, otherwise false or nil

boolean giveOrder(enumeration Order, [object Target=nil, subsystem TargetSubsystem=nil, number Priority=1.0])
Uses the goal code to execute orders
Returns: True if order was given, otherwise false or nil

boolean doManeuver(number Duration, number Heading, number Pitch, number Bank, boolean Force Rotation, number Vertical, number Horizontal, number Forward, boolean Force Movement)
Sets ship maneuver over the defined time period
Returns: True if maneuver order was given, otherwise false or nil

boolean triggerAnimation(string Type, [number Subtype, boolean Forwards])
Triggers an animation. Type is the string name of the animation type, Subtype is the subtype number, such as weapon bank #, and Forwards is boolean.
IMPORTANT: Function is in testing and should not be used with official mod releases
Returns: True if successful, false or nil otherwise

boolean warpIn()
Warps ship in
Returns: True if successful, or nil if ship handle is invalid

boolean warpOut()
Warps ship out
Returns: True if successful, or nil if ship handle is invalid

boolean isWarpingIn()
Checks if ship is warping in
Returns: True if the ship is warping in, false or nil otherwise

number getEMP()
Returns the current emp effect strength acting on the object
Returns: Current EMP effect strength or NIL if object is invalid

number getTimeUntilExplosion()
Returns the time in seconds until the ship explodes
Returns: Time until explosion or -1, if invalid handle or ship isn't exploding

===weapon:object===
Weapon handle

weaponclass Class = weaponclass
Weapon's class
Value: Weapon class, or invalid weaponclass handle if weapon handle is invalid

boolean DestroyedByWeapon = boolean
Whether weapon was destroyed by another weapon
Value: True if weapon was destroyed by another weapon, false if weapon was destroyed by another object or if weapon handle is invalid

number LifeLeft = number
Weapon life left (in seconds)
Value: Life left (seconds) or 0 if weapon handle is invalid

number FlakDetonationRange = number
Range at which flak will detonate (meters)
Value: Detonation range (meters) or 0 if weapon handle is invalid

object Target = object
Target of weapon. Value may also be a deriviative of the 'object' class, such as 'ship'.
Value: Weapon target, or invalid object handle if weapon handle is invalid

subsystem ParentTurret = subsystem
Turret which fired this weapon.
Value: Turret subsystem handle, or an invalid handle if the weapon not fired from a turret

object HomingObject = object
Object that weapon will home in on. Value may also be a deriviative of the 'object' class, such as 'ship'
Value: Object that weapon is homing in on, or an invalid object handle if weapon is not homing or the weapon handle is invalid

vector HomingPosition = vector
Position that weapon will home in on (World vector)
Value: Homing point, or null vector if weapon handle is invalid

subsystem HomingSubsystem = subsystem
Subsystem that weapon will home in on.
Value: Homing subsystem, or invalid subsystem handle if weapon is not homing or weapon handle is invalid

team Team = team
Weapon's team
Value: Weapon team, or invalid team handle if weapon handle is invalid

boolean isArmed([boolean Hit target])
Checks if the weapon is armed.
Returns: boolean value of the weapon arming status

collision info getCollisionInformation()
Returns the collision information for this weapon
Returns: The collision information or invalid handle if none

===beam:object===
Beam handle

weaponclass Class = weaponclass
Weapon's class
Value: Weapon class, or invalid weaponclass handle if beam handle is invalid

vector LastShot = vector
End point of the beam
Value: vector or null vector if beam handle is not valid

vector LastStart = vector
Start point of the beam
Value: vector or null vector if beam handle is not valid

object Target = object
Target of beam. Value may also be a deriviative of the 'object' class, such as 'ship'.
Value: Beam target, or invalid object handle if beam handle is invalid

subsystem TargetSubsystem = subsystem
Subsystem that beam is targeting.
Value: Target subsystem, or invalid subsystem handle if beam handle is invalid

object ParentShip = object
Parent of the beam.
Value: Beam parent, or invalid object handle if beam handle is invalid

subsystem ParentSubsystem = subsystem
Subsystem that beam is fired from.
Value: Parent subsystem, or invalid subsystem handle if beam handle is invalid

number getCollisionCount()
Get the number of collisions in frame.
Returns: Number of beam collisions

vector getCollisionPosition(number)
Get the position of the defined collision.
Returns: World vector

collision info getCollisionInformation(number)
Get the collision information of the specified collision
Returns: handle to information or invalid handle on error

object getCollisionObject(number)
Get the target of the defined collision.
Returns: Object the beam collided with

boolean isExitCollision(number)
Checks if the defined collision was exit collision.
Returns: True if the collision was exit collision, false if entry, nil otherwise

vector getStartDirectionInfo()
Gets the start information about the direction. The vector is a normalized vector from LastStart showing the start direction of a slashing beam
Returns: The start direction or null vector if invalid

vector getEndDirectionInfo()
Gets the end information about the direction. The vector is a normalized vector from LastStart showing the end direction of a slashing beam
Returns: The start direction or null vector if invalid

===wing===
Wing handle

ship [] number Index
Array of ships in the wing
Returns: Ship handle, or invalid ship handle if index is invawing handle is invalid

number #
Number of wings in mission
Returns: Number of wings in mission

===player===
Player handle

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

string getName()
Gets current player name
Returns: Player name, or empty string if handle is invalid

string getCampaignFilename()
Gets current player campaign filename
Returns: Campaign name, or empty string if handle is invalid

string getImageFilename()
Gets current player image filename
Returns: Player image filename, or empty string if handle is invalid

number getMainHall()
Gets player's main hall number
Returns: Main hall index, or 1 if handle is invalid

string getSquadronName()
Gets current player squad name
Returns: Squadron name, or empty string if handle is invalid

===camera===
Camera handle

string (string)
Camera name
Returns: Camera name, or an empty string if handle is invalid

boolean isValid()
True if valid, false or nil if not
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

string Name = string
New camera name
Value: Camera name

number FOV = number
New camera FOV (in radians)
Value: Camera FOV (in radians)

orientation Orientation = orientation
New camera orientation
Value: Camera orientation

vector Position = vector
New camera position
Value: Camera position

object Self = object
New mount object
Value: Camera object

subsystem SelfSubsystem = subsystem
New mount object subsystem
Value: Subsystem that the camera is mounted on

object Target = object
New target object
Value: Camera target object

subsystem TargetSubsystem = subsystem
New target subsystem
Value: Subsystem that the camera is pointed at

boolean setFOV([number FOV, number Zoom Time, number Zoom Acceleration Time, number Zoom deceleration Time])
Sets camera FOV
FOV is the final field of view, in radians, of the camera.
Zoom Time is the total time to take zooming in or out.
Acceleration Time is the total time it should take the camera to get up to full zoom speed.
Deceleration Time is the total time it should take the camera to slow down from full zoom speed.
Returns: true if successful, false or nil otherwise

boolean setOrientation([world orientation Orientation, number Rotation Time, number Acceleration Time, number Deceleration time])
Sets camera orientation and velocity data.
Orientation is the final orientation for the camera, after it has finished moving. If not specified, the camera will simply stop at its current orientation.
Rotation time is how long total, including acceleration, the camera should take to rotate. If it is not specified, the camera will jump to the specified orientation.
Acceleration time is how long it should take the camera to get 'up to speed'. If not specified, the camera will instantly start moving.
Deceleration time is how long it should take the camera to slow down. If not specified, the camera will instantly stop moving.
Returns: true if successful, false or nil otherwise

boolean setPosition([wvector Position, number Translation Time, number Acceleration Time, number Deceleration Time])
Sets camera position and velocity data.
Position is the final position for the camera. If not specified, the camera will simply stop at its current position.
Translation time is how long total, including acceleration, the camera should take to move. If it is not specified, the camera will jump to the specified position.
Acceleration time is how long it should take the camera to get 'up to speed'. If not specified, the camera will instantly start moving.
Deceleration time is how long it should take the camera to slow down. If not specified, the camera will instantly stop moving.
Returns: true if successful, false or nil otherwise

===soundentry===
sounds.tbl table entry handle

number DefaultVolume = number
The default volume of this game sound
Value: Volume in the range from 1 to 0 or -1 on error

string getFilename()
Returns the filename of this sound
Returns: filename or empty string on error

number getDuration()
Gives the length of the sound in seconds.
Returns: the length, or -1 on error

number, number get3DValues(vector Postion[, number radius=0.0])
Computes the volume and the panning of the sound when it would be played from the specified position.
If range is given then the volume will diminish when the listener is withing that distance to the source.
The position of the listener is always the the current viewing position.
Returns: The volume and the panning, in that sequence, or both -1 on error

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===sound===
sound instance handle

number Pitch = number
Pitch of sound, from 100 to 100000
Value: Pitch, or 0 if handle is invalid

number getRemainingTime()
The remaining time of this sound handle
Returns: Remaining time, or -1 on error

boolean setVolume(number)
Sets the volume of this sound instance
Returns: true if succeeded, false otherwise

boolean setPanning(number)
Sets the panning of this sound. Argument ranges from -1 for left to 1 for right
Returns: true if succeeded, false otherwise

boolean setPosition(number[,boolean = true])
Sets the absolute position of the sound. If boolean argument is true then the value is given as a percentage
Returns: true if successfull, false otherwise

boolean rewind(number)
Rewinds the sound by the given number of seconds
Returns: true if succeeded, false otherwise

boolean skip(number)
Skips the given number of seconds of the sound
Returns: true if succeeded, false otherwise

boolean isPlaying()
Specifies if this handle is currently playing
Returns: true if playing, false if otherwise

boolean stop()
Stops the sound of this handle
Returns: true if succeeded, false otherwise

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===3Dsound:sound===
3D sound instance handle

boolean updatePosition(vector Position[, number radius = 0.0])
Updates the given 3D sound with the specified position and an optional range value
Returns: true if succeesed, false otherwise

===control info===
control info handle

number Pitch = number
Pitch of the player ship
Value: Pitch

number Heading = number
Heading of the player ship
Value: Heading

number Bank = number
Bank of the player ship
Value: Bank

number Vertical = number
Vertical control of the player ship
Value: Vertical control

number Sideways = number
Sideways control of the player ship
Value: Sideways control

number Forward = number
Forward control of the player ship
Value: Forward

number ForwardCruise = number
Forward control of the player ship
Value: Forward

number PrimaryCount = number
Number of primary weapons that will fire
Value: Number of weapons to fire, or 0 if handle is invalid

number SecondaryCount = number
Number of secondary weapons that will fire
Value: Number of weapons to fire, or 0 if handle is invalid

number CountermeasureCount = number
Number of countermeasures that will launch
Value: Number of countermeasures to launch, or 0 if handle is invalid

nil clearLuaButtonInfo()
Clears the lua button control info
Returns: Nothing

number, number, number,number getButtonInfo()
Access the four bitfields containing the button info
Returns: Four bitfields

number, number, number,number accessButtonInfo(number, number, number, number)
Access the four bitfields containing the button info
Returns: Four bitfields

nil useButtonControl(number, string)
Adds the defined button control to lua button control data, if number is -1 it tries to use the string
Returns: Nothing

string getButtonControlName(number)
Gives the name of the command corresponding with the given number
Returns: Name of the command

number getButtonControlNumber(string)
Gives the number of the command corresponding with the given string
Returns: Number of the command

boolean AllButtonPolling = boolean
Toggles the all button polling for lua
Value: If the all button polling is enabled or not

number, number, number,number pollAllButtons()
Access the four bitfields containing the button info
Returns: Four bitfields

===particle===
Handle to a particle

vector Position = vector
The current position of the particle (world vector)
Value: The current position

vector Velocity = vector
The current velocity of the particle (world vector)
Value: The current velocity

number Age = number
The time this particle already lives
Value: The current age or -1 on error

number MaximumLife = number
The time this particle can live
Value: The maximal life or -1 on error

number Radius = number
The radius of the particle
Value: The radius or -1 on error

number TracerLength = number
The tracer legth of the particle
Value: The radius or -1 on error

object AttachedObject = object
The object this particle is attached to. If valid the position will be relativ to this object and the velocity will be ignored.
Value: Attached object or invalid object handle on error

boolean isValid()
Detects whether this handle is valid
Returns: true if valid false if not

==Libraries==
===Audio (ad)===
Sound/Music Library

soundentry getSoundentry(string/number)
Return a sound entry matching the specified index or name. If you are using a number then the first valid index is 1
Returns: soundentry or invalid handle on error

sound playSound(soundentry)
Plays the specified sound entry handle
Returns: A handle to the playing sound

sound playLoopingSound(soundentry)
Plays the specified sound as a looping sound
Returns: A handle to the playing sound or invalid handle if playback failed

3Dsound play3DSound(soundentry[, vector source[, vector listener]])
Plays the specified sound entry handle. Source if by default 0, 0, 0 and listener is by default the current viewposition
Returns: A handle to the playing sound

boolean playGameSound(Sound index, [Panning (-1.0 left to 1.0 right), Volume %, Priority 0-3, Voice Message?])
Plays a sound from #Game Sounds in sounds.tbl. A priority of 0 indicates that the song must play; 1-3 will specify the maximum number of that sound that can be played
Returns: True if sound was played, false if not (Replaced with a sound instance object in the future)

boolean playInterfaceSound(Sound index)
Plays a sound from #Interface Sounds in sounds.tbl
Returns: True if sound was played, false if not

number playMusic(string Filename, [float volume = 1.0, bool looping = true])
Plays a music file using FS2Open's builtin music system. Volume should be in the 0.0 - 1.0 range, and is capped at 1.0. Files passed to this function are looped by default.
Returns: Audiohandle of the created audiostream, or -1 on failure

nil stopMusic(int audiohandle, [bool fade = false])
Stops a playing music file, provided audiohandle is valid
Returns: Nothing

===Base (ba)===
Base FreeSpace 2 functions

nil print(string Message)
Prints a string
Returns: Nothing

nil warning(string Message)
Displays a FreeSpace warning (debug build-only) message with the string provided
Returns: Nothing

nil error(string Message)
Displays a FreeSpace error message with the string provided
Returns: Nothing

orientation createOrientation([p/r1c1, b/r1c2, h/r1c3, r2c1, r2c2, r2c3, r3c1, r3c2, r3c3])
Given 0, 3, or 9 arguments, creates an orientation object with that orientation.
Returns: New orientation object, or null orientation on failure

vector createVector([x, y, z])
Creates a vector object
Returns: Vector object

number getFrametime([Do not adjust for time compression (Boolean)])
Gets how long this frame is calculated to take. Use it to for animations, physics, etc to make incremental changes.
Returns: Frame time (seconds)

state getCurrentGameState([Depth (number)])
Gets current FreeSpace state; if a depth is specified, the state at that depth is returned. (IE at the in-game options game, a depth of 1 would give you the game state, while the function defaults to 0, which would be the options screen.
Returns: Current game state at specified depth, or invalid handle if no game state is active yet

string getCurrentMPStatus(NIL)
Gets this computers current MP status
Returns: Current MP status

string setControlMode(NIL or enumeration LE_*_CONTROL)
Sets the current control mode for the game.
Returns: Current control mode

string setButtonControlMode(NIL or enumeration LE_*_BUTTON_CONTROL)
Sets the current control mode for the game.
Returns: Current control mode

control info getControlInfo()
Gets the control info handle.
Returns: control info handle

boolean postGameEvent(gameevent Event)
Sets current game event. Note that you can crash FreeSpace 2 by posting an event at an improper time, so test extensively if you use it.
Returns: True if event was posted, false if passed event was invalid

gameevent GameEvents[] number Index/string Name
Array of game events
Returns: Game event, or invalid gameevent handle if index is invalid

number #
Number of events
Returns: Number of events

gamestate GameStates[] number Index/string Name
Array of game states
Returns: Game state, or invalid gamestate handle if index is invalid

number #
Number of states
Returns: Number of states

===CFile (cf)===
CFile FS2 filesystem access

boolean deleteFile(string Filename, string Path)
Deletes given file. Path must be specified. Use a slash for the root directory.
Returns: True if deleted, false

boolean fileExists(string Filename, [string Path = "", boolean CheckVPs = false])
Checks if a file exists. Use a blank string for path for any directory, or a slash for the root directory.
Returns: True if file exists, false or nil otherwise

file openFile(string Filename, [string Mode="r", string Path = ""])
Opens a file. 'Mode' uses standard C fopen arguments. Use a blank string for path for any directory, or a slash for the root directory.Be EXTREMELY CAREFUL when using this function, as you may PERMANENTLY delete any file by accident
Returns: File handle, or invalid file handle if the specified file couldn't be opened

file openTempFile()
Opens a temp file that is automatically deleted when closed
Returns: File handle, or invalid file handle if tempfile couldn't be created

boolean renameFile(string CurrentFilename, string NewFilename, string Path)
Renames given file. Path must be specified. Use a slash for the root directory.
Returns: True if file was renamed, otherwise false

===Controls (io)===
Controls library

number getMouseX()
Gets Mouse X pos
Returns: Mouse x position, or 0 if mouse is not initialized yet

number getMouseY()
Gets Mouse Y pos
Returns: Mouse y position, or 0 if mouse is not initialized yet

boolean isMouseButtonDown({MOUSE_*_BUTTON enumeration}, [..., ...])
Returns whether the specified mouse buttons are up or down
Returns: Whether specified mouse buttons are down, or false if mouse is not initialized yet

nil setCursorImage(Image filename, [LOCK or UNLOCK])
Sets mouse cursor image, and allows you to lock/unlock the image. (A locked cursor may only be changed with the unlock parameter)
Returns: Nothing

nil setCursorHidden(True to hide mouse, false to show it)
Shows or hides mouse cursor
Returns: Nothing

boolean forceMousePosition(number, number (coordinates))
function to force mouse position
Returns: if the operation succeeded or not

boolean MouseControlStatus = boolean
Gets and sets the retail mouse control status
Value: if the retail mouse is on or off

boolean updateTrackIR()
Updates Tracking Data. Call before using get functions
Returns: Checks if trackir is available and updates variables, returns true if successful, otherwise false

number getTrackIRPitch()
Gets pitch axis from last update
Returns: Pitch value -1 to 1, or 0 on failure

number getTrackIRYaw()
Gets yaw axis from last update
Returns: Yaw value -1 to 1, or 0 on failure

number getTrackIRRoll()
Gets roll axis from last update
Returns: Roll value -1 to 1, or 0 on failure

number getTrackIRX()
Gets x position from last update
Returns: X value -1 to 1, or 0 on failure

number getTrackIRY()
Gets y position from last update
Returns: Y value -1 to 1, or 0 on failure

number getTrackIRZ()
Gets z position from last update
Returns: Z value -1 to 1, or 0 on failure

===HUD (hu)===
HUD library

boolean HUDDrawn = boolean
Current HUD draw status
Value: If the HUD is drawn or not

boolean setHUDGaugeColor(number (index number of the gauge), [number red, number green, number blue, number alpha])
Color used to draw the gauge
Returns: If the operation was successful

number, number, number, number getHUDGaugeColor(number (index number of the gauge))
Color used to draw the gauge
Returns: Red, green, blue, and alpha of the gauge

HudGauge getHUDGaugeHandle(string Name)
Returns a handle to a specified HUD gauge
Returns: HUD Gauge handle, or nil if invalid

===Graphics (gr)===
Graphics Library

camera Cameras[] number Index/string Name
Gets camera
Returns: Ship handle, or invalid ship handle if index was invalid

number #
Gets number of cameras
Returns: Number of cameras

font Fonts[] number Index/string Filename
Array of loaded fonts
Returns: Font handle, or invalid font handle if index is invalid

number #
Number of loaded fonts
Returns: Number of loaded fonts

font CurrentFont = font
Current font
Value: (null)

enumeration CurrentOpacityType = enumeration
Current alpha blending type; uses ALPHABLEND_* enumerations
Value: (null)

texture CurrentRenderTarget = texture
Current rendering target
Value: Current rendering target, or invalid texture handle if screen is render target

nil clearScreen([number Red, number green, number blue, number alpha])
Clears the screen to black, or the color specified.
Returns: Nothing

camera createCamera(string Name, [wvector Position, orientation Orientation])
Creates a new camera using the specified position and orientation (World)
Returns: Camera handle, or invalid camera handle if camera couldn't be created

number getScreenWidth()
Gets screen width
Returns: Width in pixels, or 0 if graphics are not initialized yet

number getScreenHeight()
Gets screen height
Returns: Height in pixels, or 0 if graphics are not initialized yet

vector getVectorFromCoords([number X=center, number Y=center, number Depth, boolean normalize = false])
Returns a vector through screen coordinates x and y. If depth is specified, vector is extended to Depth units into spaceIf normalize is true, vector will be normalized.
Returns: Vector, or zero vector on failure

boolean setTarget([texture Texture])
If texture is specified, sets current rendering surface to a texture.Otherwise, sets rendering surface back to screen.
Returns: True if successful, false otherwise

boolean setCamera([camera handle Camera])
Sets current camera, or resets camera if none specified
Returns: true if successful, false or nil otherwise

nil setColor(number Red, number Green, number Blue, [number Alpha])
Sets 2D drawing color; each color number should be from 0 (darkest) to 255 (brightest)
Returns: Nothing

nil drawCircle(number Radius, number X, number Y)
Draws a circle
Returns: Nothing

nil drawCurve(number X, number Y, number Radius)
Draws a curve
Returns: Nothing

nil drawGradientLine(number X1, number Y1, number X2, number Y2)
Draws a line from (x1,y1) to (x2,y2) with the CurrentColor that steadily fades out
Returns: Nothing

nil drawLine(number X1, number Y1, number X2, number Y2)
Draws a line from (x1,y1) to (x2,y2) with CurrentColor
Returns: Nothing

nil drawPixel(number X, number Y)
Sets pixel to CurrentColor
Returns: Nothing

nil drawPolygon(texture Texture, [vector Position={0,0,0}, orientation Orientation=null, number Width=1.0, number Height=1.0])
Draws a polygon
Returns: Nothing

nil drawRectangle(number X1, number Y1, number X2, number Y2, [boolean Filled=true])
Draws a rectangle with CurrentColor
Returns: Nothing

boolean drawSphere([number Radius = 1.0, vector Position])
Draws a sphere with radius Radius at world vector Position
Returns: True if successful, false or nil otherwise

int drawModel(model, position, orientation)
Draws the given model with the specified position and orientation - Use with extreme care, may not work properly in all scripting hooks.
Returns: Zero if successful, otherwise an integer error code

int drawModelOOR(model Model, vector Position, matrix Orientation, integer Flags)
Draws the given model with the specified position and orientation - Use with extreme care, designer to operate properly only in On Object Render hook.
Returns: Zero if successful, otherwise an integer error code

number,number,number,number drawTargetingBrackets(object Object, [boolean draw=true, int padding=5])
Gets the edge positions of targeting brackets for the specified object. The brackets will only be drawn if draw is true or the default value of draw is used. Brackets are drawn with the current color. The brackets will have a padding (distance from the actual bounding box); the default value (used elsewhere in FS2) is 5.
Returns: Left, top, right, and bottom positions of the brackets, or nil if invalid

number drawString(string Message, [number X1, number Y1, number X2, number Y2])
Draws a string. Use x1/y1 to control position, x2/y2 to limit textbox size.Text will automatically move onto new lines, if x2/y2 is specified.Additionally, calling drawString with only a string argument will automaticallydraw that string below the previously drawn string (or 0,0 if no stringshave been drawn yet
Returns: Number of lines drawn, or 0 on failure

number getStringWidth(string String)
Gets string width
Returns: String width, or 0 on failure

texture createTexture([number Width=512, number Height=512, enumeration Type=TEXTURE_DYNAMIC])
Creates a texture for rendering to.Types are TEXTURE_STATIC - for infrequent rendering - and TEXTURE_DYNAMIC - for frequent rendering.
Returns: New texture handle, or invalid texture handle if texture couldn't be created

texture loadTexture(string Filename, [boolean LoadIfAnimation, boolean NoDropFrames])
Gets a handle to a texture. If second argument is set to true, animations will also be loaded.If third argument is set to true, every other animation frame will not be loaded if system has less than 48 MB memory.
IMPORTANT: Textures will not be unload themselves unless you explicitly tell them to do so.When you are done with a texture, call the Unload() function to free up memory.
Returns: Texture handle, or invalid texture handle if texture couldn't be loaded

boolean drawImage(string Filename/texture Texture, [number X1=0, Y1=0, number X2, number Y2, number UVX1 = 0.0, number UVY1 = 0.0, number UVX2=1.0, number UVY2=1.0, number alpha=1.0])
Draws an image or texture. Any image extension passed will be ignored.The UV variables specify the UV value for each corner of the image. In UV coordinates, (0,0) is the top left of the image; (1,1) is the lower right.
Returns: Whether image was drawn

boolean drawMonochromeImage(string Filename/texture Texture, number X1, number Y1, [number X2, number Y2, number alpha=1.0])
Draws a monochrome image using the current color
Returns: Whether image was drawn

number getImageWidth(string Filename)
Gets image width
Returns: Image width, or 0 if filename is invalid

number getImageHeight(Image name)
Gets image height
Returns: Image height, or 0 if filename is invalid

nil flashScreen(number Red, number Green, number Blue)
Flashes the screen
Returns: Nothing

model loadModel(string Filename)
Loads the model - will not setup subsystem data, DO NOT USE FOR LOADING SHIP MODELS
Returns: Handle to a model

boolean hasViewmode(enumeration)
Specifies if the current viemode has the specified flag, see VM_* enumeration
Returns: true if flag is present, false otherwise

===HookVariables (hv)===
Hook variables repository

string Globals[] number Index
Array of current HookVariable names
Returns: Hookvariable name, or empty string if invalid index specified

number #
Number of HookVariables
Returns: Number of HookVariables

===Mission (mn)===
Mission library

object getObjectFromSignature(number Signature)
Gets a handle of an object from its signature
Returns: Handle of object with signaure, invalid handle if signature is not in use

boolean evaluateSEXP(string)
Runs the defined SEXP script
Returns: if the operation was successful

boolean runSEXP(string)
Runs the defined SEXP script
Returns: if the operation was successful

asteroid Asteroids[] number Index
Gets asteroid
Returns: Asteroid handle, or invalid handle if invalid index specified

number #
Number of asteroids in mission. Note that the value returned is only good until an asteroid is destroyed, and so cannot be relied on for more than one frame.
Returns: Number of asteroids in the mission, or 0 if asteroids are not enabled

debris Debris[] number Index
Array of debris in the current mission
Returns: Debris handle, or invalid debris handle if index wasn't valid

number #
Number of debris pieces in the mission. Note that the value returned is only good until a piece of debris is destroyed, and so cannot be relied on for more than one frame.
Returns: Current number of debris particles

ship EscortShips[] number Index
Gets escort ship at specified index on escort list
Returns: Specified ship, or invalid ship handle if invalid index

number #
Current number of escort ships
Returns: Current number of escort ships

event Events[] number Index/string Name
Indexes events list
Returns: Event handle, or invalid event handle if index was invalid

number #
Number of events in mission
Returns: Number of events in mission

sexpvariable SEXPVariables[] number Index/string Name
Array of SEXP variables. Note that you can set a sexp variable using the array, eg 'SEXPVariables[1] = "newvalue"'
Returns: Handle to SEXP variable, or invalid sexpvariable handle if index was invalid

number #
Current number of SEXP variables
Returns: Counts number of loaded SEXP Variables. May be slow.

ship Ships[] number Index/string Name
Gets ship
Returns: Ship handle, or invalid ship handle if index was invalid

number #
Number of ships in the mission. This function is somewhat slow, and should be set to a variable for use in looping situations. Note that the value returned is only good until a ship is destroyed, and so cannot be relied on for more than one frame.
Returns: Number of ships in the mission, or 0 if ships haven't been initialized yet

waypoint Waypoints[] number Index
Array of waypoints in the current mission
Returns: Waypoint handle, or invalid waypoint handle if index was invalid

number #
Gets number of waypoints in mission. Note that this is only accurate for one frame.
Returns: Number of waypoints in the mission

waypointlist WaypointLists[] number Index/string WaypointListName
Array of waypoint lists
Returns: Gets waypointlist handle

number #
Number of waypoint lists in mission. Note that this is only accurate for one frame.
Returns: Number of waypoint lists in the mission

weapon Weapons[] number Index
Gets handle to a weapon object in the mission.
Returns: Weapon handle, or invalid weapon handle if index is invalid

number #
Number of weapon objects in mission. Note that this is only accurate for one frame.
Returns: Number of weapon objects in mission

beam Beams[] number Index
Gets handle to a beam object in the mission.
Returns: Beam handle, or invalid beam handle if index is invalid

number #
Number of beam objects in mission. Note that this is only accurate for one frame.
Returns: Number of beam objects in mission

wing Wings[] number Index/string WingName
Wings in the mission
Returns: Wing handle, or invalid wing handle if index or name was invalid

number #
Number of wings in mission
Returns: Number of wings in mission

ship createShip([string Name, shipclass Class=Shipclass[1], orientation Orientation=null, vector Position={0,0,0}])
Creates a ship and returns a handle to it using the specified name, class, world orientation, and world position
Returns: Ship handle, or invalid ship handle if ship couldn't be created

waypoint createWaypoint([vector Position, waypointlist List])
Creates a waypoint
Returns: Waypoint handle, or invalid waypoint handle if waypoint couldn't be created

weapon createWeapon([weaponclass Class=WeaponClass[1], orientation Orientation=null, world vector Position={0,0,0}, object Parent = nil, number Group = -1)
Creates a weapon and returns a handle to it. 'Group' is used for lighting grouping purposes; for example, quad lasers would only need to act as one light source.
Returns: Weapon handle, or invalid weapon handle if weapon couldn't be created.

string getMissionFilename()
Gets mission filename
Returns: Mission filename, or empty string if game is not in a mission

boolean startMission([Filename or MISSION_* enumeration, Briefing = true])
Starts the defined mission
Returns: True, or false if the function fails

number getMissionTime()
Game time in seconds since the mission was started; is affected by time compression
Returns: Mission time (seconds), or 0 if game is not in a mission

boolean loadMission(Mission name)
Loads a mission
Returns: True if mission was loaded, otherwise false

nil unloadMission()
Stops the current mission and unloads it
Returns: Nothing

nil simulateFrame()
Simulates mission frame
Returns: Nothing

nil renderFrame()
Renders mission frame, but does not move anything
Returns: Nothing

===BitOps (bit)===
Bitwise Operations library

number AND(number, number)
Values for which bitwise boolean AND operation is performed
Returns: Result of the AND operation

number OR(number, number)
Values for which bitwise boolean OR operation is performed
Returns: Result of the OR operation

number XOR(number, number)
Values for which bitwise boolean XOR operation is performed
Returns: Result of the XOR operation

number toggleBit(number, number (bit))
Toggles the value of the set bit in the given number for 32 bit integer
Returns: Result of the operation

boolean checkBit(number, number (bit))
Checks the value of the set bit in the given number for 32 bit integer
Returns: Was the bit true of false

number addBit(number, number (bit))
Performs inclusive or (OR) operation on the set bit of the value
Returns: Result of the operation

===Tables (tb)===
Tables library

ship ShipClasses[] number Index/string Name
Array of ship classes
Returns: Ship handle, or invalid ship handle if index is invalid

number #
Number of ship classes
Returns: Number of ship classes, or 0 if ship classes haven't been loaded yet

weapon WeaponClasses[] number Index/string WeaponName
Array of weapon classes
Returns: Weapon class handle, or invalid weaponclass handle if index is invalid

number #
Number of weapon classes
Returns: Number of weapon classes, or 0 if weapon classes haven't been loaded yet

===Testing (ts)===
Experimental or testing stuff

nil avdTest()
Test the AVD Physics code
Returns: Nothing

particle createParticle(vector Position, vector Velocity, number Lifetime, number Radius, enumeration Type, [number Tracer length=-1, boolean Reverse=false, texture Texture=Nil, object Attached Object=Nil])
Creates a particle. Use PARTICLE_* enumerations for type.Reverse reverse animation, if one is specifiedAttached object specifies object that Position will be (and always be) relative to.
Returns: Handle to the created particle

string getStack()
Generates an ADE stackdump
Returns: Current Lua stack

boolean isCurrentPlayerMulti()
Returns whether current player is a multiplayer pilot or not.
Returns: Whether current player is a multiplayer pilot or not

boolean isPXOEnabled()
Returns whether PXO is currently enabled in the configuration.
Returns: Whether PXO is enabled or not

==Enumerations==
ALPHABLEND_FILTER
ALPHABLEND_NONE
CFILE_TYPE_NORMAL
CFILE_TYPE_MEMORY_MAPPED
MOUSE_LEFT_BUTTON
MOUSE_RIGHT_BUTTON
MOUSE_MIDDLE_BUTTON
ORDER_ATTACK
ORDER_ATTACK_ANY
ORDER_DEPART
ORDER_DISABLE
ORDER_DISARM
ORDER_DOCK
ORDER_EVADE
ORDER_FLY_TO
ORDER_FORM_ON_WING
ORDER_GUARD
ORDER_IGNORE_SHIP
ORDER_KEEP_SAFE_DISTANCE
ORDER_PLAY_DEAD
ORDER_REARM
ORDER_STAY_NEAR
ORDER_STAY_STILL
ORDER_UNDOCK
ORDER_WAYPOINTS
ORDER_WAYPOINTS_ONCE
PARTICLE_DEBUG
PARTICLE_BITMAP
PARTICLE_FIRE
PARTICLE_SMOKE
PARTICLE_SMOKE2
PARTICLE_PERSISTENT_BITMAP
SEXPVAR_CAMPAIGN_PERSISTENT
SEXPVAR_NOT_PERSISTENT
SEXPVAR_PLAYER_PERSISTENT
SEXPVAR_TYPE_NUMBER
SEXPVAR_TYPE_STRING
TEXTURE_STATIC
TEXTURE_DYNAMIC
LOCK
UNLOCK
NONE
SHIELD_FRONT
SHIELD_LEFT
SHIELD_RIGHT
SHIELD_BACK
MISSION_REPEAT
NORMAL_CONTROLS
LUA_STEERING_CONTROLS
LUA_FULL_CONTROLS
NORMAL_BUTTON_CONTROLS
LUA_ADDITIVE_BUTTON_CONTROL
LUA_OVERRIDE_BUTTON_CONTROL
VM_INTERNAL
VM_EXTERNAL
VM_TRACK
VM_DEAD_VIEW
VM_CHASE
VM_OTHER_SHIP
VM_EXTERNAL_CAMERA_LOCKED
VM_WARP_CHASE
VM_PADLOCK_UP
VM_PADLOCK_REAR
VM_PADLOCK_LEFT
VM_PADLOCK_RIGHT
VM_WARPIN_ANCHOR
VM_TOPDOWN
VM_FREECAMERA

Scripting functions

2012-07-15T12:03:49Z

Aginor: /* HudGauge */

This page explains all the functions mentioned in the scripting.html file, including their syntax, remarks on their use and common errors modders may encounter when they use them.

----

Script Output - FSO v3.6.13 (FS2_Open Scripting)

==Conditional Hooks==

===Conditions===
*State
*Campaign
*Mission
*Object Type
*Ship
*Ship class
*Ship type
*Weapon class
*KeyPress
*Version
*Application
**''Usually: $Application: FS2_Open''

===Actions===
*On Game Init
*On Splash Screen
*On State Start
*On Frame
*On Key Pressed
*On Key Released
*On Mouse Moved
*On Mouse Pressed
*On Mouse Released
*On State End
*On Mission Start
*On HUD Draw
*On Ship Collision
*On Weapon Collision
*On Debris Collision
*On Asteroid Collision
*On Object Render
*On Warp In
*On Warp Out
*On Death
*On Mission End
*On Weapon Delete
*On Weapon Equipped
*On Weapon Fired
*On Weapon Selected
*On Weapon Deselected
*On Gameplay Start
*On Turret Fired
*On Primary Fire
*On Secondary Fire

==Types==
===vector===
:'''Vector object'''
 
:''number [] x,y,z or 1-3''
::*Vector component
::*'''Returns:''' Value at index, or 0 if vector handle is invalid
 
:''[[Scripting_functions#vector|vector]] + number/vector''
::*Adds vector by another vector, or adds all axes by value
::*'''Returns:''' Final vector, or null vector if error occurs
 
:''[[Scripting_functions#vector|vector]] - number/vector''
::*Subtracts vector from another vector, or subtracts all axes by value
::*'''Returns:''' Final vector, or null vector if error occurs
 
:''[[Scripting_functions#vector|vector]] * number/vector''
::*Scales vector object (Multiplies all axes by number), or multiplies each axes by the other vector's axes.
::*''' Returns:''' Final vector, or null vector if error occurs
 
:''[[Scripting_functions#vector|vector]] / number/vector''
::*Scales vector object (Divide all axes by number), or divides each axes by the dividing vector's axes.
::*'''Returns:''' Final vector, or null vector if error occurs
 
:''string (string)''
::*Converts a vector to string with format "(x,y,z)"
::*'''Returns:''' Vector as string, or empty string if handle is invalid
 
:''[[Scripting_functions#orientation|orientation]]'' '''getOrientation()'''
::*Returns orientation object representing the direction of the vector. Does not require vector to be normalized.
::*'''Returns:''' Orientation object, or null orientation object if handle is invalid
 
:''number'' '''getMagnitude()'''
::*Returns the magnitude of a vector (Total regardless of direction)
::*'''Returns:''' Magnitude of vector, or 0 if handle is invalid
 
:''number'' '''getDistance('''''Vector''''')'''
::*Distance
::*'''Returns:''' Returns distance from another vector
 
:''number'' '''getDotProduct('''''vector OtherVector''''')'''
::*Returns dot product of vector object with vector argument
::*'''Returns:''' Dot product, or 0 if a handle is invalid
 
:''[[Scripting_functions#vector|vector]]'' '''getCrossProduct('''''vector OtherVector''''')'''
::*Returns cross product of vector object with vector argument
::*'''Returns:''' Cross product, or null vector if a handle is invalid
 
:''number,number'' '''getScreenCoords()'''
::*Gets screen cordinates of a world vector
::*'''Returns:''' X (number), Y (number), or false if off-screen
 
:''vector'' '''getNormalized()'''
::*Returns a normalized version of the vector
::*'''Returns:''' Normalized Vector, or NIL if invalid
 
===orientation===
Orientation matrix object

number [] p,b,h or 1-9
Orientation component - pitch, bank, heading, or index into 3x3 matrix (1-9)
Returns: Number at the specified index, or 0 if index is invalid.

orientation * orientation
Multiplies two matrix objects)
Returns: matrix, or empty matrix if unsuccessful

string (string)
Converts a matrix to a string with format "[r1c1 r2c1 r3c1 | r1c2 r2c2 r3c2| r1c3 r2c3 r3c3]"
Returns: Formatted string or "

orientation getInterpolated(orientation Final, number Factor)
Returns orientation that has been interpolated to Final by Factor (0.0-1.0)
Returns: Interpolated orientation, or null orientation on failure

orientation getTranspose()
Returns a transpose version of the specified orientation
Returns: Transpose matrix, or null orientation on failure

vector rotateVector(vector Input)
Returns rotated version of given vector
Returns: Rotated vector, or empty vector on error

vector unrotateVector(vector Input)
Returns unrotated version of given vector
Returns: Unrotated vector, or empty vector on error

===enumeration===
Enumeration object

enumeration = enumeration
Sets enumeration to specified value (if it is not a global
Returns: enumeration

string (string)
Returns enumeration name
Returns: Enumeration name, or "" if invalid

===event===
Mission event handle

string Name = string
Mission event name
Value: (null)

string DirectiveText = string
Directive text
Value: (null)

string DirectiveKeypressText = string
Raw directive keypress text, as seen in FRED.
Value: (null)

number Interval = number
Time for event to repeat (in seconds)
Value: Repeat time, or 0 if invalid handle

number ObjectCount = number
Number of objects left for event
Value: Repeat count, or 0 if invalid handle

number RepeatCount = number
Event repeat count
Value: Repeat count, or 0 if invalid handle

number Score = number
Event score
Value: Event score, or 0 if invalid handle

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===file===
File handle

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

nil close()
Instantly closes file and invalidates all file handles
Returns: Nothing

boolean flush()
Flushes file buffer to disk.
Returns: True for success, false on failure

string getPath()
Determines path of the given file
Returns: Path string of the file handle, or an empty string if it doesn't have one, or the handle is invalid

number or string, ... read(number or string, ...)
Reads part of or all of a file, depending on arguments passed. Based on basic Lua file:read function.Returns nil when the end of the file is reached.

* "*n" - Reads a number.
* "*a" - Reads the rest of the file and returns it as a string.
* "*l" - Reads a line. Skips the end of line markers.
* (number) - Reads given number of characters, then returns them as a string.

Returns: Requested data, or nil if the function fails

number seek([string Whence="cur", number Offset=0])
# Changes position of file, or gets location.Whence can be:"set" - File start.
# "cur" - Current position in file.
# "end" - File end.
Returns: new offset, or false or nil on failure

number write(string or number, ...)
Writes a series of Lua strings or numbers to the current file.
Returns: Number of items successfully written.

===font===
font handle

string (string)
Filename of font
Returns: Font filename, or an empty string if the handle is invalid

string Filename = string
Filename of font (including extension)
Value: (null)

number Height = number
Height of font (in pixels)
Value: Font height, or 0 if the handle is invalid

boolean isValid()
True if valid, false or nil if not
Returns: Detects whether handle is valid

===gameevent===
Game event

string (string)
Game event name
Returns: Game event name, or empty string if handle is invalid

string Name = string
Game event name
Value: Game event name, or empty string if handle is invalid

===gamestate===
Game state

string (string)
Game state name
Returns: Game state name, or empty string if handle is invalid

string Name = string
Game state name
Value: Game state name, or empty string if handle is invalid

===HudGauge===
:'''HUD Gauge handle'''
 
:''string Name = string''
::*Custom HUD Gauge name
::*'''Returns:''' Custom HUD Gauge name, or nil if handle is invalid
 
:''string Text = string''
::*Custom HUD Gauge text
::*'''Returns:''' Value: Custom HUD Gauge text, or nil if handle is invalid
 

===eyepoint===
Eyepoint handle

vector Normal = vector
Eyepoint normal
Value: Eyepoint normal, or null vector if handle is invalid

vector Position = vector
Eyepoint location (Local vector)
Value: Eyepoint location, or null vector if handle is invalid

boolean IsValid()
Detect whether this handle is valid
Returns: true if valid false otherwise

===model===
3D Model (POF) handle

modeltextures_h Textures = modeltextures_h
Model textures
Value: Model textures, or an invalid modeltextures handle if the model handle is invalid

thrusters Thrusters = thrusters
Model thrusters
Value: Thrusters of the model or invalid handle

eyepoints Eyepoints = eyepoints
Model eyepoints
Value: Array of eyepoints or invalid handle on error

vector BoundingBoxMax = vector
Model bounding box maximum
Value: Model bounding box, or an empty vector if the handle is invalid

vector BoundingBoxMin = vector
Model bounding box minimum
Value: Model bounding box, or an empty vector if the handle is invalid

string Filename = string
Model filename
Value: Model filename, or an empty string if the handle is invalid

number Mass = number
Model mass
Value: Model mass, or 0 if the model handle is invalid

orientation MomentOfInertia = orientation
Model moment of inertia
Value: Moment of Inertia matrix or identity matrix if invalid

number Radius = number
Model radius (Used for collision & culling detection)
Value: Model Radius or 0 if invalid

boolean isValid()
True if valid, false or nil if not
Returns: Detects whether handle is valid

===modeltextures_h===
Array of materials

number #
Number of textures on model
Returns: Number of model textures

texture [] texture
number Index/string TextureName
Returns: Model textures, or invalid modeltextures handle if model handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===eyepoints===
Array of model eye points

number #
Gets the number of eyepoints on this model
Returns: Number of eyepoints on this model or 0 on error

eyepoint [] eyepoint
Gets en eyepoint handle
Returns: eye handle or invalid handle on error

boolean isValid()
Detects whether handle is valid or not
Returns: true if valid false otherwise

===thrusters===
The thrusters of a model

number #
Number of thruster banks on the model
Returns: Number of thrusterbanks

thrusterbank [] number Index
Array of all thrusterbanks on this thruster
Returns: Handle to the thrusterbank or invalid handle if index is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===thrusterbank===
A model thrusterbank

number #
Number of thrusters on this thrusterbank
Returns: Number of thrusters on this bank or 0 if handle is invalid

glowpoint [] number Index
Array of glowpoint
Returns: Glowpoint, or invalid glowpoint handle on failure

boolean isValid()
Detectes if this handle is valid
Returns: true if this handle is valid, false otherwise

===glowpoint===
A model glowpoint

vector Position
The (local) vector to the position of the glowpoint

number Radius
The radius of the glowpoint

boolean isValid()
Returns wether this handle is valid or not
Returns: True if handle is valid, false otherwise

===order===
order handle

boolean remove()
Removes the given order from the ship's priority queue.
Returns: True if order was successfully removed, otherwise false or nil.

===shiporders===
Ship orders

number #
Number of textures on ship
Returns: Number of textures on ship, or 0 if handle is invalid

order [] number Index/string TextureFilename
Array of ship orders
Returns: Order, or invalid texture handle on failure

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===physics===
Physics handle

number AfterburnerAccelerationTime = number
Afterburner acceleration time
Value: Afterburner acceleration time, or 0 if handle is invalid

vector AfterburnerVelocityMax = vector
Afterburner max velocity (Local vector)
Value: Afterburner max velocity, or null vector if handle is invalid

number BankingConstant = number
Banking constant
Value: Banking constant, or 0 if handle is invalid

number ForwardAccelerationTime = number
Forward acceleration time
Value: Forward acceleration time, or 0 if handle is invalid

number ForwardDecelerationTime = number
Forward deceleration time
Value: Forward decleration time, or 0 if handle is invalid

number ForwardThrust = number
Forward thrust amount (0-1), used primarily for thruster graphics
Value: Forward thrust, or 0 if handle is invalid

number Mass = number
Object mass
Value: Object mass, or 0 if handle is invalid

vector RotationalVelocity = vector
Rotational velocity (Local vector)
Value: Rotational velocity, or null vector if handle is invalid

number RotationalVelocityDamping = number
Rotational damping, ie derivative of rotational speed
Value: Rotational damping, or 0 if handle is invalid

number RotationalVelocityDesired = lvector
Desired rotational velocity
Value: Desired rotational velocity, or 0 if handle is invalid

vector RotationalVelocityMax = vector
Maximum rotational velocity (Local vector)
Value: Maximum rotational velocity, or null vector if handle is invalid

number ShockwaveShakeAmplitude = number
How much shaking from shockwaves is applied to object
Value: Shockwave shake amplitude, or 0 if handle is invalid

number SideThrust = number
Side thrust amount (0-1), used primarily for thruster graphics
Value: Side thrust amount, or 0 if handle is invalid

number SlideAccelerationTime = number
Time to accelerate to maximum slide velocity
Value: Sliding acceleration time, or 0 if handle is invalid

number SlideDecelerationTime = number
Time to decelerate from maximum slide speed
Value: Sliding deceleration time, or 0 if handle is invalid

vector Velocity = vector
Object world velocity (World vector)
Value: Object velocity, or null vector if handle is invalid

vector VelocityDesired = vector
Desired velocity (World vector)
Value: Desired velocity, or null vector if handle is invalid

vector VelocityMax = vector
Object max local velocity (Local vector)
Value: Maximum velocity, or null vector if handle is invalid

number VerticalThrust = number
Vertical thrust amount (0-1), used primarily for thruster graphics
Value: Vertical thrust amount, or 0 if handle is invalid

boolean AfterburnerActive = boolean
Specifies if the afterburner is active or not
Value: true if afterburner is active false otherwise

boolean isValid()
True if valid, false or nil if not
Returns: Detects whether handle is valid

number getSpeed()
Gets total speed as of last frame
Returns: Total speed, or 0 if handle is invalid

number getForwardSpeed()
Gets total speed in the ship's 'forward' direction as of last frame
Returns: Total forward speed, or 0 if handle is invalid

boolean isAfterburnerActive()
True if Afterburners are on, false or nil if not
Returns: Detects whether afterburner is active

boolean isGliding()
True if glide mode is on, false or nil if not
Returns: Detects if ship is gliding

===sexpvariable===
SEXP Variable handle

enumeration Persistence = enumeration
SEXP Variable persistance, uses SEXPVAR_*_PERSISTENT enumerations
Value: SEXPVAR_*_PERSISTENT enumeration, or invalid numeration if handle is invalid

enumeration Type = enumeration
SEXP Variable type, uses SEXPVAR_TYPE_* enumerations
Value: SEXPVAR_TYPE_* enumeration, or invalid numeration if handle is invalid

string Value = number/string
SEXP variable value
Value: SEXP variable contents, or nil if the variable is of an invalid type or the handle is invalid

string (string)
Returns SEXP name
Returns: SEXP name, or empty string if handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

boolean delete()
Deletes a SEXP Variable
Returns: True if successful, false if the handle is invalid

===shields===
Shields handle

number [] enumeration/number
Gets or sets shield quadrant strength. Use "SHIELD_*" enumeration or 1-4 for a specific quadrant, or NONE for the entire shield
Returns: Quadrant/shield strength, or 0 if handle is invalid

number CombinedLeft = number
Total shield hitpoints left (for all quadrants combined)
Value: Combined shield strength, or 0 if handle is invalid

number CombinedMax = number
Maximum shield hitpoints (for all quadrants combined)
Value: Combined maximum shield strength, or 0 if handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===shiptype===
Ship type handle

string Name = string
Ship type name
Value: Ship type name, or empty string if handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===species===
Species handle

string Name = string
Species name
Value: Species name, or empty string if handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===team===
Team handle

boolean == team, team
Checks whether two teams are the same team
Returns: true if equal

string Name = string
Team name
Value: Team name, or empty string if handle is invalid

number, number, number getColor()
Gets the IFF color of the specified Team
Returns: rgb color for the specified team or nil if invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===texture===
Texture handle

nil __gc
Auto-deletes texture
Returns: Nothing

boolean == texture, texture
Checks if two texture handles refer to the same texture
Returns: True if textures are equal

texture [] number
Returns texture handle to specified frame number in current texture's animation.This means that [1] will always return the first frame in an animation, no matter what frame an animation is.You cannot change a texture animation frame.
Returns: Texture handle, or invalid texture handle if index is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

nil unload()
Unloads a texture from memory
Returns: Nothing

string getFilename()
Returns filename for texture
Returns: Filename, or empty string if handle is invalid

number getWidth()
Gets texture width
Returns: Texture width, or 0 if handle is invalid

number getHeight()
Gets texture height
Returns: Texture height, or 0 if handle is invalid

number getFPS()
Gets frames-per-second of texture
Returns: Texture FPS, or 0 if handle is invalid

number getFramesLeft()
Gets number of frames left, from handle's position in animation
Returns: Frames left, or 0 if handle is invalid

===material===
Texture map, including diffuse, glow, and specular textures

texture BaseMap = texture
Base texture
Value: Base texture, or invalid texture handle if material handle is invalid

texture GlowMap = texture
Glow texture
Value: Glow texture, or invalid texture handle if material handle is invalid

texture SpecularMap = texture
Specular texture
Value: Texture handle, or invalid texture handle if material handle is invalid

===weaponclass===
Weapon class handle

string (string)
Weapon class name
Returns: Weapon class name, or an empty string if handle is invalid

string Name = string
Weapon class name
Value: Weapon class name, or empty string if handle is invalid

string Title = string
Weapon class title
Value: Weapon class title, or empty string if handle is invalid

string Description = string
Weapon class description string
Value: Description string, or empty string if handle is invalid

string TechTitle = string
Weapon class tech title
Value: Tech title, or empty string if handle is invalid

string TechAnimationFilename = string
Weapon class animation filename
Value: Filename, or empty string if handle is invalid

string TechDescription = string
Weapon class tech description string
Value: Description string, or empty string if handle is invalid

model Model = model
Model
Value: Weapon class model, or invalid model handle if weaponclass handle is invalid

number ArmorFactor = number
Amount of weapon damage applied to ship hull (0-1.0)
Value: Armor factor, or empty string if handle is invalid

number Damage = number
Amount of damage that weapon deals
Value: Damage amount, or 0 if handle is invalid

number FireWait = number
Weapon fire wait (cooldown time) in seconds
Value: Fire wait time, or 0 if handle is invalid

number FreeFlightTime = number
The time the weapon will fly before turing onto its target
Value: Free flight time or emty string if invalid

number LifeMax = number
Life of weapon in seconds
Value: Life of weapon, or 0 if handle is invalid

number Range = number
Range of weapon in meters
Value: Weapon Range, or 0 if handle is invalid

number Mass = number
Weapon mass
Value: Weapon mass, or 0 if handle is invalid

number ShieldFactor = number
Amount of weapon damage applied to ship shields (0-1.0)
Value: Shield damage factor, or 0 if handle is invalid

number SubsystemFactor = number
Amount of weapon damage applied to ship subsystems (0-1.0)
Value: Subsystem damage factor, or 0 if handle is invalid

number TargetLOD = number
LOD used for weapon model in the targeting computer
Value: LOD number, or 0 if handle is invalid

number Speed = number
Weapon max speed, aka $Velocity in weapons.tbl
Value: Weapon speed, or 0 if handle is invalid

boolean Bomb = boolean
Is weapon class flagged as bomb
Value: New flag

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

number getWeaponClassIndex()
Gets the index value of the weapon class
Returns: index value of the weapon class

boolean isLaser()
Return true if the weapon is a laser (this includes balistic primaries)
Returns: true if the weapon is a laser, false otherwise

boolean isMissile()
Return true if the weapon is a missile
Returns: true if the weapon is a missile, false otherwise

boolean isBeam()
Return true if the weapon is a beam
Returns: true if the weapon is a beam, false otherwise

===collision info===
Information about a collision

nil __gc
Removes the allocated reference of this handle
Returns: Nothing

model Model = model
The model this collision info is about
Value: The model

number getCollisionDistance()
The distance to the closest collision point
Returns: distance or -1 on error

vector getCollisionPoint([boolean local])
The collision point of this information (local to the object if boolean is set to true)
Returns: The collision point or nil of none

vector getCollisionNormal([boolean local])
The collision normal of this information (local to object if boolean is set to true)
Returns: The collision normal or nil of none

boolean isValid()
Detects if this handle is valid
Returns: true if valid false otherwise

===object===
Object handle

boolean == object, object
Checks whether two object handles are for the same object
Returns: True if equal, false if not or a handle is invalid

string (string)
Returns name of object (if any)
Returns: Object name, or empty string if handle is invalid

object Parent = object
Parent of the object. Value may also be a deriviative of the 'object' class, such as 'ship'.
Value: Parent handle, or invalid handle if object is invalid

vector Position = vector
Object world position (World vector)
Value: World position, or null vector if handle is invalid

vector LastPosition = vector
Object world position as of last frame (World vector)
Value: World position, or null vector if handle is invalid

orientation Orientation = orientation
Object world orientation (World orientation)
Value: Orientation, or null orientation if handle is invalid

orientation LastOrientation = orientation
Object world orientation as of last frame (World orientation)
Value: Orientation, or null orientation if handle is invalid

physics Physics = physics
Physics data used to move ship between frames
Value: Physics data, or invalid physics handle if object handle is invalid

number HitpointsLeft = number
Hitpoints an object has left
Value: Hitpoints left, or 0 if handle is invalid

shields Shields = shields
Shields
Value: Shields handle, or invalid shields handle if object handle is invalid

number getSignature()
Gets the object's unique signature
Returns: Returns the objects unique numeric signature, or -1 if invalid. useful for creating a metadata sytem

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

string getBreedName()
Gets object type
Returns: Object type name, or empty string if handle is invalid

number CollisionGroups = number
Collision group data
Value: Current collision group signature. NOTE: This is a bitfield, NOT a normal number.

vector getfvec([boolean normalize])
Returns the objects' current fvec.
Returns: Objects' forward vector, or nil if invalid. If called with a true argument, vector will be normalized.

vector getuvec([boolean normalize])
Returns the objects' current uvec.
Returns: Objects' up vector, or nil if invalid. If called with a true argument, vector will be normalized.

vector getrvec([boolean normalize])
Returns the objects' current rvec.
Returns: Objects' rvec, or nil if invalid. If called with a true argument, vector will be normalized.

vector, collision info checkRayCollision(vector Start Point, vector End Point, [boolean Local])
Checks the collisions between the polygons of the current object and a ray
Returns: World collision point (local if boolean is set to true) and the specific collsision info, nil if no collisions

===asteroid:object===
Asteroid handle

object Target = object
Asteroid target object; may be object derivative, such as ship.
Value: Target object, or invalid handle if asteroid handle is invalid

boolean kill([ship killer=nil, wvector hitpos=nil])
Kills the asteroid. Set "killer" to designate a specific ship as having been the killer, and "hitpos" to specify the world position of the hit location; if nil, the asteroid center is used.
Returns: True if successful, false or nil otherwise

===shipclass===
Ship class handle

string (string)
Ship class name
Returns: Ship class name, or an empty string if handle is invalid

string Name = string
Ship class name
Value: Ship class name, or an empty string if handle is invalid

string ShortName = string
Ship class short name
Value: Ship short name, or empty string if handle is invalid

string TypeString = string
Ship class type string
Value: Type string, or empty string if handle is invalid

string ManeuverabilityString = string
Ship class maneuverability string
Value: Maneuverability string, or empty string if handle is invalid

string ArmorString = string
Ship class armor string
Value: Armor string, or empty string if handle is invalid

string ManufacturerString = string
Ship class manufacturer
Value: Manufacturer, or empty string if handle is invalid

string Description = string
Ship class description
Value: Description, or empty string if handle is invalid

string TechDescription = string
Ship class tech description
Value: Tech description, or empty string if handle is invalid

number AfterburnerFuelMax = number
Afterburner fuel capacity
Value: Afterburner capacity, or 0 if handle is invalid

number CountermeasuresMax = number
Maximum number of countermeasures the ship can carry
Value: Countermeasure capacity, or 0 if handle is invalid

model Model = model
Model
Value: Ship class model, or invalid model handle if shipclass handle is invalid

model CockpitModel = model
Model used for first-person cockpit
Value: Cockpit model

number HitpointsMax = number
Ship class hitpoints
Value: Hitpoints, or 0 if handle is invalid

species Species = Species
Ship class species
Value: Ship class species, or invalid species handle if shipclass handle is invalid

shiptype Type = shiptype
Ship class type
Value: Ship type, or invalid handle if shipclass handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

boolean isInTechroom()
Gets whether or not the ship class is available in the techroom
Returns: Whether ship has been revealed in the techroom, false if handle is invalid

boolean renderTechModel(X1, Y1, X2, Y2, [Rotation %, Pitch %, Bank %, Zoom multiplier])
Draws ship model as if in techroom
Returns: Whether ship was rendered

boolean renderTechModel2(X1, Y1, X2, Y2, orientation Orientation=null, [Zoom multiplier])
Draws ship model as if in techroom
Returns: Whether ship was rendered

boolean isModelLoaded([boolean Load = false])
Checks if the model used for this shipclass is loaded or not and optionally loads the model, which might be a slow operation.
Returns: If the model is loaded or not

number getShipClassIndex()
Gets the index valus of the ship class
Returns: index value of the ship class

===debris:object===
Debris handle

boolean IsHull = boolean
Whether or not debris is a piece of hull
Value: Whether debris is a hull fragment, or false if handle is invalid

shipclass OriginClass = shipclass
The shipclass of the ship this debris originates from
Value: The shipclass of the ship that created this debris

number getDebrisRadius()
The radius of this debris piece
Returns: The radius of this debris piece or -1 if invalid

boolean isValid()
Return if this debris handle is valid
Returns: true if valid false otherwise

===waypoint:object===
waypoint handle

===waypointlist===
waypointlist handle

waypoint [] number Index
Array of waypoints that are part of the waypoint list
Returns: Waypoint, or invalid handle if the index or waypointlist handle is invalid

number #
Number of waypoints in the list. Note that the value returned cannot be relied on for more than one frame.
Returns: Number of waypoints in the list, or 0 if handle is invalid

string Name = string
Name of WaypointList
Value: Waypointlist name, or empty string if handle is invalid

===weaponbank===
Ship/subystem weapons bank handle

weaponclass WeaponClass = weaponclass
Class of weapon mounted in the bank
Value: Weapon class, or an invalid weaponclass handle if bank handle is invalid

number AmmoLeft = number
Ammo left for the current bank
Value: Ammo left, or 0 if handle is invalid

number AmmoMax = number
Maximum ammo for the current bank
Value: Ammo capacity, or 0 if handle is invalid

boolean Armed = boolean
Weapon armed status. Does not take linking into account.
Value: True if armed, false if unarmed or handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===weaponbanktype===
Ship/subsystem weapons bank type handle

weaponbank [] number Index
Array of weapon banks
Returns: Weapon bank, or invalid handle on failure

boolean Linked = boolean
Whether bank is in linked or unlinked fire mode (Primary-only)
Value: Link status, or false if handle is invalid

boolean DualFire = boolean
Whether bank is in dual fire mode (Secondary-only)
Value: Dual fire status, or false if handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

number #
Number of weapons in the mounted bank
Returns: Number of bank weapons, or 0 if handle is invalid

===subsystem===
Ship subsystem handle

string (string)
Returns name of subsystem
Returns: Subsystem name, or empty string if handle is invalid

string ArmorClass = string
Current Armor class
Value: Armor class name, or empty string if none is set

number AWACSIntensity = number
Subsystem AWACS intensity
Value: AWACS intensity, or 0 if handle is invalid

number AWACSRadius = number
Subsystem AWACS radius
Value: AWACS radius, or 0 if handle is invalid

orientation Orientation = orientation
Orientation of subobject or turret base
Value: Subsystem orientation, or null orientation if handle is invalid

orientation GunOrientation = orientation
Orientation of turret gun
Value: Gun orientation, or null orientation if handle is invalid

number HitpointsLeft = number
Subsystem hitpoints left
Value: Hitpoints left, or 0 if handle is invalid. Setting a value of 0 will disable it - set a value of -1 or lower to actually blow it up.

number HitpointsMax = number
Subsystem hitpoints max
Value: Max hitpoints, or 0 if handle is invalid

vector Position = vector
Subsystem position with regards to main ship (Local Vector)
Value: Subsystem position, or null vector if subsystem handle is invalid

vector GunPosition = vector
Subsystem gun position with regards to main ship (Local vector)
Value: Gun position, or null vector if subsystem handle is invalid

string Name = string
Subsystem name
Value: Subsystem name, or an empty string if handle is invalid

string getModelName()
Returns the original name of the subsystem in the model file
Returns: name or empty string on error

weaponbanktype PrimaryBanks = weaponbanktype
Array of primary weapon banks
Value: Primary banks, or invalid weaponbanktype handle if subsystem handle is invalid

weaponbanktype SecondaryBanks = weaponbanktype
Array of secondary weapon banks
Value: Secondary banks, or invalid weaponbanktype handle if subsystem handle is invalid

object Target = object
Object targetted by this subsystem. If used to set a new target, AI targeting will be switched off.
Value: Targeted object, or invalid object handle if subsystem handle is invalid

boolean TurretResets = boolean
Specifies wether this turrets resets after a certain time of inactivity
Value: true if turret resets, false otherwise

number TurretResetDelay = number
The time (in milliseconds) after that the turret resets itself
Value: Reset delay

number TurnRate = number
The turn rate
Value: Turnrate or -1 on error

boolean TurretLocked = boolean
Whether the turret is locked. Setting to true locks the turret, setting to false frees it.
Value: True if turret is locked, false otherwise

number NextFireTimestamp = number
The next time the turret may attempt to fire
Value: Mission time (seconds) or -1 on error

boolean targetingOverride(boolean)
If set to true, AI targeting for this turret is switched off. If set to false, the AI will take over again.
Returns: Returns true if successful, false otherwise

boolean hasFired()
Determine if a subsystem has fired
Returns: true if if fired, false if not fired, or nil if invalid. resets fired flag when called.

boolean isTurret()
Determines if this subsystem is a turret
Returns: true if subsystem is turret, false otherwise or nil on error

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

nil fireWeapon([Turret weapon index = 1, Flak range = 100])
Fires weapon on turret
Returns: Nothing

boolean rotateTurret(vector Pos[, boolean reset=false)
Rotates the turret to face Pos or resets the turret to its original state
Returns: true on success false otherwise

vector getTurretHeading()
Returns the turrets forward vector
Returns: Returns a normalized version of the forward vector or null vector on error

number, number, number getFOVs()
Returns current turrets FOVs
Returns: Standard FOV, maximum barrel elevation, turret base fov.

matrix getTurretMatrix()
Returns current subsystems turret matrix
Returns: Turret matrix.

===shiptextures===
Ship textures handle

number #
Number of textures on ship
Returns: Number of textures on ship, or 0 if handle is invalid

texture [] number Index/string TextureFilename
Array of ship textures
Returns: Texture, or invalid texture handle on failure

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===ship:object===
Ship handle

subsystem [] string Name/number Index
Array of ship subsystems
Returns: Subsystem handle, or invalid subsystem handle if index or ship handle is invalid

number #
Number of subsystems on ship
Returns: Subsystem number, or 0 if handle is invalid

string ShieldArmorClass = string
Current Armor class of the ships' shield
Value: Armor class name, or empty string if none is set

string ArmorClass = string
Current Armor class
Value: Armor class name, or empty string if none is set

string Name = string
Ship name
Value: Ship name, or empty string if handle is invalid

number AfterburnerFuelLeft = number
Afterburner fuel left
Value: Afterburner fuel left, or 0 if handle is invalid

number AfterburnerFuelMax = number
Afterburner fuel capacity
Value: Afterburner fuel capacity, or 0 if handle is invalid

shipclass Class = shipclass
Ship class
Value: Ship class, or invalid shipclass handle if ship handle is invalid

number CountermeasuresLeft = number
Number of countermeasures left
Value: Countermeasures left, or 0 if ship handle is invalid

weaponclass CountermeasureClass = weaponclass
Weapon class mounted on this ship's countermeasure point
Value: Countermeasure hardpoint weapon class, or invalid weaponclass handle if no countermeasure class or ship handle is invalid

number HitpointsMax = number
Total hitpoints
Value: Ship maximum hitpoints, or 0 if handle is invalid

number WeaponEnergyLeft = number
Current weapon energy reserves
Value: Ship current weapon energy reserve level, or 0 if invalid

number WeaponEnergyMax = number
Maximum weapon energy
Value: Ship maximum weapon energy reserve level, or 0 if invalid

boolean PrimaryTriggerDown = boolean
Determines if primary trigger is pressed or not
Value: True if pressed, false if not, nil if ship handle is invalid

weaponbanktype PrimaryBanks = weaponbanktype
Array of primary weapon banks
Value: Primary weapon banks, or invalid weaponbanktype handle if ship handle is invalid

weaponbanktype SecondaryBanks = weaponbanktype
Array of secondary weapon banks
Value: Secondary weapon banks, or invalid weaponbanktype handle if ship handle is invalid

weaponbanktype TertiaryBanks = weaponbanktype
Array of tertiary weapon banks
Value: Tertiary weapon banks, or invalid weaponbanktype handle if ship handle is invalid

object Target = object
Target of ship. Value may also be a deriviative of the 'object' class, such as 'ship'.
Value: Target object, or invalid object handle if no target or ship handle is invalid

subsystem TargetSubsystem = subsystem
Target subsystem of ship.
Value: Target subsystem, or invalid subsystem handle if no target or ship handle is invalid

team Team = team
Ship's team
Value: Ship team, or invalid team handle if ship handle is invalid

shiptextures Textures = shiptextures
Gets ship textures
Value: Ship textures, or invalid shiptextures handle if ship handle is invalid

boolean FlagAffectedByGravity = boolean
Checks for the "affected-by-gravity" flag
Value: True if flag is set, false if flag is not set and nil on error

boolean Disabled = boolean
The disabled state of this ship
Value: true if ship is diabled, false otherwise

boolean kill([object Killer])
Kills the ship. Set "Killer" to the ship you are killing to self-destruct
Returns: True if successful, false or nil otherwise

boolean addShipEffect(string name, int duration (in milliseconds))
Activates an effect for this ship. Effect names are defined in Post_processing.tbl, and need to be implemented in the main shader. This functions analogous to the ship-effect sexp. NOTE: only one effect can be active at any time, adding new effects will override effects already in progress.
Returns: Returns true if the effect was successfully added, false otherwise

number hasShipExploded()
Checks if the ship explosion event has already happened
Returns: Returns 1 if first explosion timestamp is passed, 2 if second is passed, 0 otherwise

boolean fireCountermeasure()
Launches a countermeasure from the ship
Returns: Whether countermeasure was launched or not

number firePrimary()
Fires ship primary bank(s)
Returns: Number of primary banks fired

number fireSecondary()
Fires ship secondary bank(s)
Returns: Number of secondary banks fired

number getAnimationDoneTime(number Type, number Subtype)
Gets time that animation will be done
Returns: Time (seconds), or 0 if ship handle is invalid

boolean clearOrders()
Clears a ship's orders list
Returns: True if successful, otherwise false or nil

boolean giveOrder(enumeration Order, [object Target=nil, subsystem TargetSubsystem=nil, number Priority=1.0])
Uses the goal code to execute orders
Returns: True if order was given, otherwise false or nil

boolean doManeuver(number Duration, number Heading, number Pitch, number Bank, boolean Force Rotation, number Vertical, number Horizontal, number Forward, boolean Force Movement)
Sets ship maneuver over the defined time period
Returns: True if maneuver order was given, otherwise false or nil

boolean triggerAnimation(string Type, [number Subtype, boolean Forwards])
Triggers an animation. Type is the string name of the animation type, Subtype is the subtype number, such as weapon bank #, and Forwards is boolean.
IMPORTANT: Function is in testing and should not be used with official mod releases
Returns: True if successful, false or nil otherwise

boolean warpIn()
Warps ship in
Returns: True if successful, or nil if ship handle is invalid

boolean warpOut()
Warps ship out
Returns: True if successful, or nil if ship handle is invalid

boolean isWarpingIn()
Checks if ship is warping in
Returns: True if the ship is warping in, false or nil otherwise

number getEMP()
Returns the current emp effect strength acting on the object
Returns: Current EMP effect strength or NIL if object is invalid

number getTimeUntilExplosion()
Returns the time in seconds until the ship explodes
Returns: Time until explosion or -1, if invalid handle or ship isn't exploding

===weapon:object===
Weapon handle

weaponclass Class = weaponclass
Weapon's class
Value: Weapon class, or invalid weaponclass handle if weapon handle is invalid

boolean DestroyedByWeapon = boolean
Whether weapon was destroyed by another weapon
Value: True if weapon was destroyed by another weapon, false if weapon was destroyed by another object or if weapon handle is invalid

number LifeLeft = number
Weapon life left (in seconds)
Value: Life left (seconds) or 0 if weapon handle is invalid

number FlakDetonationRange = number
Range at which flak will detonate (meters)
Value: Detonation range (meters) or 0 if weapon handle is invalid

object Target = object
Target of weapon. Value may also be a deriviative of the 'object' class, such as 'ship'.
Value: Weapon target, or invalid object handle if weapon handle is invalid

subsystem ParentTurret = subsystem
Turret which fired this weapon.
Value: Turret subsystem handle, or an invalid handle if the weapon not fired from a turret

object HomingObject = object
Object that weapon will home in on. Value may also be a deriviative of the 'object' class, such as 'ship'
Value: Object that weapon is homing in on, or an invalid object handle if weapon is not homing or the weapon handle is invalid

vector HomingPosition = vector
Position that weapon will home in on (World vector)
Value: Homing point, or null vector if weapon handle is invalid

subsystem HomingSubsystem = subsystem
Subsystem that weapon will home in on.
Value: Homing subsystem, or invalid subsystem handle if weapon is not homing or weapon handle is invalid

team Team = team
Weapon's team
Value: Weapon team, or invalid team handle if weapon handle is invalid

boolean isArmed([boolean Hit target])
Checks if the weapon is armed.
Returns: boolean value of the weapon arming status

collision info getCollisionInformation()
Returns the collision information for this weapon
Returns: The collision information or invalid handle if none

===beam:object===
Beam handle

weaponclass Class = weaponclass
Weapon's class
Value: Weapon class, or invalid weaponclass handle if beam handle is invalid

vector LastShot = vector
End point of the beam
Value: vector or null vector if beam handle is not valid

vector LastStart = vector
Start point of the beam
Value: vector or null vector if beam handle is not valid

object Target = object
Target of beam. Value may also be a deriviative of the 'object' class, such as 'ship'.
Value: Beam target, or invalid object handle if beam handle is invalid

subsystem TargetSubsystem = subsystem
Subsystem that beam is targeting.
Value: Target subsystem, or invalid subsystem handle if beam handle is invalid

object ParentShip = object
Parent of the beam.
Value: Beam parent, or invalid object handle if beam handle is invalid

subsystem ParentSubsystem = subsystem
Subsystem that beam is fired from.
Value: Parent subsystem, or invalid subsystem handle if beam handle is invalid

number getCollisionCount()
Get the number of collisions in frame.
Returns: Number of beam collisions

vector getCollisionPosition(number)
Get the position of the defined collision.
Returns: World vector

collision info getCollisionInformation(number)
Get the collision information of the specified collision
Returns: handle to information or invalid handle on error

object getCollisionObject(number)
Get the target of the defined collision.
Returns: Object the beam collided with

boolean isExitCollision(number)
Checks if the defined collision was exit collision.
Returns: True if the collision was exit collision, false if entry, nil otherwise

vector getStartDirectionInfo()
Gets the start information about the direction. The vector is a normalized vector from LastStart showing the start direction of a slashing beam
Returns: The start direction or null vector if invalid

vector getEndDirectionInfo()
Gets the end information about the direction. The vector is a normalized vector from LastStart showing the end direction of a slashing beam
Returns: The start direction or null vector if invalid

===wing===
Wing handle

ship [] number Index
Array of ships in the wing
Returns: Ship handle, or invalid ship handle if index is invawing handle is invalid

number #
Number of wings in mission
Returns: Number of wings in mission

===player===
Player handle

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

string getName()
Gets current player name
Returns: Player name, or empty string if handle is invalid

string getCampaignFilename()
Gets current player campaign filename
Returns: Campaign name, or empty string if handle is invalid

string getImageFilename()
Gets current player image filename
Returns: Player image filename, or empty string if handle is invalid

number getMainHall()
Gets player's main hall number
Returns: Main hall index, or 1 if handle is invalid

string getSquadronName()
Gets current player squad name
Returns: Squadron name, or empty string if handle is invalid

===camera===
Camera handle

string (string)
Camera name
Returns: Camera name, or an empty string if handle is invalid

boolean isValid()
True if valid, false or nil if not
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

string Name = string
New camera name
Value: Camera name

number FOV = number
New camera FOV (in radians)
Value: Camera FOV (in radians)

orientation Orientation = orientation
New camera orientation
Value: Camera orientation

vector Position = vector
New camera position
Value: Camera position

object Self = object
New mount object
Value: Camera object

subsystem SelfSubsystem = subsystem
New mount object subsystem
Value: Subsystem that the camera is mounted on

object Target = object
New target object
Value: Camera target object

subsystem TargetSubsystem = subsystem
New target subsystem
Value: Subsystem that the camera is pointed at

boolean setFOV([number FOV, number Zoom Time, number Zoom Acceleration Time, number Zoom deceleration Time])
Sets camera FOV
FOV is the final field of view, in radians, of the camera.
Zoom Time is the total time to take zooming in or out.
Acceleration Time is the total time it should take the camera to get up to full zoom speed.
Deceleration Time is the total time it should take the camera to slow down from full zoom speed.
Returns: true if successful, false or nil otherwise

boolean setOrientation([world orientation Orientation, number Rotation Time, number Acceleration Time, number Deceleration time])
Sets camera orientation and velocity data.
Orientation is the final orientation for the camera, after it has finished moving. If not specified, the camera will simply stop at its current orientation.
Rotation time is how long total, including acceleration, the camera should take to rotate. If it is not specified, the camera will jump to the specified orientation.
Acceleration time is how long it should take the camera to get 'up to speed'. If not specified, the camera will instantly start moving.
Deceleration time is how long it should take the camera to slow down. If not specified, the camera will instantly stop moving.
Returns: true if successful, false or nil otherwise

boolean setPosition([wvector Position, number Translation Time, number Acceleration Time, number Deceleration Time])
Sets camera position and velocity data.
Position is the final position for the camera. If not specified, the camera will simply stop at its current position.
Translation time is how long total, including acceleration, the camera should take to move. If it is not specified, the camera will jump to the specified position.
Acceleration time is how long it should take the camera to get 'up to speed'. If not specified, the camera will instantly start moving.
Deceleration time is how long it should take the camera to slow down. If not specified, the camera will instantly stop moving.
Returns: true if successful, false or nil otherwise

===soundentry===
sounds.tbl table entry handle

number DefaultVolume = number
The default volume of this game sound
Value: Volume in the range from 1 to 0 or -1 on error

string getFilename()
Returns the filename of this sound
Returns: filename or empty string on error

number getDuration()
Gives the length of the sound in seconds.
Returns: the length, or -1 on error

number, number get3DValues(vector Postion[, number radius=0.0])
Computes the volume and the panning of the sound when it would be played from the specified position.
If range is given then the volume will diminish when the listener is withing that distance to the source.
The position of the listener is always the the current viewing position.
Returns: The volume and the panning, in that sequence, or both -1 on error

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===sound===
sound instance handle

number Pitch = number
Pitch of sound, from 100 to 100000
Value: Pitch, or 0 if handle is invalid

number getRemainingTime()
The remaining time of this sound handle
Returns: Remaining time, or -1 on error

boolean setVolume(number)
Sets the volume of this sound instance
Returns: true if succeeded, false otherwise

boolean setPanning(number)
Sets the panning of this sound. Argument ranges from -1 for left to 1 for right
Returns: true if succeeded, false otherwise

boolean setPosition(number[,boolean = true])
Sets the absolute position of the sound. If boolean argument is true then the value is given as a percentage
Returns: true if successfull, false otherwise

boolean rewind(number)
Rewinds the sound by the given number of seconds
Returns: true if succeeded, false otherwise

boolean skip(number)
Skips the given number of seconds of the sound
Returns: true if succeeded, false otherwise

boolean isPlaying()
Specifies if this handle is currently playing
Returns: true if playing, false if otherwise

boolean stop()
Stops the sound of this handle
Returns: true if succeeded, false otherwise

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

===3Dsound:sound===
3D sound instance handle

boolean updatePosition(vector Position[, number radius = 0.0])
Updates the given 3D sound with the specified position and an optional range value
Returns: true if succeesed, false otherwise

===control info===
control info handle

number Pitch = number
Pitch of the player ship
Value: Pitch

number Heading = number
Heading of the player ship
Value: Heading

number Bank = number
Bank of the player ship
Value: Bank

number Vertical = number
Vertical control of the player ship
Value: Vertical control

number Sideways = number
Sideways control of the player ship
Value: Sideways control

number Forward = number
Forward control of the player ship
Value: Forward

number ForwardCruise = number
Forward control of the player ship
Value: Forward

number PrimaryCount = number
Number of primary weapons that will fire
Value: Number of weapons to fire, or 0 if handle is invalid

number SecondaryCount = number
Number of secondary weapons that will fire
Value: Number of weapons to fire, or 0 if handle is invalid

number CountermeasureCount = number
Number of countermeasures that will launch
Value: Number of countermeasures to launch, or 0 if handle is invalid

nil clearLuaButtonInfo()
Clears the lua button control info
Returns: Nothing

number, number, number,number getButtonInfo()
Access the four bitfields containing the button info
Returns: Four bitfields

number, number, number,number accessButtonInfo(number, number, number, number)
Access the four bitfields containing the button info
Returns: Four bitfields

nil useButtonControl(number, string)
Adds the defined button control to lua button control data, if number is -1 it tries to use the string
Returns: Nothing

string getButtonControlName(number)
Gives the name of the command corresponding with the given number
Returns: Name of the command

number getButtonControlNumber(string)
Gives the number of the command corresponding with the given string
Returns: Number of the command

boolean AllButtonPolling = boolean
Toggles the all button polling for lua
Value: If the all button polling is enabled or not

number, number, number,number pollAllButtons()
Access the four bitfields containing the button info
Returns: Four bitfields

===particle===
Handle to a particle

vector Position = vector
The current position of the particle (world vector)
Value: The current position

vector Velocity = vector
The current velocity of the particle (world vector)
Value: The current velocity

number Age = number
The time this particle already lives
Value: The current age or -1 on error

number MaximumLife = number
The time this particle can live
Value: The maximal life or -1 on error

number Radius = number
The radius of the particle
Value: The radius or -1 on error

number TracerLength = number
The tracer legth of the particle
Value: The radius or -1 on error

object AttachedObject = object
The object this particle is attached to. If valid the position will be relativ to this object and the velocity will be ignored.
Value: Attached object or invalid object handle on error

boolean isValid()
Detects whether this handle is valid
Returns: true if valid false if not

==Libraries==
===Audio (ad)===
Sound/Music Library

soundentry getSoundentry(string/number)
Return a sound entry matching the specified index or name. If you are using a number then the first valid index is 1
Returns: soundentry or invalid handle on error

sound playSound(soundentry)
Plays the specified sound entry handle
Returns: A handle to the playing sound

sound playLoopingSound(soundentry)
Plays the specified sound as a looping sound
Returns: A handle to the playing sound or invalid handle if playback failed

3Dsound play3DSound(soundentry[, vector source[, vector listener]])
Plays the specified sound entry handle. Source if by default 0, 0, 0 and listener is by default the current viewposition
Returns: A handle to the playing sound

boolean playGameSound(Sound index, [Panning (-1.0 left to 1.0 right), Volume %, Priority 0-3, Voice Message?])
Plays a sound from #Game Sounds in sounds.tbl. A priority of 0 indicates that the song must play; 1-3 will specify the maximum number of that sound that can be played
Returns: True if sound was played, false if not (Replaced with a sound instance object in the future)

boolean playInterfaceSound(Sound index)
Plays a sound from #Interface Sounds in sounds.tbl
Returns: True if sound was played, false if not

number playMusic(string Filename, [float volume = 1.0, bool looping = true])
Plays a music file using FS2Open's builtin music system. Volume should be in the 0.0 - 1.0 range, and is capped at 1.0. Files passed to this function are looped by default.
Returns: Audiohandle of the created audiostream, or -1 on failure

nil stopMusic(int audiohandle, [bool fade = false])
Stops a playing music file, provided audiohandle is valid
Returns: Nothing

===Base (ba)===
Base FreeSpace 2 functions

nil print(string Message)
Prints a string
Returns: Nothing

nil warning(string Message)
Displays a FreeSpace warning (debug build-only) message with the string provided
Returns: Nothing

nil error(string Message)
Displays a FreeSpace error message with the string provided
Returns: Nothing

orientation createOrientation([p/r1c1, b/r1c2, h/r1c3, r2c1, r2c2, r2c3, r3c1, r3c2, r3c3])
Given 0, 3, or 9 arguments, creates an orientation object with that orientation.
Returns: New orientation object, or null orientation on failure

vector createVector([x, y, z])
Creates a vector object
Returns: Vector object

number getFrametime([Do not adjust for time compression (Boolean)])
Gets how long this frame is calculated to take. Use it to for animations, physics, etc to make incremental changes.
Returns: Frame time (seconds)

state getCurrentGameState([Depth (number)])
Gets current FreeSpace state; if a depth is specified, the state at that depth is returned. (IE at the in-game options game, a depth of 1 would give you the game state, while the function defaults to 0, which would be the options screen.
Returns: Current game state at specified depth, or invalid handle if no game state is active yet

string getCurrentMPStatus(NIL)
Gets this computers current MP status
Returns: Current MP status

string setControlMode(NIL or enumeration LE_*_CONTROL)
Sets the current control mode for the game.
Returns: Current control mode

string setButtonControlMode(NIL or enumeration LE_*_BUTTON_CONTROL)
Sets the current control mode for the game.
Returns: Current control mode

control info getControlInfo()
Gets the control info handle.
Returns: control info handle

boolean postGameEvent(gameevent Event)
Sets current game event. Note that you can crash FreeSpace 2 by posting an event at an improper time, so test extensively if you use it.
Returns: True if event was posted, false if passed event was invalid

gameevent GameEvents[] number Index/string Name
Array of game events
Returns: Game event, or invalid gameevent handle if index is invalid

number #
Number of events
Returns: Number of events

gamestate GameStates[] number Index/string Name
Array of game states
Returns: Game state, or invalid gamestate handle if index is invalid

number #
Number of states
Returns: Number of states

===CFile (cf)===
CFile FS2 filesystem access

boolean deleteFile(string Filename, string Path)
Deletes given file. Path must be specified. Use a slash for the root directory.
Returns: True if deleted, false

boolean fileExists(string Filename, [string Path = "", boolean CheckVPs = false])
Checks if a file exists. Use a blank string for path for any directory, or a slash for the root directory.
Returns: True if file exists, false or nil otherwise

file openFile(string Filename, [string Mode="r", string Path = ""])
Opens a file. 'Mode' uses standard C fopen arguments. Use a blank string for path for any directory, or a slash for the root directory.Be EXTREMELY CAREFUL when using this function, as you may PERMANENTLY delete any file by accident
Returns: File handle, or invalid file handle if the specified file couldn't be opened

file openTempFile()
Opens a temp file that is automatically deleted when closed
Returns: File handle, or invalid file handle if tempfile couldn't be created

boolean renameFile(string CurrentFilename, string NewFilename, string Path)
Renames given file. Path must be specified. Use a slash for the root directory.
Returns: True if file was renamed, otherwise false

===Controls (io)===
Controls library

number getMouseX()
Gets Mouse X pos
Returns: Mouse x position, or 0 if mouse is not initialized yet

number getMouseY()
Gets Mouse Y pos
Returns: Mouse y position, or 0 if mouse is not initialized yet

boolean isMouseButtonDown({MOUSE_*_BUTTON enumeration}, [..., ...])
Returns whether the specified mouse buttons are up or down
Returns: Whether specified mouse buttons are down, or false if mouse is not initialized yet

nil setCursorImage(Image filename, [LOCK or UNLOCK])
Sets mouse cursor image, and allows you to lock/unlock the image. (A locked cursor may only be changed with the unlock parameter)
Returns: Nothing

nil setCursorHidden(True to hide mouse, false to show it)
Shows or hides mouse cursor
Returns: Nothing

boolean forceMousePosition(number, number (coordinates))
function to force mouse position
Returns: if the operation succeeded or not

boolean MouseControlStatus = boolean
Gets and sets the retail mouse control status
Value: if the retail mouse is on or off

boolean updateTrackIR()
Updates Tracking Data. Call before using get functions
Returns: Checks if trackir is available and updates variables, returns true if successful, otherwise false

number getTrackIRPitch()
Gets pitch axis from last update
Returns: Pitch value -1 to 1, or 0 on failure

number getTrackIRYaw()
Gets yaw axis from last update
Returns: Yaw value -1 to 1, or 0 on failure

number getTrackIRRoll()
Gets roll axis from last update
Returns: Roll value -1 to 1, or 0 on failure

number getTrackIRX()
Gets x position from last update
Returns: X value -1 to 1, or 0 on failure

number getTrackIRY()
Gets y position from last update
Returns: Y value -1 to 1, or 0 on failure

number getTrackIRZ()
Gets z position from last update
Returns: Z value -1 to 1, or 0 on failure

===HUD (hu)===
HUD library

boolean HUDDrawn = boolean
Current HUD draw status
Value: If the HUD is drawn or not

boolean setHUDGaugeColor(number (index number of the gauge), [number red, number green, number blue, number alpha])
Color used to draw the gauge
Returns: If the operation was successful

number, number, number, number getHUDGaugeColor(number (index number of the gauge))
Color used to draw the gauge
Returns: Red, green, blue, and alpha of the gauge

HudGauge getHUDGaugeHandle(string Name)
Returns a handle to a specified HUD gauge
Returns: HUD Gauge handle, or nil if invalid

===Graphics (gr)===
Graphics Library

camera Cameras[] number Index/string Name
Gets camera
Returns: Ship handle, or invalid ship handle if index was invalid

number #
Gets number of cameras
Returns: Number of cameras

font Fonts[] number Index/string Filename
Array of loaded fonts
Returns: Font handle, or invalid font handle if index is invalid

number #
Number of loaded fonts
Returns: Number of loaded fonts

font CurrentFont = font
Current font
Value: (null)

enumeration CurrentOpacityType = enumeration
Current alpha blending type; uses ALPHABLEND_* enumerations
Value: (null)

texture CurrentRenderTarget = texture
Current rendering target
Value: Current rendering target, or invalid texture handle if screen is render target

nil clearScreen([number Red, number green, number blue, number alpha])
Clears the screen to black, or the color specified.
Returns: Nothing

camera createCamera(string Name, [wvector Position, orientation Orientation])
Creates a new camera using the specified position and orientation (World)
Returns: Camera handle, or invalid camera handle if camera couldn't be created

number getScreenWidth()
Gets screen width
Returns: Width in pixels, or 0 if graphics are not initialized yet

number getScreenHeight()
Gets screen height
Returns: Height in pixels, or 0 if graphics are not initialized yet

vector getVectorFromCoords([number X=center, number Y=center, number Depth, boolean normalize = false])
Returns a vector through screen coordinates x and y. If depth is specified, vector is extended to Depth units into spaceIf normalize is true, vector will be normalized.
Returns: Vector, or zero vector on failure

boolean setTarget([texture Texture])
If texture is specified, sets current rendering surface to a texture.Otherwise, sets rendering surface back to screen.
Returns: True if successful, false otherwise

boolean setCamera([camera handle Camera])
Sets current camera, or resets camera if none specified
Returns: true if successful, false or nil otherwise

nil setColor(number Red, number Green, number Blue, [number Alpha])
Sets 2D drawing color; each color number should be from 0 (darkest) to 255 (brightest)
Returns: Nothing

nil drawCircle(number Radius, number X, number Y)
Draws a circle
Returns: Nothing

nil drawCurve(number X, number Y, number Radius)
Draws a curve
Returns: Nothing

nil drawGradientLine(number X1, number Y1, number X2, number Y2)
Draws a line from (x1,y1) to (x2,y2) with the CurrentColor that steadily fades out
Returns: Nothing

nil drawLine(number X1, number Y1, number X2, number Y2)
Draws a line from (x1,y1) to (x2,y2) with CurrentColor
Returns: Nothing

nil drawPixel(number X, number Y)
Sets pixel to CurrentColor
Returns: Nothing

nil drawPolygon(texture Texture, [vector Position={0,0,0}, orientation Orientation=null, number Width=1.0, number Height=1.0])
Draws a polygon
Returns: Nothing

nil drawRectangle(number X1, number Y1, number X2, number Y2, [boolean Filled=true])
Draws a rectangle with CurrentColor
Returns: Nothing

boolean drawSphere([number Radius = 1.0, vector Position])
Draws a sphere with radius Radius at world vector Position
Returns: True if successful, false or nil otherwise

int drawModel(model, position, orientation)
Draws the given model with the specified position and orientation - Use with extreme care, may not work properly in all scripting hooks.
Returns: Zero if successful, otherwise an integer error code

int drawModelOOR(model Model, vector Position, matrix Orientation, integer Flags)
Draws the given model with the specified position and orientation - Use with extreme care, designer to operate properly only in On Object Render hook.
Returns: Zero if successful, otherwise an integer error code

number,number,number,number drawTargetingBrackets(object Object, [boolean draw=true, int padding=5])
Gets the edge positions of targeting brackets for the specified object. The brackets will only be drawn if draw is true or the default value of draw is used. Brackets are drawn with the current color. The brackets will have a padding (distance from the actual bounding box); the default value (used elsewhere in FS2) is 5.
Returns: Left, top, right, and bottom positions of the brackets, or nil if invalid

number drawString(string Message, [number X1, number Y1, number X2, number Y2])
Draws a string. Use x1/y1 to control position, x2/y2 to limit textbox size.Text will automatically move onto new lines, if x2/y2 is specified.Additionally, calling drawString with only a string argument will automaticallydraw that string below the previously drawn string (or 0,0 if no stringshave been drawn yet
Returns: Number of lines drawn, or 0 on failure

number getStringWidth(string String)
Gets string width
Returns: String width, or 0 on failure

texture createTexture([number Width=512, number Height=512, enumeration Type=TEXTURE_DYNAMIC])
Creates a texture for rendering to.Types are TEXTURE_STATIC - for infrequent rendering - and TEXTURE_DYNAMIC - for frequent rendering.
Returns: New texture handle, or invalid texture handle if texture couldn't be created

texture loadTexture(string Filename, [boolean LoadIfAnimation, boolean NoDropFrames])
Gets a handle to a texture. If second argument is set to true, animations will also be loaded.If third argument is set to true, every other animation frame will not be loaded if system has less than 48 MB memory.
IMPORTANT: Textures will not be unload themselves unless you explicitly tell them to do so.When you are done with a texture, call the Unload() function to free up memory.
Returns: Texture handle, or invalid texture handle if texture couldn't be loaded

boolean drawImage(string Filename/texture Texture, [number X1=0, Y1=0, number X2, number Y2, number UVX1 = 0.0, number UVY1 = 0.0, number UVX2=1.0, number UVY2=1.0, number alpha=1.0])
Draws an image or texture. Any image extension passed will be ignored.The UV variables specify the UV value for each corner of the image. In UV coordinates, (0,0) is the top left of the image; (1,1) is the lower right.
Returns: Whether image was drawn

boolean drawMonochromeImage(string Filename/texture Texture, number X1, number Y1, [number X2, number Y2, number alpha=1.0])
Draws a monochrome image using the current color
Returns: Whether image was drawn

number getImageWidth(string Filename)
Gets image width
Returns: Image width, or 0 if filename is invalid

number getImageHeight(Image name)
Gets image height
Returns: Image height, or 0 if filename is invalid

nil flashScreen(number Red, number Green, number Blue)
Flashes the screen
Returns: Nothing

model loadModel(string Filename)
Loads the model - will not setup subsystem data, DO NOT USE FOR LOADING SHIP MODELS
Returns: Handle to a model

boolean hasViewmode(enumeration)
Specifies if the current viemode has the specified flag, see VM_* enumeration
Returns: true if flag is present, false otherwise

===HookVariables (hv)===
Hook variables repository

string Globals[] number Index
Array of current HookVariable names
Returns: Hookvariable name, or empty string if invalid index specified

number #
Number of HookVariables
Returns: Number of HookVariables

===Mission (mn)===
Mission library

object getObjectFromSignature(number Signature)
Gets a handle of an object from its signature
Returns: Handle of object with signaure, invalid handle if signature is not in use

boolean evaluateSEXP(string)
Runs the defined SEXP script
Returns: if the operation was successful

boolean runSEXP(string)
Runs the defined SEXP script
Returns: if the operation was successful

asteroid Asteroids[] number Index
Gets asteroid
Returns: Asteroid handle, or invalid handle if invalid index specified

number #
Number of asteroids in mission. Note that the value returned is only good until an asteroid is destroyed, and so cannot be relied on for more than one frame.
Returns: Number of asteroids in the mission, or 0 if asteroids are not enabled

debris Debris[] number Index
Array of debris in the current mission
Returns: Debris handle, or invalid debris handle if index wasn't valid

number #
Number of debris pieces in the mission. Note that the value returned is only good until a piece of debris is destroyed, and so cannot be relied on for more than one frame.
Returns: Current number of debris particles

ship EscortShips[] number Index
Gets escort ship at specified index on escort list
Returns: Specified ship, or invalid ship handle if invalid index

number #
Current number of escort ships
Returns: Current number of escort ships

event Events[] number Index/string Name
Indexes events list
Returns: Event handle, or invalid event handle if index was invalid

number #
Number of events in mission
Returns: Number of events in mission

sexpvariable SEXPVariables[] number Index/string Name
Array of SEXP variables. Note that you can set a sexp variable using the array, eg 'SEXPVariables[1] = "newvalue"'
Returns: Handle to SEXP variable, or invalid sexpvariable handle if index was invalid

number #
Current number of SEXP variables
Returns: Counts number of loaded SEXP Variables. May be slow.

ship Ships[] number Index/string Name
Gets ship
Returns: Ship handle, or invalid ship handle if index was invalid

number #
Number of ships in the mission. This function is somewhat slow, and should be set to a variable for use in looping situations. Note that the value returned is only good until a ship is destroyed, and so cannot be relied on for more than one frame.
Returns: Number of ships in the mission, or 0 if ships haven't been initialized yet

waypoint Waypoints[] number Index
Array of waypoints in the current mission
Returns: Waypoint handle, or invalid waypoint handle if index was invalid

number #
Gets number of waypoints in mission. Note that this is only accurate for one frame.
Returns: Number of waypoints in the mission

waypointlist WaypointLists[] number Index/string WaypointListName
Array of waypoint lists
Returns: Gets waypointlist handle

number #
Number of waypoint lists in mission. Note that this is only accurate for one frame.
Returns: Number of waypoint lists in the mission

weapon Weapons[] number Index
Gets handle to a weapon object in the mission.
Returns: Weapon handle, or invalid weapon handle if index is invalid

number #
Number of weapon objects in mission. Note that this is only accurate for one frame.
Returns: Number of weapon objects in mission

beam Beams[] number Index
Gets handle to a beam object in the mission.
Returns: Beam handle, or invalid beam handle if index is invalid

number #
Number of beam objects in mission. Note that this is only accurate for one frame.
Returns: Number of beam objects in mission

wing Wings[] number Index/string WingName
Wings in the mission
Returns: Wing handle, or invalid wing handle if index or name was invalid

number #
Number of wings in mission
Returns: Number of wings in mission

ship createShip([string Name, shipclass Class=Shipclass[1], orientation Orientation=null, vector Position={0,0,0}])
Creates a ship and returns a handle to it using the specified name, class, world orientation, and world position
Returns: Ship handle, or invalid ship handle if ship couldn't be created

waypoint createWaypoint([vector Position, waypointlist List])
Creates a waypoint
Returns: Waypoint handle, or invalid waypoint handle if waypoint couldn't be created

weapon createWeapon([weaponclass Class=WeaponClass[1], orientation Orientation=null, world vector Position={0,0,0}, object Parent = nil, number Group = -1)
Creates a weapon and returns a handle to it. 'Group' is used for lighting grouping purposes; for example, quad lasers would only need to act as one light source.
Returns: Weapon handle, or invalid weapon handle if weapon couldn't be created.

string getMissionFilename()
Gets mission filename
Returns: Mission filename, or empty string if game is not in a mission

boolean startMission([Filename or MISSION_* enumeration, Briefing = true])
Starts the defined mission
Returns: True, or false if the function fails

number getMissionTime()
Game time in seconds since the mission was started; is affected by time compression
Returns: Mission time (seconds), or 0 if game is not in a mission

boolean loadMission(Mission name)
Loads a mission
Returns: True if mission was loaded, otherwise false

nil unloadMission()
Stops the current mission and unloads it
Returns: Nothing

nil simulateFrame()
Simulates mission frame
Returns: Nothing

nil renderFrame()
Renders mission frame, but does not move anything
Returns: Nothing

===BitOps (bit)===
Bitwise Operations library

number AND(number, number)
Values for which bitwise boolean AND operation is performed
Returns: Result of the AND operation

number OR(number, number)
Values for which bitwise boolean OR operation is performed
Returns: Result of the OR operation

number XOR(number, number)
Values for which bitwise boolean XOR operation is performed
Returns: Result of the XOR operation

number toggleBit(number, number (bit))
Toggles the value of the set bit in the given number for 32 bit integer
Returns: Result of the operation

boolean checkBit(number, number (bit))
Checks the value of the set bit in the given number for 32 bit integer
Returns: Was the bit true of false

number addBit(number, number (bit))
Performs inclusive or (OR) operation on the set bit of the value
Returns: Result of the operation

===Tables (tb)===
Tables library

ship ShipClasses[] number Index/string Name
Array of ship classes
Returns: Ship handle, or invalid ship handle if index is invalid

number #
Number of ship classes
Returns: Number of ship classes, or 0 if ship classes haven't been loaded yet

weapon WeaponClasses[] number Index/string WeaponName
Array of weapon classes
Returns: Weapon class handle, or invalid weaponclass handle if index is invalid

number #
Number of weapon classes
Returns: Number of weapon classes, or 0 if weapon classes haven't been loaded yet

===Testing (ts)===
Experimental or testing stuff

nil avdTest()
Test the AVD Physics code
Returns: Nothing

particle createParticle(vector Position, vector Velocity, number Lifetime, number Radius, enumeration Type, [number Tracer length=-1, boolean Reverse=false, texture Texture=Nil, object Attached Object=Nil])
Creates a particle. Use PARTICLE_* enumerations for type.Reverse reverse animation, if one is specifiedAttached object specifies object that Position will be (and always be) relative to.
Returns: Handle to the created particle

string getStack()
Generates an ADE stackdump
Returns: Current Lua stack

boolean isCurrentPlayerMulti()
Returns whether current player is a multiplayer pilot or not.
Returns: Whether current player is a multiplayer pilot or not

boolean isPXOEnabled()
Returns whether PXO is currently enabled in the configuration.
Returns: Whether PXO is enabled or not

==Enumerations==
ALPHABLEND_FILTER
ALPHABLEND_NONE
CFILE_TYPE_NORMAL
CFILE_TYPE_MEMORY_MAPPED
MOUSE_LEFT_BUTTON
MOUSE_RIGHT_BUTTON
MOUSE_MIDDLE_BUTTON
ORDER_ATTACK
ORDER_ATTACK_ANY
ORDER_DEPART
ORDER_DISABLE
ORDER_DISARM
ORDER_DOCK
ORDER_EVADE
ORDER_FLY_TO
ORDER_FORM_ON_WING
ORDER_GUARD
ORDER_IGNORE_SHIP
ORDER_KEEP_SAFE_DISTANCE
ORDER_PLAY_DEAD
ORDER_REARM
ORDER_STAY_NEAR
ORDER_STAY_STILL
ORDER_UNDOCK
ORDER_WAYPOINTS
ORDER_WAYPOINTS_ONCE
PARTICLE_DEBUG
PARTICLE_BITMAP
PARTICLE_FIRE
PARTICLE_SMOKE
PARTICLE_SMOKE2
PARTICLE_PERSISTENT_BITMAP
SEXPVAR_CAMPAIGN_PERSISTENT
SEXPVAR_NOT_PERSISTENT
SEXPVAR_PLAYER_PERSISTENT
SEXPVAR_TYPE_NUMBER
SEXPVAR_TYPE_STRING
TEXTURE_STATIC
TEXTURE_DYNAMIC
LOCK
UNLOCK
NONE
SHIELD_FRONT
SHIELD_LEFT
SHIELD_RIGHT
SHIELD_BACK
MISSION_REPEAT
NORMAL_CONTROLS
LUA_STEERING_CONTROLS
LUA_FULL_CONTROLS
NORMAL_BUTTON_CONTROLS
LUA_ADDITIVE_BUTTON_CONTROL
LUA_OVERRIDE_BUTTON_CONTROL
VM_INTERNAL
VM_EXTERNAL
VM_TRACK
VM_DEAD_VIEW
VM_CHASE
VM_OTHER_SHIP
VM_EXTERNAL_CAMERA_LOCKED
VM_WARP_CHASE
VM_PADLOCK_UP
VM_PADLOCK_REAR
VM_PADLOCK_LEFT
VM_PADLOCK_RIGHT
VM_WARPIN_ANCHOR
VM_TOPDOWN
VM_FREECAMERA

Scripting functions

2012-07-13T12:47:53Z

Aginor: Added a complete scripting.html. Needs format changes and links. But it is ready for editing remarks in.

This page explains all the functions mentioned in the scripting.html file, including their syntax, remarks on their use and common errors modders may encounter when they use them.

----

Script Output - FSO v3.6.13 (FS2_Open Scripting)

Conditional Hooks

Conditions
State
Campaign
Mission
Object Type
Ship
Ship class
Ship type
Weapon class
KeyPress
Version
Application
Actions
On Game Init
On Splash Screen
On State Start
On Frame
On Key Pressed
On Key Released
On Mouse Moved
On Mouse Pressed
On Mouse Released
On State End
On Mission Start
On HUD Draw
On Ship Collision
On Weapon Collision
On Debris Collision
On Asteroid Collision
On Object Render
On Warp In
On Warp Out
On Death
On Mission End
On Weapon Delete
On Weapon Equipped
On Weapon Fired
On Weapon Selected
On Weapon Deselected
On Gameplay Start
On Turret Fired
On Primary Fire
On Secondary Fire

Scripting languages
Lua

Lua

Libraries
Audio (ad) - Sound/Music Library
Base (ba) - Base FreeSpace 2 functions
CFile (cf) - CFile FS2 filesystem access
Controls (io) - Controls library
HUD (hu) - HUD library
Graphics (gr) - Graphics Library
HookVariables (hv) - Hook variables repository
Mission (mn) - Mission library
BitOps (bit) - Bitwise Operations library
Tables (tb) - Tables library
Testing (ts) - Experimental or testing stuff
Types
vector - Vector object
orientation - Orientation matrix object
enumeration - Enumeration object
event - Mission event handle
file - File handle
font - font handle
gameevent - Game event
gamestate - Game state
HudGauge - HUD Gauge handle
eyepoint - Eyepoint handle
model - 3D Model (POF) handle
modeltextures_h - Array of materials
eyepoints - Array of model eye points
thrusters - The thrusters of a model
thrusterbank - A model thrusterbank
glowpoint - A model glowpoint
order - order handle
shiporders - Ship orders
physics - Physics handle
sexpvariable - SEXP Variable handle
shields - Shields handle
shiptype - Ship type handle
species - Species handle
team - Team handle
texture - Texture handle
material - Texture map, including diffuse, glow, and specular textures
weaponclass - Weapon class handle
collision info - Information about a collision
object - Object handle
asteroid - Asteroid handle
shipclass - Ship class handle
debris - Debris handle
waypoint - waypoint handle
waypointlist - waypointlist handle
weaponbank - Ship/subystem weapons bank handle
weaponbanktype - Ship/subsystem weapons bank type handle
subsystem - Ship subsystem handle
shiptextures - Ship textures handle
ship - Ship handle
weapon - Weapon handle
beam - Beam handle
wing - Wing handle
player - Player handle
camera - Camera handle
soundentry - sounds.tbl table entry handle
sound - sound instance handle
3Dsound - 3D sound instance handle
control info - control info handle
particle - Handle to a particle
Enumerations

vector
Vector object

number [] x,y,z or 1-3
Vector component
Returns: Value at index, or 0 if vector handle is invalid

vector + number/vector
Adds vector by another vector, or adds all axes by value
Returns: Final vector, or null vector if error occurs

vector - number/vector
Subtracts vector from another vector, or subtracts all axes by value
Returns: Final vector, or null vector if error occurs

vector * number/vector
Scales vector object (Multiplies all axes by number), or multiplies each axes by the other vector's axes.
Returns: Final vector, or null vector if error occurs

vector / number/vector
Scales vector object (Divide all axes by number), or divides each axes by the dividing vector's axes.
Returns: Final vector, or null vector if error occurs

string (string)
Converts a vector to string with format "(x,y,z)"
Returns: Vector as string, or empty string if handle is invalid

orientation getOrientation()
Returns orientation object representing the direction of the vector. Does not require vector to be normalized.
Returns: Orientation object, or null orientation object if handle is invalid

number getMagnitude()
Returns the magnitude of a vector (Total regardless of direction)
Returns: Magnitude of vector, or 0 if handle is invalid

number getDistance(Vector)
Distance
Returns: Returns distance from another vector

number getDotProduct(vector OtherVector)
Returns dot product of vector object with vector argument
Returns: Dot product, or 0 if a handle is invalid

vector getCrossProduct(vector OtherVector)
Returns cross product of vector object with vector argument
Returns: Cross product, or null vector if a handle is invalid

number,number getScreenCoords()
Gets screen cordinates of a world vector
Returns: X (number), Y (number), or false if off-screen

vector getNormalized()
Returns a normalized version of the vector
Returns: Normalized Vector, or NIL if invalid

orientation
Orientation matrix object

number [] p,b,h or 1-9
Orientation component - pitch, bank, heading, or index into 3x3 matrix (1-9)
Returns: Number at the specified index, or 0 if index is invalid.

orientation * orientation
Multiplies two matrix objects)
Returns: matrix, or empty matrix if unsuccessful

string (string)
Converts a matrix to a string with format "[r1c1 r2c1 r3c1 | r1c2 r2c2 r3c2| r1c3 r2c3 r3c3]"
Returns: Formatted string or "

orientation getInterpolated(orientation Final, number Factor)
Returns orientation that has been interpolated to Final by Factor (0.0-1.0)
Returns: Interpolated orientation, or null orientation on failure

orientation getTranspose()
Returns a transpose version of the specified orientation
Returns: Transpose matrix, or null orientation on failure

vector rotateVector(vector Input)
Returns rotated version of given vector
Returns: Rotated vector, or empty vector on error

vector unrotateVector(vector Input)
Returns unrotated version of given vector
Returns: Unrotated vector, or empty vector on error

enumeration
Enumeration object

enumeration = enumeration
Sets enumeration to specified value (if it is not a global
Returns: enumeration

string (string)
Returns enumeration name
Returns: Enumeration name, or "" if invalid

event
Mission event handle

string Name = string
Mission event name
Value: (null)

string DirectiveText = string
Directive text
Value: (null)

string DirectiveKeypressText = string
Raw directive keypress text, as seen in FRED.
Value: (null)

number Interval = number
Time for event to repeat (in seconds)
Value: Repeat time, or 0 if invalid handle

number ObjectCount = number
Number of objects left for event
Value: Repeat count, or 0 if invalid handle

number RepeatCount = number
Event repeat count
Value: Repeat count, or 0 if invalid handle

number Score = number
Event score
Value: Event score, or 0 if invalid handle

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

file
File handle

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

nil close()
Instantly closes file and invalidates all file handles
Returns: Nothing

boolean flush()
Flushes file buffer to disk.
Returns: True for success, false on failure

string getPath()
Determines path of the given file
Returns: Path string of the file handle, or an empty string if it doesn't have one, or the handle is invalid

number or string, ... read(number or string, ...)
Reads part of or all of a file, depending on arguments passed. Based on basic Lua file:read function.Returns nil when the end of the file is reached.

* "*n" - Reads a number.
* "*a" - Reads the rest of the file and returns it as a string.
* "*l" - Reads a line. Skips the end of line markers.
* (number) - Reads given number of characters, then returns them as a string.

Returns: Requested data, or nil if the function fails

number seek([string Whence="cur", number Offset=0])
# Changes position of file, or gets location.Whence can be:"set" - File start.
# "cur" - Current position in file.
# "end" - File end.
Returns: new offset, or false or nil on failure

number write(string or number, ...)
Writes a series of Lua strings or numbers to the current file.
Returns: Number of items successfully written.

font
font handle

string (string)
Filename of font
Returns: Font filename, or an empty string if the handle is invalid

string Filename = string
Filename of font (including extension)
Value: (null)

number Height = number
Height of font (in pixels)
Value: Font height, or 0 if the handle is invalid

boolean isValid()
True if valid, false or nil if not
Returns: Detects whether handle is valid

gameevent
Game event

string (string)
Game event name
Returns: Game event name, or empty string if handle is invalid

string Name = string
Game event name
Value: Game event name, or empty string if handle is invalid

gamestate
Game state

string (string)
Game state name
Returns: Game state name, or empty string if handle is invalid

string Name = string
Game state name
Value: Game state name, or empty string if handle is invalid

HudGauge
HUD Gauge handle

string Name = string
Custom HUD Gauge name
Value: Custom HUD Gauge name, or nil if handle is invalid

string Text = string
Custom HUD Gauge text
Value: Custom HUD Gauge text, or nil if handle is invalid

eyepoint
Eyepoint handle

vector Normal = vector
Eyepoint normal
Value: Eyepoint normal, or null vector if handle is invalid

vector Position = vector
Eyepoint location (Local vector)
Value: Eyepoint location, or null vector if handle is invalid

boolean IsValid()
Detect whether this handle is valid
Returns: true if valid false otherwise

model
3D Model (POF) handle

modeltextures_h Textures = modeltextures_h
Model textures
Value: Model textures, or an invalid modeltextures handle if the model handle is invalid

thrusters Thrusters = thrusters
Model thrusters
Value: Thrusters of the model or invalid handle

eyepoints Eyepoints = eyepoints
Model eyepoints
Value: Array of eyepoints or invalid handle on error

vector BoundingBoxMax = vector
Model bounding box maximum
Value: Model bounding box, or an empty vector if the handle is invalid

vector BoundingBoxMin = vector
Model bounding box minimum
Value: Model bounding box, or an empty vector if the handle is invalid

string Filename = string
Model filename
Value: Model filename, or an empty string if the handle is invalid

number Mass = number
Model mass
Value: Model mass, or 0 if the model handle is invalid

orientation MomentOfInertia = orientation
Model moment of inertia
Value: Moment of Inertia matrix or identity matrix if invalid

number Radius = number
Model radius (Used for collision & culling detection)
Value: Model Radius or 0 if invalid

boolean isValid()
True if valid, false or nil if not
Returns: Detects whether handle is valid

modeltextures_h
Array of materials

number #
Number of textures on model
Returns: Number of model textures

texture [] texture
number Index/string TextureName
Returns: Model textures, or invalid modeltextures handle if model handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

eyepoints
Array of model eye points

number #
Gets the number of eyepoints on this model
Returns: Number of eyepoints on this model or 0 on error

eyepoint [] eyepoint
Gets en eyepoint handle
Returns: eye handle or invalid handle on error

boolean isValid()
Detects whether handle is valid or not
Returns: true if valid false otherwise

thrusters
The thrusters of a model

number #
Number of thruster banks on the model
Returns: Number of thrusterbanks

thrusterbank [] number Index
Array of all thrusterbanks on this thruster
Returns: Handle to the thrusterbank or invalid handle if index is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

thrusterbank
A model thrusterbank

number #
Number of thrusters on this thrusterbank
Returns: Number of thrusters on this bank or 0 if handle is invalid

glowpoint [] number Index
Array of glowpoint
Returns: Glowpoint, or invalid glowpoint handle on failure

boolean isValid()
Detectes if this handle is valid
Returns: true if this handle is valid, false otherwise

glowpoint
A model glowpoint

vector Position
The (local) vector to the position of the glowpoint

number Radius
The radius of the glowpoint

boolean isValid()
Returns wether this handle is valid or not
Returns: True if handle is valid, false otherwise

order
order handle

boolean remove()
Removes the given order from the ship's priority queue.
Returns: True if order was successfully removed, otherwise false or nil.

shiporders
Ship orders

number #
Number of textures on ship
Returns: Number of textures on ship, or 0 if handle is invalid

order [] number Index/string TextureFilename
Array of ship orders
Returns: Order, or invalid texture handle on failure

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

physics
Physics handle

number AfterburnerAccelerationTime = number
Afterburner acceleration time
Value: Afterburner acceleration time, or 0 if handle is invalid

vector AfterburnerVelocityMax = vector
Afterburner max velocity (Local vector)
Value: Afterburner max velocity, or null vector if handle is invalid

number BankingConstant = number
Banking constant
Value: Banking constant, or 0 if handle is invalid

number ForwardAccelerationTime = number
Forward acceleration time
Value: Forward acceleration time, or 0 if handle is invalid

number ForwardDecelerationTime = number
Forward deceleration time
Value: Forward decleration time, or 0 if handle is invalid

number ForwardThrust = number
Forward thrust amount (0-1), used primarily for thruster graphics
Value: Forward thrust, or 0 if handle is invalid

number Mass = number
Object mass
Value: Object mass, or 0 if handle is invalid

vector RotationalVelocity = vector
Rotational velocity (Local vector)
Value: Rotational velocity, or null vector if handle is invalid

number RotationalVelocityDamping = number
Rotational damping, ie derivative of rotational speed
Value: Rotational damping, or 0 if handle is invalid

number RotationalVelocityDesired = lvector
Desired rotational velocity
Value: Desired rotational velocity, or 0 if handle is invalid

vector RotationalVelocityMax = vector
Maximum rotational velocity (Local vector)
Value: Maximum rotational velocity, or null vector if handle is invalid

number ShockwaveShakeAmplitude = number
How much shaking from shockwaves is applied to object
Value: Shockwave shake amplitude, or 0 if handle is invalid

number SideThrust = number
Side thrust amount (0-1), used primarily for thruster graphics
Value: Side thrust amount, or 0 if handle is invalid

number SlideAccelerationTime = number
Time to accelerate to maximum slide velocity
Value: Sliding acceleration time, or 0 if handle is invalid

number SlideDecelerationTime = number
Time to decelerate from maximum slide speed
Value: Sliding deceleration time, or 0 if handle is invalid

vector Velocity = vector
Object world velocity (World vector)
Value: Object velocity, or null vector if handle is invalid

vector VelocityDesired = vector
Desired velocity (World vector)
Value: Desired velocity, or null vector if handle is invalid

vector VelocityMax = vector
Object max local velocity (Local vector)
Value: Maximum velocity, or null vector if handle is invalid

number VerticalThrust = number
Vertical thrust amount (0-1), used primarily for thruster graphics
Value: Vertical thrust amount, or 0 if handle is invalid

boolean AfterburnerActive = boolean
Specifies if the afterburner is active or not
Value: true if afterburner is active false otherwise

boolean isValid()
True if valid, false or nil if not
Returns: Detects whether handle is valid

number getSpeed()
Gets total speed as of last frame
Returns: Total speed, or 0 if handle is invalid

number getForwardSpeed()
Gets total speed in the ship's 'forward' direction as of last frame
Returns: Total forward speed, or 0 if handle is invalid

boolean isAfterburnerActive()
True if Afterburners are on, false or nil if not
Returns: Detects whether afterburner is active

boolean isGliding()
True if glide mode is on, false or nil if not
Returns: Detects if ship is gliding

sexpvariable
SEXP Variable handle

enumeration Persistence = enumeration
SEXP Variable persistance, uses SEXPVAR_*_PERSISTENT enumerations
Value: SEXPVAR_*_PERSISTENT enumeration, or invalid numeration if handle is invalid

enumeration Type = enumeration
SEXP Variable type, uses SEXPVAR_TYPE_* enumerations
Value: SEXPVAR_TYPE_* enumeration, or invalid numeration if handle is invalid

string Value = number/string
SEXP variable value
Value: SEXP variable contents, or nil if the variable is of an invalid type or the handle is invalid

string (string)
Returns SEXP name
Returns: SEXP name, or empty string if handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

boolean delete()
Deletes a SEXP Variable
Returns: True if successful, false if the handle is invalid

shields
Shields handle

number [] enumeration/number
Gets or sets shield quadrant strength. Use "SHIELD_*" enumeration or 1-4 for a specific quadrant, or NONE for the entire shield
Returns: Quadrant/shield strength, or 0 if handle is invalid

number CombinedLeft = number
Total shield hitpoints left (for all quadrants combined)
Value: Combined shield strength, or 0 if handle is invalid

number CombinedMax = number
Maximum shield hitpoints (for all quadrants combined)
Value: Combined maximum shield strength, or 0 if handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

shiptype
Ship type handle

string Name = string
Ship type name
Value: Ship type name, or empty string if handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

species
Species handle

string Name = string
Species name
Value: Species name, or empty string if handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

team
Team handle

boolean == team, team
Checks whether two teams are the same team
Returns: true if equal

string Name = string
Team name
Value: Team name, or empty string if handle is invalid

number, number, number getColor()
Gets the IFF color of the specified Team
Returns: rgb color for the specified team or nil if invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

texture
Texture handle

nil __gc
Auto-deletes texture
Returns: Nothing

boolean == texture, texture
Checks if two texture handles refer to the same texture
Returns: True if textures are equal

texture [] number
Returns texture handle to specified frame number in current texture's animation.This means that [1] will always return the first frame in an animation, no matter what frame an animation is.You cannot change a texture animation frame.
Returns: Texture handle, or invalid texture handle if index is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

nil unload()
Unloads a texture from memory
Returns: Nothing

string getFilename()
Returns filename for texture
Returns: Filename, or empty string if handle is invalid

number getWidth()
Gets texture width
Returns: Texture width, or 0 if handle is invalid

number getHeight()
Gets texture height
Returns: Texture height, or 0 if handle is invalid

number getFPS()
Gets frames-per-second of texture
Returns: Texture FPS, or 0 if handle is invalid

number getFramesLeft()
Gets number of frames left, from handle's position in animation
Returns: Frames left, or 0 if handle is invalid

material
Texture map, including diffuse, glow, and specular textures

texture BaseMap = texture
Base texture
Value: Base texture, or invalid texture handle if material handle is invalid

texture GlowMap = texture
Glow texture
Value: Glow texture, or invalid texture handle if material handle is invalid

texture SpecularMap = texture
Specular texture
Value: Texture handle, or invalid texture handle if material handle is invalid

weaponclass
Weapon class handle

string (string)
Weapon class name
Returns: Weapon class name, or an empty string if handle is invalid

string Name = string
Weapon class name
Value: Weapon class name, or empty string if handle is invalid

string Title = string
Weapon class title
Value: Weapon class title, or empty string if handle is invalid

string Description = string
Weapon class description string
Value: Description string, or empty string if handle is invalid

string TechTitle = string
Weapon class tech title
Value: Tech title, or empty string if handle is invalid

string TechAnimationFilename = string
Weapon class animation filename
Value: Filename, or empty string if handle is invalid

string TechDescription = string
Weapon class tech description string
Value: Description string, or empty string if handle is invalid

model Model = model
Model
Value: Weapon class model, or invalid model handle if weaponclass handle is invalid

number ArmorFactor = number
Amount of weapon damage applied to ship hull (0-1.0)
Value: Armor factor, or empty string if handle is invalid

number Damage = number
Amount of damage that weapon deals
Value: Damage amount, or 0 if handle is invalid

number FireWait = number
Weapon fire wait (cooldown time) in seconds
Value: Fire wait time, or 0 if handle is invalid

number FreeFlightTime = number
The time the weapon will fly before turing onto its target
Value: Free flight time or emty string if invalid

number LifeMax = number
Life of weapon in seconds
Value: Life of weapon, or 0 if handle is invalid

number Range = number
Range of weapon in meters
Value: Weapon Range, or 0 if handle is invalid

number Mass = number
Weapon mass
Value: Weapon mass, or 0 if handle is invalid

number ShieldFactor = number
Amount of weapon damage applied to ship shields (0-1.0)
Value: Shield damage factor, or 0 if handle is invalid

number SubsystemFactor = number
Amount of weapon damage applied to ship subsystems (0-1.0)
Value: Subsystem damage factor, or 0 if handle is invalid

number TargetLOD = number
LOD used for weapon model in the targeting computer
Value: LOD number, or 0 if handle is invalid

number Speed = number
Weapon max speed, aka $Velocity in weapons.tbl
Value: Weapon speed, or 0 if handle is invalid

boolean Bomb = boolean
Is weapon class flagged as bomb
Value: New flag

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

number getWeaponClassIndex()
Gets the index value of the weapon class
Returns: index value of the weapon class

boolean isLaser()
Return true if the weapon is a laser (this includes balistic primaries)
Returns: true if the weapon is a laser, false otherwise

boolean isMissile()
Return true if the weapon is a missile
Returns: true if the weapon is a missile, false otherwise

boolean isBeam()
Return true if the weapon is a beam
Returns: true if the weapon is a beam, false otherwise

collision info
Information about a collision

nil __gc
Removes the allocated reference of this handle
Returns: Nothing

model Model = model
The model this collision info is about
Value: The model

number getCollisionDistance()
The distance to the closest collision point
Returns: distance or -1 on error

vector getCollisionPoint([boolean local])
The collision point of this information (local to the object if boolean is set to true)
Returns: The collision point or nil of none

vector getCollisionNormal([boolean local])
The collision normal of this information (local to object if boolean is set to true)
Returns: The collision normal or nil of none

boolean isValid()
Detects if this handle is valid
Returns: true if valid false otherwise

object
Object handle

boolean == object, object
Checks whether two object handles are for the same object
Returns: True if equal, false if not or a handle is invalid

string (string)
Returns name of object (if any)
Returns: Object name, or empty string if handle is invalid

object Parent = object
Parent of the object. Value may also be a deriviative of the 'object' class, such as 'ship'.
Value: Parent handle, or invalid handle if object is invalid

vector Position = vector
Object world position (World vector)
Value: World position, or null vector if handle is invalid

vector LastPosition = vector
Object world position as of last frame (World vector)
Value: World position, or null vector if handle is invalid

orientation Orientation = orientation
Object world orientation (World orientation)
Value: Orientation, or null orientation if handle is invalid

orientation LastOrientation = orientation
Object world orientation as of last frame (World orientation)
Value: Orientation, or null orientation if handle is invalid

physics Physics = physics
Physics data used to move ship between frames
Value: Physics data, or invalid physics handle if object handle is invalid

number HitpointsLeft = number
Hitpoints an object has left
Value: Hitpoints left, or 0 if handle is invalid

shields Shields = shields
Shields
Value: Shields handle, or invalid shields handle if object handle is invalid

number getSignature()
Gets the object's unique signature
Returns: Returns the objects unique numeric signature, or -1 if invalid. useful for creating a metadata sytem

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

string getBreedName()
Gets object type
Returns: Object type name, or empty string if handle is invalid

number CollisionGroups = number
Collision group data
Value: Current collision group signature. NOTE: This is a bitfield, NOT a normal number.

vector getfvec([boolean normalize])
Returns the objects' current fvec.
Returns: Objects' forward vector, or nil if invalid. If called with a true argument, vector will be normalized.

vector getuvec([boolean normalize])
Returns the objects' current uvec.
Returns: Objects' up vector, or nil if invalid. If called with a true argument, vector will be normalized.

vector getrvec([boolean normalize])
Returns the objects' current rvec.
Returns: Objects' rvec, or nil if invalid. If called with a true argument, vector will be normalized.

vector, collision info checkRayCollision(vector Start Point, vector End Point, [boolean Local])
Checks the collisions between the polygons of the current object and a ray
Returns: World collision point (local if boolean is set to true) and the specific collsision info, nil if no collisions

asteroid:object
Asteroid handle

object Target = object
Asteroid target object; may be object derivative, such as ship.
Value: Target object, or invalid handle if asteroid handle is invalid

boolean kill([ship killer=nil, wvector hitpos=nil])
Kills the asteroid. Set "killer" to designate a specific ship as having been the killer, and "hitpos" to specify the world position of the hit location; if nil, the asteroid center is used.
Returns: True if successful, false or nil otherwise

shipclass
Ship class handle

string (string)
Ship class name
Returns: Ship class name, or an empty string if handle is invalid

string Name = string
Ship class name
Value: Ship class name, or an empty string if handle is invalid

string ShortName = string
Ship class short name
Value: Ship short name, or empty string if handle is invalid

string TypeString = string
Ship class type string
Value: Type string, or empty string if handle is invalid

string ManeuverabilityString = string
Ship class maneuverability string
Value: Maneuverability string, or empty string if handle is invalid

string ArmorString = string
Ship class armor string
Value: Armor string, or empty string if handle is invalid

string ManufacturerString = string
Ship class manufacturer
Value: Manufacturer, or empty string if handle is invalid

string Description = string
Ship class description
Value: Description, or empty string if handle is invalid

string TechDescription = string
Ship class tech description
Value: Tech description, or empty string if handle is invalid

number AfterburnerFuelMax = number
Afterburner fuel capacity
Value: Afterburner capacity, or 0 if handle is invalid

number CountermeasuresMax = number
Maximum number of countermeasures the ship can carry
Value: Countermeasure capacity, or 0 if handle is invalid

model Model = model
Model
Value: Ship class model, or invalid model handle if shipclass handle is invalid

model CockpitModel = model
Model used for first-person cockpit
Value: Cockpit model

number HitpointsMax = number
Ship class hitpoints
Value: Hitpoints, or 0 if handle is invalid

species Species = Species
Ship class species
Value: Ship class species, or invalid species handle if shipclass handle is invalid

shiptype Type = shiptype
Ship class type
Value: Ship type, or invalid handle if shipclass handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

boolean isInTechroom()
Gets whether or not the ship class is available in the techroom
Returns: Whether ship has been revealed in the techroom, false if handle is invalid

boolean renderTechModel(X1, Y1, X2, Y2, [Rotation %, Pitch %, Bank %, Zoom multiplier])
Draws ship model as if in techroom
Returns: Whether ship was rendered

boolean renderTechModel2(X1, Y1, X2, Y2, orientation Orientation=null, [Zoom multiplier])
Draws ship model as if in techroom
Returns: Whether ship was rendered

boolean isModelLoaded([boolean Load = false])
Checks if the model used for this shipclass is loaded or not and optionally loads the model, which might be a slow operation.
Returns: If the model is loaded or not

number getShipClassIndex()
Gets the index valus of the ship class
Returns: index value of the ship class

debris:object
Debris handle

boolean IsHull = boolean
Whether or not debris is a piece of hull
Value: Whether debris is a hull fragment, or false if handle is invalid

shipclass OriginClass = shipclass
The shipclass of the ship this debris originates from
Value: The shipclass of the ship that created this debris

number getDebrisRadius()
The radius of this debris piece
Returns: The radius of this debris piece or -1 if invalid

boolean isValid()
Return if this debris handle is valid
Returns: true if valid false otherwise

waypoint:object
waypoint handle

waypointlist
waypointlist handle

waypoint [] number Index
Array of waypoints that are part of the waypoint list
Returns: Waypoint, or invalid handle if the index or waypointlist handle is invalid

number #
Number of waypoints in the list. Note that the value returned cannot be relied on for more than one frame.
Returns: Number of waypoints in the list, or 0 if handle is invalid

string Name = string
Name of WaypointList
Value: Waypointlist name, or empty string if handle is invalid

weaponbank
Ship/subystem weapons bank handle

weaponclass WeaponClass = weaponclass
Class of weapon mounted in the bank
Value: Weapon class, or an invalid weaponclass handle if bank handle is invalid

number AmmoLeft = number
Ammo left for the current bank
Value: Ammo left, or 0 if handle is invalid

number AmmoMax = number
Maximum ammo for the current bank
Value: Ammo capacity, or 0 if handle is invalid

boolean Armed = boolean
Weapon armed status. Does not take linking into account.
Value: True if armed, false if unarmed or handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

weaponbanktype
Ship/subsystem weapons bank type handle

weaponbank [] number Index
Array of weapon banks
Returns: Weapon bank, or invalid handle on failure

boolean Linked = boolean
Whether bank is in linked or unlinked fire mode (Primary-only)
Value: Link status, or false if handle is invalid

boolean DualFire = boolean
Whether bank is in dual fire mode (Secondary-only)
Value: Dual fire status, or false if handle is invalid

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

number #
Number of weapons in the mounted bank
Returns: Number of bank weapons, or 0 if handle is invalid

subsystem
Ship subsystem handle

string (string)
Returns name of subsystem
Returns: Subsystem name, or empty string if handle is invalid

string ArmorClass = string
Current Armor class
Value: Armor class name, or empty string if none is set

number AWACSIntensity = number
Subsystem AWACS intensity
Value: AWACS intensity, or 0 if handle is invalid

number AWACSRadius = number
Subsystem AWACS radius
Value: AWACS radius, or 0 if handle is invalid

orientation Orientation = orientation
Orientation of subobject or turret base
Value: Subsystem orientation, or null orientation if handle is invalid

orientation GunOrientation = orientation
Orientation of turret gun
Value: Gun orientation, or null orientation if handle is invalid

number HitpointsLeft = number
Subsystem hitpoints left
Value: Hitpoints left, or 0 if handle is invalid. Setting a value of 0 will disable it - set a value of -1 or lower to actually blow it up.

number HitpointsMax = number
Subsystem hitpoints max
Value: Max hitpoints, or 0 if handle is invalid

vector Position = vector
Subsystem position with regards to main ship (Local Vector)
Value: Subsystem position, or null vector if subsystem handle is invalid

vector GunPosition = vector
Subsystem gun position with regards to main ship (Local vector)
Value: Gun position, or null vector if subsystem handle is invalid

string Name = string
Subsystem name
Value: Subsystem name, or an empty string if handle is invalid

string getModelName()
Returns the original name of the subsystem in the model file
Returns: name or empty string on error

weaponbanktype PrimaryBanks = weaponbanktype
Array of primary weapon banks
Value: Primary banks, or invalid weaponbanktype handle if subsystem handle is invalid

weaponbanktype SecondaryBanks = weaponbanktype
Array of secondary weapon banks
Value: Secondary banks, or invalid weaponbanktype handle if subsystem handle is invalid

object Target = object
Object targetted by this subsystem. If used to set a new target, AI targeting will be switched off.
Value: Targeted object, or invalid object handle if subsystem handle is invalid

boolean TurretResets = boolean
Specifies wether this turrets resets after a certain time of inactivity
Value: true if turret resets, false otherwise

number TurretResetDelay = number
The time (in milliseconds) after that the turret resets itself
Value: Reset delay

number TurnRate = number
The turn rate
Value: Turnrate or -1 on error

boolean TurretLocked = boolean
Whether the turret is locked. Setting to true locks the turret, setting to false frees it.
Value: True if turret is locked, false otherwise

number NextFireTimestamp = number
The next time the turret may attempt to fire
Value: Mission time (seconds) or -1 on error

boolean targetingOverride(boolean)
If set to true, AI targeting for this turret is switched off. If set to false, the AI will take over again.
Returns: Returns true if successful, false otherwise

boolean hasFired()
Determine if a subsystem has fired
Returns: true if if fired, false if not fired, or nil if invalid. resets fired flag when called.

boolean isTurret()
Determines if this subsystem is a turret
Returns: true if subsystem is turret, false otherwise or nil on error

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

nil fireWeapon([Turret weapon index = 1, Flak range = 100])
Fires weapon on turret
Returns: Nothing

boolean rotateTurret(vector Pos[, boolean reset=false)
Rotates the turret to face Pos or resets the turret to its original state
Returns: true on success false otherwise

vector getTurretHeading()
Returns the turrets forward vector
Returns: Returns a normalized version of the forward vector or null vector on error

number, number, number getFOVs()
Returns current turrets FOVs
Returns: Standard FOV, maximum barrel elevation, turret base fov.

matrix getTurretMatrix()
Returns current subsystems turret matrix
Returns: Turret matrix.

shiptextures
Ship textures handle

number #
Number of textures on ship
Returns: Number of textures on ship, or 0 if handle is invalid

texture [] number Index/string TextureFilename
Array of ship textures
Returns: Texture, or invalid texture handle on failure

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

ship:object
Ship handle

subsystem [] string Name/number Index
Array of ship subsystems
Returns: Subsystem handle, or invalid subsystem handle if index or ship handle is invalid

number #
Number of subsystems on ship
Returns: Subsystem number, or 0 if handle is invalid

string ShieldArmorClass = string
Current Armor class of the ships' shield
Value: Armor class name, or empty string if none is set

string ArmorClass = string
Current Armor class
Value: Armor class name, or empty string if none is set

string Name = string
Ship name
Value: Ship name, or empty string if handle is invalid

number AfterburnerFuelLeft = number
Afterburner fuel left
Value: Afterburner fuel left, or 0 if handle is invalid

number AfterburnerFuelMax = number
Afterburner fuel capacity
Value: Afterburner fuel capacity, or 0 if handle is invalid

shipclass Class = shipclass
Ship class
Value: Ship class, or invalid shipclass handle if ship handle is invalid

number CountermeasuresLeft = number
Number of countermeasures left
Value: Countermeasures left, or 0 if ship handle is invalid

weaponclass CountermeasureClass = weaponclass
Weapon class mounted on this ship's countermeasure point
Value: Countermeasure hardpoint weapon class, or invalid weaponclass handle if no countermeasure class or ship handle is invalid

number HitpointsMax = number
Total hitpoints
Value: Ship maximum hitpoints, or 0 if handle is invalid

number WeaponEnergyLeft = number
Current weapon energy reserves
Value: Ship current weapon energy reserve level, or 0 if invalid

number WeaponEnergyMax = number
Maximum weapon energy
Value: Ship maximum weapon energy reserve level, or 0 if invalid

boolean PrimaryTriggerDown = boolean
Determines if primary trigger is pressed or not
Value: True if pressed, false if not, nil if ship handle is invalid

weaponbanktype PrimaryBanks = weaponbanktype
Array of primary weapon banks
Value: Primary weapon banks, or invalid weaponbanktype handle if ship handle is invalid

weaponbanktype SecondaryBanks = weaponbanktype
Array of secondary weapon banks
Value: Secondary weapon banks, or invalid weaponbanktype handle if ship handle is invalid

weaponbanktype TertiaryBanks = weaponbanktype
Array of tertiary weapon banks
Value: Tertiary weapon banks, or invalid weaponbanktype handle if ship handle is invalid

object Target = object
Target of ship. Value may also be a deriviative of the 'object' class, such as 'ship'.
Value: Target object, or invalid object handle if no target or ship handle is invalid

subsystem TargetSubsystem = subsystem
Target subsystem of ship.
Value: Target subsystem, or invalid subsystem handle if no target or ship handle is invalid

team Team = team
Ship's team
Value: Ship team, or invalid team handle if ship handle is invalid

shiptextures Textures = shiptextures
Gets ship textures
Value: Ship textures, or invalid shiptextures handle if ship handle is invalid

boolean FlagAffectedByGravity = boolean
Checks for the "affected-by-gravity" flag
Value: True if flag is set, false if flag is not set and nil on error

boolean Disabled = boolean
The disabled state of this ship
Value: true if ship is diabled, false otherwise

boolean kill([object Killer])
Kills the ship. Set "Killer" to the ship you are killing to self-destruct
Returns: True if successful, false or nil otherwise

boolean addShipEffect(string name, int duration (in milliseconds))
Activates an effect for this ship. Effect names are defined in Post_processing.tbl, and need to be implemented in the main shader. This functions analogous to the ship-effect sexp. NOTE: only one effect can be active at any time, adding new effects will override effects already in progress.
Returns: Returns true if the effect was successfully added, false otherwise

number hasShipExploded()
Checks if the ship explosion event has already happened
Returns: Returns 1 if first explosion timestamp is passed, 2 if second is passed, 0 otherwise

boolean fireCountermeasure()
Launches a countermeasure from the ship
Returns: Whether countermeasure was launched or not

number firePrimary()
Fires ship primary bank(s)
Returns: Number of primary banks fired

number fireSecondary()
Fires ship secondary bank(s)
Returns: Number of secondary banks fired

number getAnimationDoneTime(number Type, number Subtype)
Gets time that animation will be done
Returns: Time (seconds), or 0 if ship handle is invalid

boolean clearOrders()
Clears a ship's orders list
Returns: True if successful, otherwise false or nil

boolean giveOrder(enumeration Order, [object Target=nil, subsystem TargetSubsystem=nil, number Priority=1.0])
Uses the goal code to execute orders
Returns: True if order was given, otherwise false or nil

boolean doManeuver(number Duration, number Heading, number Pitch, number Bank, boolean Force Rotation, number Vertical, number Horizontal, number Forward, boolean Force Movement)
Sets ship maneuver over the defined time period
Returns: True if maneuver order was given, otherwise false or nil

boolean triggerAnimation(string Type, [number Subtype, boolean Forwards])
Triggers an animation. Type is the string name of the animation type, Subtype is the subtype number, such as weapon bank #, and Forwards is boolean.
IMPORTANT: Function is in testing and should not be used with official mod releases
Returns: True if successful, false or nil otherwise

boolean warpIn()
Warps ship in
Returns: True if successful, or nil if ship handle is invalid

boolean warpOut()
Warps ship out
Returns: True if successful, or nil if ship handle is invalid

boolean isWarpingIn()
Checks if ship is warping in
Returns: True if the ship is warping in, false or nil otherwise

number getEMP()
Returns the current emp effect strength acting on the object
Returns: Current EMP effect strength or NIL if object is invalid

number getTimeUntilExplosion()
Returns the time in seconds until the ship explodes
Returns: Time until explosion or -1, if invalid handle or ship isn't exploding

weapon:object
Weapon handle

weaponclass Class = weaponclass
Weapon's class
Value: Weapon class, or invalid weaponclass handle if weapon handle is invalid

boolean DestroyedByWeapon = boolean
Whether weapon was destroyed by another weapon
Value: True if weapon was destroyed by another weapon, false if weapon was destroyed by another object or if weapon handle is invalid

number LifeLeft = number
Weapon life left (in seconds)
Value: Life left (seconds) or 0 if weapon handle is invalid

number FlakDetonationRange = number
Range at which flak will detonate (meters)
Value: Detonation range (meters) or 0 if weapon handle is invalid

object Target = object
Target of weapon. Value may also be a deriviative of the 'object' class, such as 'ship'.
Value: Weapon target, or invalid object handle if weapon handle is invalid

subsystem ParentTurret = subsystem
Turret which fired this weapon.
Value: Turret subsystem handle, or an invalid handle if the weapon not fired from a turret

object HomingObject = object
Object that weapon will home in on. Value may also be a deriviative of the 'object' class, such as 'ship'
Value: Object that weapon is homing in on, or an invalid object handle if weapon is not homing or the weapon handle is invalid

vector HomingPosition = vector
Position that weapon will home in on (World vector)
Value: Homing point, or null vector if weapon handle is invalid

subsystem HomingSubsystem = subsystem
Subsystem that weapon will home in on.
Value: Homing subsystem, or invalid subsystem handle if weapon is not homing or weapon handle is invalid

team Team = team
Weapon's team
Value: Weapon team, or invalid team handle if weapon handle is invalid

boolean isArmed([boolean Hit target])
Checks if the weapon is armed.
Returns: boolean value of the weapon arming status

collision info getCollisionInformation()
Returns the collision information for this weapon
Returns: The collision information or invalid handle if none

beam:object
Beam handle

weaponclass Class = weaponclass
Weapon's class
Value: Weapon class, or invalid weaponclass handle if beam handle is invalid

vector LastShot = vector
End point of the beam
Value: vector or null vector if beam handle is not valid

vector LastStart = vector
Start point of the beam
Value: vector or null vector if beam handle is not valid

object Target = object
Target of beam. Value may also be a deriviative of the 'object' class, such as 'ship'.
Value: Beam target, or invalid object handle if beam handle is invalid

subsystem TargetSubsystem = subsystem
Subsystem that beam is targeting.
Value: Target subsystem, or invalid subsystem handle if beam handle is invalid

object ParentShip = object
Parent of the beam.
Value: Beam parent, or invalid object handle if beam handle is invalid

subsystem ParentSubsystem = subsystem
Subsystem that beam is fired from.
Value: Parent subsystem, or invalid subsystem handle if beam handle is invalid

number getCollisionCount()
Get the number of collisions in frame.
Returns: Number of beam collisions

vector getCollisionPosition(number)
Get the position of the defined collision.
Returns: World vector

collision info getCollisionInformation(number)
Get the collision information of the specified collision
Returns: handle to information or invalid handle on error

object getCollisionObject(number)
Get the target of the defined collision.
Returns: Object the beam collided with

boolean isExitCollision(number)
Checks if the defined collision was exit collision.
Returns: True if the collision was exit collision, false if entry, nil otherwise

vector getStartDirectionInfo()
Gets the start information about the direction. The vector is a normalized vector from LastStart showing the start direction of a slashing beam
Returns: The start direction or null vector if invalid

vector getEndDirectionInfo()
Gets the end information about the direction. The vector is a normalized vector from LastStart showing the end direction of a slashing beam
Returns: The start direction or null vector if invalid

wing
Wing handle

ship [] number Index
Array of ships in the wing
Returns: Ship handle, or invalid ship handle if index is invawing handle is invalid

number #
Number of wings in mission
Returns: Number of wings in mission

player
Player handle

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

string getName()
Gets current player name
Returns: Player name, or empty string if handle is invalid

string getCampaignFilename()
Gets current player campaign filename
Returns: Campaign name, or empty string if handle is invalid

string getImageFilename()
Gets current player image filename
Returns: Player image filename, or empty string if handle is invalid

number getMainHall()
Gets player's main hall number
Returns: Main hall index, or 1 if handle is invalid

string getSquadronName()
Gets current player squad name
Returns: Squadron name, or empty string if handle is invalid

camera
Camera handle

string (string)
Camera name
Returns: Camera name, or an empty string if handle is invalid

boolean isValid()
True if valid, false or nil if not
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

string Name = string
New camera name
Value: Camera name

number FOV = number
New camera FOV (in radians)
Value: Camera FOV (in radians)

orientation Orientation = orientation
New camera orientation
Value: Camera orientation

vector Position = vector
New camera position
Value: Camera position

object Self = object
New mount object
Value: Camera object

subsystem SelfSubsystem = subsystem
New mount object subsystem
Value: Subsystem that the camera is mounted on

object Target = object
New target object
Value: Camera target object

subsystem TargetSubsystem = subsystem
New target subsystem
Value: Subsystem that the camera is pointed at

boolean setFOV([number FOV, number Zoom Time, number Zoom Acceleration Time, number Zoom deceleration Time])
Sets camera FOV
FOV is the final field of view, in radians, of the camera.
Zoom Time is the total time to take zooming in or out.
Acceleration Time is the total time it should take the camera to get up to full zoom speed.
Deceleration Time is the total time it should take the camera to slow down from full zoom speed.
Returns: true if successful, false or nil otherwise

boolean setOrientation([world orientation Orientation, number Rotation Time, number Acceleration Time, number Deceleration time])
Sets camera orientation and velocity data.
Orientation is the final orientation for the camera, after it has finished moving. If not specified, the camera will simply stop at its current orientation.
Rotation time is how long total, including acceleration, the camera should take to rotate. If it is not specified, the camera will jump to the specified orientation.
Acceleration time is how long it should take the camera to get 'up to speed'. If not specified, the camera will instantly start moving.
Deceleration time is how long it should take the camera to slow down. If not specified, the camera will instantly stop moving.
Returns: true if successful, false or nil otherwise

boolean setPosition([wvector Position, number Translation Time, number Acceleration Time, number Deceleration Time])
Sets camera position and velocity data.
Position is the final position for the camera. If not specified, the camera will simply stop at its current position.
Translation time is how long total, including acceleration, the camera should take to move. If it is not specified, the camera will jump to the specified position.
Acceleration time is how long it should take the camera to get 'up to speed'. If not specified, the camera will instantly start moving.
Deceleration time is how long it should take the camera to slow down. If not specified, the camera will instantly stop moving.
Returns: true if successful, false or nil otherwise

soundentry
sounds.tbl table entry handle

number DefaultVolume = number
The default volume of this game sound
Value: Volume in the range from 1 to 0 or -1 on error

string getFilename()
Returns the filename of this sound
Returns: filename or empty string on error

number getDuration()
Gives the length of the sound in seconds.
Returns: the length, or -1 on error

number, number get3DValues(vector Postion[, number radius=0.0])
Computes the volume and the panning of the sound when it would be played from the specified position.
If range is given then the volume will diminish when the listener is withing that distance to the source.
The position of the listener is always the the current viewing position.
Returns: The volume and the panning, in that sequence, or both -1 on error

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

sound
sound instance handle

number Pitch = number
Pitch of sound, from 100 to 100000
Value: Pitch, or 0 if handle is invalid

number getRemainingTime()
The remaining time of this sound handle
Returns: Remaining time, or -1 on error

boolean setVolume(number)
Sets the volume of this sound instance
Returns: true if succeeded, false otherwise

boolean setPanning(number)
Sets the panning of this sound. Argument ranges from -1 for left to 1 for right
Returns: true if succeeded, false otherwise

boolean setPosition(number[,boolean = true])
Sets the absolute position of the sound. If boolean argument is true then the value is given as a percentage
Returns: true if successfull, false otherwise

boolean rewind(number)
Rewinds the sound by the given number of seconds
Returns: true if succeeded, false otherwise

boolean skip(number)
Skips the given number of seconds of the sound
Returns: true if succeeded, false otherwise

boolean isPlaying()
Specifies if this handle is currently playing
Returns: true if playing, false if otherwise

boolean stop()
Stops the sound of this handle
Returns: true if succeeded, false otherwise

boolean isValid()
Detects whether handle is valid
Returns: true if valid, false if handle is invalid, nil if a syntax/type error occurs

3Dsound:sound
3D sound instance handle

boolean updatePosition(vector Position[, number radius = 0.0])
Updates the given 3D sound with the specified position and an optional range value
Returns: true if succeesed, false otherwise

control info
control info handle

number Pitch = number
Pitch of the player ship
Value: Pitch

number Heading = number
Heading of the player ship
Value: Heading

number Bank = number
Bank of the player ship
Value: Bank

number Vertical = number
Vertical control of the player ship
Value: Vertical control

number Sideways = number
Sideways control of the player ship
Value: Sideways control

number Forward = number
Forward control of the player ship
Value: Forward

number ForwardCruise = number
Forward control of the player ship
Value: Forward

number PrimaryCount = number
Number of primary weapons that will fire
Value: Number of weapons to fire, or 0 if handle is invalid

number SecondaryCount = number
Number of secondary weapons that will fire
Value: Number of weapons to fire, or 0 if handle is invalid

number CountermeasureCount = number
Number of countermeasures that will launch
Value: Number of countermeasures to launch, or 0 if handle is invalid

nil clearLuaButtonInfo()
Clears the lua button control info
Returns: Nothing

number, number, number,number getButtonInfo()
Access the four bitfields containing the button info
Returns: Four bitfields

number, number, number,number accessButtonInfo(number, number, number, number)
Access the four bitfields containing the button info
Returns: Four bitfields

nil useButtonControl(number, string)
Adds the defined button control to lua button control data, if number is -1 it tries to use the string
Returns: Nothing

string getButtonControlName(number)
Gives the name of the command corresponding with the given number
Returns: Name of the command

number getButtonControlNumber(string)
Gives the number of the command corresponding with the given string
Returns: Number of the command

boolean AllButtonPolling = boolean
Toggles the all button polling for lua
Value: If the all button polling is enabled or not

number, number, number,number pollAllButtons()
Access the four bitfields containing the button info
Returns: Four bitfields

particle
Handle to a particle

vector Position = vector
The current position of the particle (world vector)
Value: The current position

vector Velocity = vector
The current velocity of the particle (world vector)
Value: The current velocity

number Age = number
The time this particle already lives
Value: The current age or -1 on error

number MaximumLife = number
The time this particle can live
Value: The maximal life or -1 on error

number Radius = number
The radius of the particle
Value: The radius or -1 on error

number TracerLength = number
The tracer legth of the particle
Value: The radius or -1 on error

object AttachedObject = object
The object this particle is attached to. If valid the position will be relativ to this object and the velocity will be ignored.
Value: Attached object or invalid object handle on error

boolean isValid()
Detects whether this handle is valid
Returns: true if valid false if not

Audio (ad)
Sound/Music Library

soundentry getSoundentry(string/number)
Return a sound entry matching the specified index or name. If you are using a number then the first valid index is 1
Returns: soundentry or invalid handle on error

sound playSound(soundentry)
Plays the specified sound entry handle
Returns: A handle to the playing sound

sound playLoopingSound(soundentry)
Plays the specified sound as a looping sound
Returns: A handle to the playing sound or invalid handle if playback failed

3Dsound play3DSound(soundentry[, vector source[, vector listener]])
Plays the specified sound entry handle. Source if by default 0, 0, 0 and listener is by default the current viewposition
Returns: A handle to the playing sound

boolean playGameSound(Sound index, [Panning (-1.0 left to 1.0 right), Volume %, Priority 0-3, Voice Message?])
Plays a sound from #Game Sounds in sounds.tbl. A priority of 0 indicates that the song must play; 1-3 will specify the maximum number of that sound that can be played
Returns: True if sound was played, false if not (Replaced with a sound instance object in the future)

boolean playInterfaceSound(Sound index)
Plays a sound from #Interface Sounds in sounds.tbl
Returns: True if sound was played, false if not

number playMusic(string Filename, [float volume = 1.0, bool looping = true])
Plays a music file using FS2Open's builtin music system. Volume should be in the 0.0 - 1.0 range, and is capped at 1.0. Files passed to this function are looped by default.
Returns: Audiohandle of the created audiostream, or -1 on failure

nil stopMusic(int audiohandle, [bool fade = false])
Stops a playing music file, provided audiohandle is valid
Returns: Nothing

Base (ba)
Base FreeSpace 2 functions

nil print(string Message)
Prints a string
Returns: Nothing

nil warning(string Message)
Displays a FreeSpace warning (debug build-only) message with the string provided
Returns: Nothing

nil error(string Message)
Displays a FreeSpace error message with the string provided
Returns: Nothing

orientation createOrientation([p/r1c1, b/r1c2, h/r1c3, r2c1, r2c2, r2c3, r3c1, r3c2, r3c3])
Given 0, 3, or 9 arguments, creates an orientation object with that orientation.
Returns: New orientation object, or null orientation on failure

vector createVector([x, y, z])
Creates a vector object
Returns: Vector object

number getFrametime([Do not adjust for time compression (Boolean)])
Gets how long this frame is calculated to take. Use it to for animations, physics, etc to make incremental changes.
Returns: Frame time (seconds)

state getCurrentGameState([Depth (number)])
Gets current FreeSpace state; if a depth is specified, the state at that depth is returned. (IE at the in-game options game, a depth of 1 would give you the game state, while the function defaults to 0, which would be the options screen.
Returns: Current game state at specified depth, or invalid handle if no game state is active yet

string getCurrentMPStatus(NIL)
Gets this computers current MP status
Returns: Current MP status

string setControlMode(NIL or enumeration LE_*_CONTROL)
Sets the current control mode for the game.
Returns: Current control mode

string setButtonControlMode(NIL or enumeration LE_*_BUTTON_CONTROL)
Sets the current control mode for the game.
Returns: Current control mode

control info getControlInfo()
Gets the control info handle.
Returns: control info handle

boolean postGameEvent(gameevent Event)
Sets current game event. Note that you can crash FreeSpace 2 by posting an event at an improper time, so test extensively if you use it.
Returns: True if event was posted, false if passed event was invalid

gameevent GameEvents[] number Index/string Name
Array of game events
Returns: Game event, or invalid gameevent handle if index is invalid

number #
Number of events
Returns: Number of events

gamestate GameStates[] number Index/string Name
Array of game states
Returns: Game state, or invalid gamestate handle if index is invalid

number #
Number of states
Returns: Number of states

CFile (cf)
CFile FS2 filesystem access

boolean deleteFile(string Filename, string Path)
Deletes given file. Path must be specified. Use a slash for the root directory.
Returns: True if deleted, false

boolean fileExists(string Filename, [string Path = "", boolean CheckVPs = false])
Checks if a file exists. Use a blank string for path for any directory, or a slash for the root directory.
Returns: True if file exists, false or nil otherwise

file openFile(string Filename, [string Mode="r", string Path = ""])
Opens a file. 'Mode' uses standard C fopen arguments. Use a blank string for path for any directory, or a slash for the root directory.Be EXTREMELY CAREFUL when using this function, as you may PERMANENTLY delete any file by accident
Returns: File handle, or invalid file handle if the specified file couldn't be opened

file openTempFile()
Opens a temp file that is automatically deleted when closed
Returns: File handle, or invalid file handle if tempfile couldn't be created

boolean renameFile(string CurrentFilename, string NewFilename, string Path)
Renames given file. Path must be specified. Use a slash for the root directory.
Returns: True if file was renamed, otherwise false

Controls (io)
Controls library

number getMouseX()
Gets Mouse X pos
Returns: Mouse x position, or 0 if mouse is not initialized yet

number getMouseY()
Gets Mouse Y pos
Returns: Mouse y position, or 0 if mouse is not initialized yet

boolean isMouseButtonDown({MOUSE_*_BUTTON enumeration}, [..., ...])
Returns whether the specified mouse buttons are up or down
Returns: Whether specified mouse buttons are down, or false if mouse is not initialized yet

nil setCursorImage(Image filename, [LOCK or UNLOCK])
Sets mouse cursor image, and allows you to lock/unlock the image. (A locked cursor may only be changed with the unlock parameter)
Returns: Nothing

nil setCursorHidden(True to hide mouse, false to show it)
Shows or hides mouse cursor
Returns: Nothing

boolean forceMousePosition(number, number (coordinates))
function to force mouse position
Returns: if the operation succeeded or not

boolean MouseControlStatus = boolean
Gets and sets the retail mouse control status
Value: if the retail mouse is on or off

boolean updateTrackIR()
Updates Tracking Data. Call before using get functions
Returns: Checks if trackir is available and updates variables, returns true if successful, otherwise false

number getTrackIRPitch()
Gets pitch axis from last update
Returns: Pitch value -1 to 1, or 0 on failure

number getTrackIRYaw()
Gets yaw axis from last update
Returns: Yaw value -1 to 1, or 0 on failure

number getTrackIRRoll()
Gets roll axis from last update
Returns: Roll value -1 to 1, or 0 on failure

number getTrackIRX()
Gets x position from last update
Returns: X value -1 to 1, or 0 on failure

number getTrackIRY()
Gets y position from last update
Returns: Y value -1 to 1, or 0 on failure

number getTrackIRZ()
Gets z position from last update
Returns: Z value -1 to 1, or 0 on failure

HUD (hu)
HUD library

boolean HUDDrawn = boolean
Current HUD draw status
Value: If the HUD is drawn or not

boolean setHUDGaugeColor(number (index number of the gauge), [number red, number green, number blue, number alpha])
Color used to draw the gauge
Returns: If the operation was successful

number, number, number, number getHUDGaugeColor(number (index number of the gauge))
Color used to draw the gauge
Returns: Red, green, blue, and alpha of the gauge

HudGauge getHUDGaugeHandle(string Name)
Returns a handle to a specified HUD gauge
Returns: HUD Gauge handle, or nil if invalid

Graphics (gr)
Graphics Library

camera Cameras[] number Index/string Name
Gets camera
Returns: Ship handle, or invalid ship handle if index was invalid

number #
Gets number of cameras
Returns: Number of cameras

font Fonts[] number Index/string Filename
Array of loaded fonts
Returns: Font handle, or invalid font handle if index is invalid

number #
Number of loaded fonts
Returns: Number of loaded fonts

font CurrentFont = font
Current font
Value: (null)

enumeration CurrentOpacityType = enumeration
Current alpha blending type; uses ALPHABLEND_* enumerations
Value: (null)

texture CurrentRenderTarget = texture
Current rendering target
Value: Current rendering target, or invalid texture handle if screen is render target

nil clearScreen([number Red, number green, number blue, number alpha])
Clears the screen to black, or the color specified.
Returns: Nothing

camera createCamera(string Name, [wvector Position, orientation Orientation])
Creates a new camera using the specified position and orientation (World)
Returns: Camera handle, or invalid camera handle if camera couldn't be created

number getScreenWidth()
Gets screen width
Returns: Width in pixels, or 0 if graphics are not initialized yet

number getScreenHeight()
Gets screen height
Returns: Height in pixels, or 0 if graphics are not initialized yet

vector getVectorFromCoords([number X=center, number Y=center, number Depth, boolean normalize = false])
Returns a vector through screen coordinates x and y. If depth is specified, vector is extended to Depth units into spaceIf normalize is true, vector will be normalized.
Returns: Vector, or zero vector on failure

boolean setTarget([texture Texture])
If texture is specified, sets current rendering surface to a texture.Otherwise, sets rendering surface back to screen.
Returns: True if successful, false otherwise

boolean setCamera([camera handle Camera])
Sets current camera, or resets camera if none specified
Returns: true if successful, false or nil otherwise

nil setColor(number Red, number Green, number Blue, [number Alpha])
Sets 2D drawing color; each color number should be from 0 (darkest) to 255 (brightest)
Returns: Nothing

nil drawCircle(number Radius, number X, number Y)
Draws a circle
Returns: Nothing

nil drawCurve(number X, number Y, number Radius)
Draws a curve
Returns: Nothing

nil drawGradientLine(number X1, number Y1, number X2, number Y2)
Draws a line from (x1,y1) to (x2,y2) with the CurrentColor that steadily fades out
Returns: Nothing

nil drawLine(number X1, number Y1, number X2, number Y2)
Draws a line from (x1,y1) to (x2,y2) with CurrentColor
Returns: Nothing

nil drawPixel(number X, number Y)
Sets pixel to CurrentColor
Returns: Nothing

nil drawPolygon(texture Texture, [vector Position={0,0,0}, orientation Orientation=null, number Width=1.0, number Height=1.0])
Draws a polygon
Returns: Nothing

nil drawRectangle(number X1, number Y1, number X2, number Y2, [boolean Filled=true])
Draws a rectangle with CurrentColor
Returns: Nothing

boolean drawSphere([number Radius = 1.0, vector Position])
Draws a sphere with radius Radius at world vector Position
Returns: True if successful, false or nil otherwise

int drawModel(model, position, orientation)
Draws the given model with the specified position and orientation - Use with extreme care, may not work properly in all scripting hooks.
Returns: Zero if successful, otherwise an integer error code

int drawModelOOR(model Model, vector Position, matrix Orientation, integer Flags)
Draws the given model with the specified position and orientation - Use with extreme care, designer to operate properly only in On Object Render hook.
Returns: Zero if successful, otherwise an integer error code

number,number,number,number drawTargetingBrackets(object Object, [boolean draw=true, int padding=5])
Gets the edge positions of targeting brackets for the specified object. The brackets will only be drawn if draw is true or the default value of draw is used. Brackets are drawn with the current color. The brackets will have a padding (distance from the actual bounding box); the default value (used elsewhere in FS2) is 5.
Returns: Left, top, right, and bottom positions of the brackets, or nil if invalid

number drawString(string Message, [number X1, number Y1, number X2, number Y2])
Draws a string. Use x1/y1 to control position, x2/y2 to limit textbox size.Text will automatically move onto new lines, if x2/y2 is specified.Additionally, calling drawString with only a string argument will automaticallydraw that string below the previously drawn string (or 0,0 if no stringshave been drawn yet
Returns: Number of lines drawn, or 0 on failure

number getStringWidth(string String)
Gets string width
Returns: String width, or 0 on failure

texture createTexture([number Width=512, number Height=512, enumeration Type=TEXTURE_DYNAMIC])
Creates a texture for rendering to.Types are TEXTURE_STATIC - for infrequent rendering - and TEXTURE_DYNAMIC - for frequent rendering.
Returns: New texture handle, or invalid texture handle if texture couldn't be created

texture loadTexture(string Filename, [boolean LoadIfAnimation, boolean NoDropFrames])
Gets a handle to a texture. If second argument is set to true, animations will also be loaded.If third argument is set to true, every other animation frame will not be loaded if system has less than 48 MB memory.
IMPORTANT: Textures will not be unload themselves unless you explicitly tell them to do so.When you are done with a texture, call the Unload() function to free up memory.
Returns: Texture handle, or invalid texture handle if texture couldn't be loaded

boolean drawImage(string Filename/texture Texture, [number X1=0, Y1=0, number X2, number Y2, number UVX1 = 0.0, number UVY1 = 0.0, number UVX2=1.0, number UVY2=1.0, number alpha=1.0])
Draws an image or texture. Any image extension passed will be ignored.The UV variables specify the UV value for each corner of the image. In UV coordinates, (0,0) is the top left of the image; (1,1) is the lower right.
Returns: Whether image was drawn

boolean drawMonochromeImage(string Filename/texture Texture, number X1, number Y1, [number X2, number Y2, number alpha=1.0])
Draws a monochrome image using the current color
Returns: Whether image was drawn

number getImageWidth(string Filename)
Gets image width
Returns: Image width, or 0 if filename is invalid

number getImageHeight(Image name)
Gets image height
Returns: Image height, or 0 if filename is invalid

nil flashScreen(number Red, number Green, number Blue)
Flashes the screen
Returns: Nothing

model loadModel(string Filename)
Loads the model - will not setup subsystem data, DO NOT USE FOR LOADING SHIP MODELS
Returns: Handle to a model

boolean hasViewmode(enumeration)
Specifies if the current viemode has the specified flag, see VM_* enumeration
Returns: true if flag is present, false otherwise

HookVariables (hv)
Hook variables repository

string Globals[] number Index
Array of current HookVariable names
Returns: Hookvariable name, or empty string if invalid index specified

number #
Number of HookVariables
Returns: Number of HookVariables

Mission (mn)
Mission library

object getObjectFromSignature(number Signature)
Gets a handle of an object from its signature
Returns: Handle of object with signaure, invalid handle if signature is not in use

boolean evaluateSEXP(string)
Runs the defined SEXP script
Returns: if the operation was successful

boolean runSEXP(string)
Runs the defined SEXP script
Returns: if the operation was successful

asteroid Asteroids[] number Index
Gets asteroid
Returns: Asteroid handle, or invalid handle if invalid index specified

number #
Number of asteroids in mission. Note that the value returned is only good until an asteroid is destroyed, and so cannot be relied on for more than one frame.
Returns: Number of asteroids in the mission, or 0 if asteroids are not enabled

debris Debris[] number Index
Array of debris in the current mission
Returns: Debris handle, or invalid debris handle if index wasn't valid

number #
Number of debris pieces in the mission. Note that the value returned is only good until a piece of debris is destroyed, and so cannot be relied on for more than one frame.
Returns: Current number of debris particles

ship EscortShips[] number Index
Gets escort ship at specified index on escort list
Returns: Specified ship, or invalid ship handle if invalid index

number #
Current number of escort ships
Returns: Current number of escort ships

event Events[] number Index/string Name
Indexes events list
Returns: Event handle, or invalid event handle if index was invalid

number #
Number of events in mission
Returns: Number of events in mission

sexpvariable SEXPVariables[] number Index/string Name
Array of SEXP variables. Note that you can set a sexp variable using the array, eg 'SEXPVariables[1] = "newvalue"'
Returns: Handle to SEXP variable, or invalid sexpvariable handle if index was invalid

number #
Current number of SEXP variables
Returns: Counts number of loaded SEXP Variables. May be slow.

ship Ships[] number Index/string Name
Gets ship
Returns: Ship handle, or invalid ship handle if index was invalid

number #
Number of ships in the mission. This function is somewhat slow, and should be set to a variable for use in looping situations. Note that the value returned is only good until a ship is destroyed, and so cannot be relied on for more than one frame.
Returns: Number of ships in the mission, or 0 if ships haven't been initialized yet

waypoint Waypoints[] number Index
Array of waypoints in the current mission
Returns: Waypoint handle, or invalid waypoint handle if index was invalid

number #
Gets number of waypoints in mission. Note that this is only accurate for one frame.
Returns: Number of waypoints in the mission

waypointlist WaypointLists[] number Index/string WaypointListName
Array of waypoint lists
Returns: Gets waypointlist handle

number #
Number of waypoint lists in mission. Note that this is only accurate for one frame.
Returns: Number of waypoint lists in the mission

weapon Weapons[] number Index
Gets handle to a weapon object in the mission.
Returns: Weapon handle, or invalid weapon handle if index is invalid

number #
Number of weapon objects in mission. Note that this is only accurate for one frame.
Returns: Number of weapon objects in mission

beam Beams[] number Index
Gets handle to a beam object in the mission.
Returns: Beam handle, or invalid beam handle if index is invalid

number #
Number of beam objects in mission. Note that this is only accurate for one frame.
Returns: Number of beam objects in mission

wing Wings[] number Index/string WingName
Wings in the mission
Returns: Wing handle, or invalid wing handle if index or name was invalid

number #
Number of wings in mission
Returns: Number of wings in mission

ship createShip([string Name, shipclass Class=Shipclass[1], orientation Orientation=null, vector Position={0,0,0}])
Creates a ship and returns a handle to it using the specified name, class, world orientation, and world position
Returns: Ship handle, or invalid ship handle if ship couldn't be created

waypoint createWaypoint([vector Position, waypointlist List])
Creates a waypoint
Returns: Waypoint handle, or invalid waypoint handle if waypoint couldn't be created

weapon createWeapon([weaponclass Class=WeaponClass[1], orientation Orientation=null, world vector Position={0,0,0}, object Parent = nil, number Group = -1)
Creates a weapon and returns a handle to it. 'Group' is used for lighting grouping purposes; for example, quad lasers would only need to act as one light source.
Returns: Weapon handle, or invalid weapon handle if weapon couldn't be created.

string getMissionFilename()
Gets mission filename
Returns: Mission filename, or empty string if game is not in a mission

boolean startMission([Filename or MISSION_* enumeration, Briefing = true])
Starts the defined mission
Returns: True, or false if the function fails

number getMissionTime()
Game time in seconds since the mission was started; is affected by time compression
Returns: Mission time (seconds), or 0 if game is not in a mission

boolean loadMission(Mission name)
Loads a mission
Returns: True if mission was loaded, otherwise false

nil unloadMission()
Stops the current mission and unloads it
Returns: Nothing

nil simulateFrame()
Simulates mission frame
Returns: Nothing

nil renderFrame()
Renders mission frame, but does not move anything
Returns: Nothing

BitOps (bit)
Bitwise Operations library

number AND(number, number)
Values for which bitwise boolean AND operation is performed
Returns: Result of the AND operation

number OR(number, number)
Values for which bitwise boolean OR operation is performed
Returns: Result of the OR operation

number XOR(number, number)
Values for which bitwise boolean XOR operation is performed
Returns: Result of the XOR operation

number toggleBit(number, number (bit))
Toggles the value of the set bit in the given number for 32 bit integer
Returns: Result of the operation

boolean checkBit(number, number (bit))
Checks the value of the set bit in the given number for 32 bit integer
Returns: Was the bit true of false

number addBit(number, number (bit))
Performs inclusive or (OR) operation on the set bit of the value
Returns: Result of the operation

Tables (tb)
Tables library

ship ShipClasses[] number Index/string Name
Array of ship classes
Returns: Ship handle, or invalid ship handle if index is invalid

number #
Number of ship classes
Returns: Number of ship classes, or 0 if ship classes haven't been loaded yet

weapon WeaponClasses[] number Index/string WeaponName
Array of weapon classes
Returns: Weapon class handle, or invalid weaponclass handle if index is invalid

number #
Number of weapon classes
Returns: Number of weapon classes, or 0 if weapon classes haven't been loaded yet

Testing (ts)
Experimental or testing stuff

nil avdTest()
Test the AVD Physics code
Returns: Nothing

particle createParticle(vector Position, vector Velocity, number Lifetime, number Radius, enumeration Type, [number Tracer length=-1, boolean Reverse=false, texture Texture=Nil, object Attached Object=Nil])
Creates a particle. Use PARTICLE_* enumerations for type.Reverse reverse animation, if one is specifiedAttached object specifies object that Position will be (and always be) relative to.
Returns: Handle to the created particle

string getStack()
Generates an ADE stackdump
Returns: Current Lua stack

boolean isCurrentPlayerMulti()
Returns whether current player is a multiplayer pilot or not.
Returns: Whether current player is a multiplayer pilot or not

boolean isPXOEnabled()
Returns whether PXO is currently enabled in the configuration.
Returns: Whether PXO is enabled or not

Enumerations
ALPHABLEND_FILTER
ALPHABLEND_NONE
CFILE_TYPE_NORMAL
CFILE_TYPE_MEMORY_MAPPED
MOUSE_LEFT_BUTTON
MOUSE_RIGHT_BUTTON
MOUSE_MIDDLE_BUTTON
ORDER_ATTACK
ORDER_ATTACK_ANY
ORDER_DEPART
ORDER_DISABLE
ORDER_DISARM
ORDER_DOCK
ORDER_EVADE
ORDER_FLY_TO
ORDER_FORM_ON_WING
ORDER_GUARD
ORDER_IGNORE_SHIP
ORDER_KEEP_SAFE_DISTANCE
ORDER_PLAY_DEAD
ORDER_REARM
ORDER_STAY_NEAR
ORDER_STAY_STILL
ORDER_UNDOCK
ORDER_WAYPOINTS
ORDER_WAYPOINTS_ONCE
PARTICLE_DEBUG
PARTICLE_BITMAP
PARTICLE_FIRE
PARTICLE_SMOKE
PARTICLE_SMOKE2
PARTICLE_PERSISTENT_BITMAP
SEXPVAR_CAMPAIGN_PERSISTENT
SEXPVAR_NOT_PERSISTENT
SEXPVAR_PLAYER_PERSISTENT
SEXPVAR_TYPE_NUMBER
SEXPVAR_TYPE_STRING
TEXTURE_STATIC
TEXTURE_DYNAMIC
LOCK
UNLOCK
NONE
SHIELD_FRONT
SHIELD_LEFT
SHIELD_RIGHT
SHIELD_BACK
MISSION_REPEAT
NORMAL_CONTROLS
LUA_STEERING_CONTROLS
LUA_FULL_CONTROLS
NORMAL_BUTTON_CONTROLS
LUA_ADDITIVE_BUTTON_CONTROL
LUA_OVERRIDE_BUTTON_CONTROL
VM_INTERNAL
VM_EXTERNAL
VM_TRACK
VM_DEAD_VIEW
VM_CHASE
VM_OTHER_SHIP
VM_EXTERNAL_CAMERA_LOCKED
VM_WARP_CHASE
VM_PADLOCK_UP
VM_PADLOCK_REAR
VM_PADLOCK_LEFT
VM_PADLOCK_RIGHT
VM_WARPIN_ANCHOR
VM_TOPDOWN
VM_FREECAMERA

Scripting.tbl

2012-07-13T11:10:55Z

Aginor:

{{SCP_table}}

{{TableVersion|4500}}

----

The scripting table is used for scripting special features like alternate HUDs or ship viewer into the game.

This table is one of the [[Modular Tables]] and can be extended with xxx-sct.tbm

 
'''Useful references:'''
*'''[[FS2 Open Lua Scripting]]'''
*'''[[Scripting API]]'''

*'''[[Scripting functions]]'''
*'''[[Command-Line_Reference#-output_scripting|Command-Line Reference for creating scripting.html]]'''
*'''[http://lua-users.org/wiki/ Lua-Users Wiki]'''
*'''[http://www.lua.org/manual/5.0/ Reference manual for Lua 5.0]'''

==General Info==
*Scripting table consist of several sections identified by a hash mark preceeding the section name (i.g. #Global Hooks)
*All sections ''must'' end with #'''End'''
*All sections are optional
*Most entries are optional
*Scripting hooks are '''not''' executed on a separate thread (at least as of this writing). They are executed at given points in the code, and all other execution will not take place until a scripting hook has finished. Therefore, large and complicated scripts will most likely cause noticeable lag or slowdown when executed.
{{Template:Note|1=Information on this page does not apply to pre-3.6.10 builds}}
 

==Prerequisites==

===Frames===
One of the most important things to understand when reading this guide is the concept of "frames". (Experienced modders can probably skip this part) In gameplay, motion is achieved by making incremental changes every fraction of a second. A ship will be moved slightly, and then drawn to the screen. This happens 30-120 times a second; anything lower, and the game will become choppy and difficult to play.

There is also a difference in the moving of objects in-game, and the moving of objects onscreen. All ships are first "moved", in memory. This probably consists of physics calculations, that change the ship's position based on if their engines are turned on, or if they run into another object. After this, the game then renders the now-moved ships to what is referred to as a "backbuffer" - a place in memory that takes the place of the computer screen. Once rendering has finished, the backbuffer is instantly drawn to the screen. This prevents objects from flickering as they are drawn. You do not have to worry about flipping the backbuffer in scripting; FS2_Open will take care of that for you.

For scripting, '''it is important to understand that each block of code will therefore be executed several times a second, but only once per frame'''. However, the exact number of times per second will depend on how much work the computer has to do (And therefore how much time it takes) for each frame. To determine how much time you should consider to have passed, you must use the ba.getFrametime() function; which will return the approximate time the frame will take, in seconds. In addition, if you "move" a ship after it has already been rendered, the change will not become apparent until the next frame.

This does mean that if you want to make a block of text move across the screen, at a rate of 5 pixels per second, all you have to do is multiply the speed by the frametime:
<pre>#Global Hooks
$Global: [
--If the g_WheeXPosition variable does not exist,
--it means we are on the first frame.
--If that is the case, set it to zero.
if not g_WheeXPosition then
g_WheeXPosition = 0
end

--Move the text
g_WheeXPosition = g_WheeXPosition + (5 * ba.getFrametime())

--Draw "WHEE!!!"
gr.drawString("WHEE!!!", g_WheeXPosition, 10)
]
#End</pre>
 

===Hooks===
Scripting "hooks" form the basis of the scripting system. A "hook" simply refers to a point in the code where code to execute scripting has been added. The hook may then be added to a table, or added to a SEXP. In general usage, "hook" refers to an entry in scripting.tbl.

All hooks take the form of an identifer (such as $Global:), followed by brackets to determine what type of scripting is being executed. A lack of brackets also indicates a type of scripting execution. All current bracket configurations are listed below. Note that "$Hook:" is used merely as a placeholder, and should be replaced with the actual hook name ($Global:, $HUD:, $On Frame:, etc).
#<pre>$Hook: scripting</pre>Specifies one line of LUA scripting. In addition, the return value of that line will be passed to the interpreter and used (if applicable). Specifying a variable or value on this line will result in it being returned, as well.
#<pre>$Hook: [scripting]</pre>A single set of brackets specifies a block of LUA scripting. Does not return a value unless explicitly specified. (Explicit specification is not possible at this time; but may be implemented in the future if/when more future hooks take a return value.)
#<pre>$Hook: [[scriptfilename.lua]]</pre>Double brackets specify a file. This file is read out of the data/scripts directory, and must include the file extension. You may specify a compiled lua file as a target as well; this may result in crossplatform issues for a mod, however.
 

====+Override====
Some hooks additionally take a +Override: field. This field uses the same bracket configurations as above. If a hook includes a +Override field, this hook always determines whether the default FS2_Open behavior that the hook is associated with will function, or will be disabled. This should be used in cases where scripting will replace the original FS2_Open behavior. For example:
<pre>$HUD: [
gr.setColor(255, 255, 255, 255)
gr.drawString("HUD Disabled", 50, 50)
]
+Override: true</pre>

Additionally, override hooks are (by convention) executed before FS2_Open behavior. The HUD hook override, for example, is executed before any part of the HUD is actually drawn.
 

==Sections==

===#Global Hooks===
Global hooks are the simplest form of scripting hooks available. They are at preset locations in the code, and are generally executed every time that point is reached. Exceptions to this rule (such as the HUD hook) only depend on one or two variables to determine execution. All other scripting execution is determined by the modder.
Note that, as with other tables, the game expects these entries in precisely the order given here; if this is not followed, the parser will throw an error.
 

====$Global:====
Script in this section is executed almost immediately before each frame is drawn. This means that any scripting elements will be drawn, or take effect, after everything else, except for the "On Frame" conditional hook. It is not used with the standalone server. In addition, note that use of this hook should generally be avoided, since all scripting will have to be processed every frame.
 

====$Splash:====
This hook is executed once, when the splash images (PreLoad and PreLoadLogo) would be drawn. This hook should generally be used only for drawing the splash screen; any initialization could should be placed in GameInit. This hook is executed before virtually any other subsystem has been loaded, aside from the graphics and filesystem subsystems, so scripting elements such as the table and mission libraries will be nonfunctional.
 

=====+Override:=====
Executed just before default splash images are loaded and displayed. Note that the frame is still drawn regardless; it is not necessary to flip the backbuffer manually.
 

====$GameInit:====
This hook is executed once, after all of the Freespace2 subsystems have been initialized. It is executed before the game switches to the main hall or, in the case of standalone server mode, begins the game.
 

====$Simulation:====
This hook is executed only during missions. It is executed after all damage, movement, physics, SEXPs, and other "physical" in-game changes have been applied. It is executed before anything has been rendered. This hook should be used only for damage, movement, and physics related scripting, as if the game needs to be rendered without any in-game time having been passed, this function will not be called.
 

====$HUD:====
The HUD hook is executed after the HUD has been drawn. Note that if the HUD is turned off, this hook will be disabled as well, until the HUD is turned back on.
 

=====+Override:=====
Executed immediately before anything on the HUD is drawn, and controls whether the default FS2_Open is drawn.
 

===#State Hooks===
In Freespace2, a "state" more or less refers to a room. It may also refer to a separate mode - playing a mission is the GS_STATE_GAME_PLAY state. The main menu is the GS_STATE_MAIN_MENU state. This section should only exist in 3.6.9. It is included here for the sake of documentation; it has since been removed and superseded by the conditional hook system.
 

=====$State:=====
Specifies the state name. A full list of states is located here: ''[[List of Game States]]''

=====$Hook:=====
Executed after all of the state code has been executed, but before the game frame is actually drawn.

======+Override:======
Determines whether the specified state is handled at all by Freespace. If true, then none of the loading or exit code for the state will be specified as well.

===#Conditional Hooks===
Scripting hooks are only available in HEAD builds. They consist of any number of conditions, followed by any number of actions. All available conditions and actions are located in the file generated by -output_scripting.

One way to think of conditional scripting is like this: The condition specifies the object that the action will apply to, or the place that the action will occur in. All conditions must be met for their associated actions to execute. Actions are associated with a set of conditions by simply adding them after that set of conditions. (Obviously, you may want to space out each pair of action/condition sets in the TBL to make it easier to read.)

The flexibility of conditional scripting comes in due to its inherent scalability. If you specify a mission and ship condition with a warpin action, that script will only be executed when the ship warps in on that particular mission. Removing the mission field will make that warpin scripting apply to the ship for all missions; or removing the ship field will make the warpin scripting apply to all ships in that mission.

This prompts the question: if this is all conditional scripting does, why not just use the global hook?
#Organization - conditional scripting is generally easier to read and modify because it is grouped in a standardized manner.
#Speed - All conditions can be evaluated by FS2_Open itself, without invoking the Lua interpreter at all.
#Scalability - As of the time of this writing, you can only have one global hook. Modular tables will simply replace it. With conditional scripting, if you want to specify additional actions for a set of conditions in a modular table file, you may do so.

;Format

;'''$Condition:''': Where "$Condition:" is one of several conditions specified in scripting.html, such as $State: or $Ship:. Takes a value representing the object the condition should be checked against (such as a state, ship, or mission name)
;'''$Condition:''': ...
;'''...''':
;'''$Action:''': Where "$Action:" is one of several actions specified in scripting.html, such as $On Frame or $On Warp In. Takes a scripting hook, using the bracket configuration outlined at the top of this article.
;'''$Condition:''': ...
;'''...''':

A brief description of all Conditions and Actions at the time of this writing:

====Conditions====

=====$State:=====
Controls execution based on what state FS2_Open is in, such as the main hall, options screen, or in a mission.
*The full list of states can be found here: ''[[List of Game States]]''

=====$Campaign:=====
Controls execution based on the current campaign's filename. (It is under consideration to change this to the campaign's name, instead).

=====$Mission:=====
Controls execution based on the filename of the last mission to have started. This condition will remain true even after the mission has been exited until another mission is started.

=====$Object Type:=====
Defines a specific object type that the action will apply for, such as a "Ship", "Asteroid", or "Jump Node".

=====$Ship:=====
Defines a specific ship (name) that the action will apply for.

=====$Ship class:=====
Defines a specific ship class (name) that the action will apply for.

=====$Ship type:=====
Defines a specific ship type (name) that the action will apply for.

=====$Weapon class:=====
Defines a specific weapon class (name) that the action will apply for.

=====$KeyPress:=====
Defines a specific key that the action will apply for.
*Experimental.
 

====Actions====

=====$On Game Init:=====
Executes immediately after game has been started.
::* No associated hook variables.

=====$On Splash Screen:=====
Executes when initial game splash screen is shown
::* No associated hook variables.

=====$On State Start:=====
Executed when specified game state starts
::* No associated hook variables.

=====$On Frame:=====
Executes immediately after the global scripting hook, which is right before the frame is drawn.
::* No associated hook variables.

=====$On Key Pressed:=====
Executed when specified key is pressed
::* '''Key''', The pressed key

=====$On Key Released:=====
Executed when specified key is released
::* '''Key''', The released key

=====$On Mouse Moved:=====
Executed when mouse is moved
::* No associated hook variables.

=====$On Mouse Pressed:=====
Executed when mouse button is pressed
::* No associated hook variables.

=====$On Mouse Released:=====
Executed when mouse button is released
::* No associated hook variables.

=====$On State End:=====
Executed when specified game state ends
::* No associated hook variables.

=====$On Mission Start:=====
Executed when mission starts
::* No associated hook variables.

=====$On Gameplay Start:=====
{{Table3615|
Executed when the gameplay part of a mission starts
::* No associated hook variables.}}

=====$On HUD Draw:=====
Executed after the HUD has been drawn. Note that if the HUD is turned off, this hook will be disabled as well, until the HUD is turned back on
::* '''Self''', the viewer (object)

=====$On Ship Collision:=====
Executes when the specified object collides with a ship. Sets a handle in the HookVariables library with the name of the object type ("Weapon", "Debris", and so on) with the type of the object. If both objects are ships, the other object gains the name "ShipB". (If both ship objects define a collision hook, the variables will be swapped for the other ship, so the ship that the script is executing for will always be called "Script".) The override will disable FS2_Open code, as well as the other object's collision code. If both objects have an override set, only one of the objects' hooks will be used (Chosen arbitrarily). Note that the override receives the same variables.
::* When colliding something other than other ship:
::** '''Ship''', the ship (object)
::** '''Debris''', '''Asteroid''', '''Weapon''', depending what it collided with (object)
::** '''Self''', the object referred by the condition (object)
::** '''Object''', the ship (object)
::* When colliding with other ship:
::** '''Ship''', the ship (object) referred by the condition (object)
::** '''ShipB''', the other ship (object)
::** '''Self''', the ship (object) referred by the condition (object)
::** '''Object''', the other ship (object)

=====$On Weapon Collision:=====
Like the ship collision hook, but for weapons.
::* When colliding something other than other weapon:
::** '''Weapon''', the weapon (object)
::** '''Debris''', '''Asteroid''', '''Ship''', depending what it collided with (object)
::** '''Self''', the object the weapon collided with (object)
::** '''Object''', the weapon (object)
::* When colliding with other weapon:
::** '''Weapon''', the weapon (object) referred by the condition
::** '''WeaponB''', the other weapon (object)
::** '''Self''', the weapon (object) referred by the condition
::** '''Object''', the other weapon (object)

=====$On Debris Collision:=====
Like the ship collision hook, except for debris.
::* '''Debris''', the debris (object)
::* '''Weapon''', '''Ship''', depending what it collided with (object)
::* '''Self''', the object the debris collided with (object)
::* '''Object''', the debris (object)

=====$On Asteroid Collision:=====
Like the ship collision hook, only for asteroids.
::* '''Asteroid''', the asteroid (object)
::* '''Weapon''', '''Ship''', depending what it collided with (object)
::* '''Self''', the object the asteroid collided with (object)
::* '''Object''', the asteroid (object)

=====$On Object Render:=====
Executes when the specified object is rendered. The override is run before the object is rendered, and both the hook and its override receive an "Object" variable of the object to be rendered.
::* '''Self''', the object rendered (object)

=====$On Warp In:=====
Run when a ship has begun warping in, immediately after everything has been set up for per-frame processing. This hook is only executed once, when the ship begins warping in. An override will disable _all_ behavior related to warpin. Both the hook and an override receive an "Object" handle in the HookVariables library, with the type of the object that is warping in.
::* '''Self''', the object warping in (object)

=====$On Warp Out:=====
Same as warping in, except for warping out.
::* '''Self''', the object warping out (object)

=====$On Death:=====
*Currently only valid for ships.
Receives "Self" and "Killer" variables of the object and killer, respectively. Overriding it will override all default death behavior.
::* For asteroids:
::** '''Self''', the asteroid (object)
::* For ships:
::** '''Self''', the ship (object)
::** '''Killer''', the other object (object) - NOTE, not guaranteed to exists

=====$On Mission End:=====
Run on mission end.
::* No associated hook variables.
=====$On Weapon Equipped:=====
{{Table3613|
Runs once each frame, for every ship that has the weapon defined in the $Weapon class condition equipped.
::* '''User''', the ship carrying the weapon
::* '''Target''', the ships' current target
}}

=====$On Weapon Fired:=====
{{Table3613|
Runs once when a ship fires a weapon defined in the $Weapon class condition
::* '''User''', the ship carrying the weapon
::* '''Target''', the ships' current target
}}

=====$On Weapon Selected:=====
{{Table3613|
Runs once when a bank with a weapon defined in the $Weapon class condition is selected
::* '''User''', the ship carrying the weapon
::* '''Target''', the ships' current target
}}

=====$On Weapon Deselected:=====
{{Table3613|
Runs once when a bank with a weapon defined in the $Weapon class condition is deselected
::* '''User''', the ship carrying the weapon
::* '''Target''', the ships' current target
}}

=====$On Turret Fired:=====
{{Table3615|
Executed when a turret fires
::* '''Ship''', the parent ship
::* '''Weapon''', the weapon which was fired
::* '''Target''', the intended target}}

==Misc. Hook Variables:==

===Viewer===
*Active if (non-player) viewing object is valid

===Player===
*Active if player obj is valid
 

==Examples==

See [[:Category:Scripting Examples|Scripting Examples category]]

[[Category:Tables]]