EmptyEpsilon Scripting Reference

This is the EmptyEpsilon script reference for this version of EmptyEpsilon.

By no means this is a guide to help you scripting, you should check emptyepsilon.org for the guide on scripting. As well as check the already existing scenario and ship data files on how to get started.

Some of the types in the parameters:

Note that most SpaceObjects directly switch to fully scanned, only SpaceShipss go through all the states.

Objects

Functions

FactionInfo

FactionInfo setName(string name)
Returns the object it was called on.
FactionInfo setLocaleName(string name)
Returns the object it was called on.
FactionInfo setGMColor(number r, number g, number b)
Returns the object it was called on.
FactionInfo setDescription(string description)
Returns the object it was called on.
FactionInfo setEnemy(FactionInfo other)
Returns the object it was called on.
FactionInfo setFriendly(FactionInfo other)
Returns the object it was called on.
boolean isValid()
Check if this is still looking at a valid object. Returns false when the objects that this variable references is destroyed.
FactionInfo destroy()
Removes this object from the game.
Returns the object it was called on.
typeName
Returns the class name of this object, this is not a function, but a direct member: if object.typeName == "Mine" then print("MINE!") end

ModelData

ModelData setName(string name)
Returns the object it was called on.
ModelData setMesh(string mesh_name)
Returns the object it was called on.
ModelData setTexture(string texture_name)
Returns the object it was called on.
ModelData setSpecular(string specular_texture_name)
Returns the object it was called on.
ModelData setIllumination(string illumination_texture_name)
Returns the object it was called on.
ModelData setRenderOffset(number mesh_offset_x, number mesh_offset_y, number mesh_offset_z)
Returns the object it was called on.
ModelData setScale(number scale)
Returns the object it was called on.
ModelData setRadius(number radius)
Returns the object it was called on.
ModelData setCollisionBox(number collision_box_x, number collision_box_y)
Returns the object it was called on.
ModelData addBeamPosition(number position_x, number position_y, number position_z)
Returns the object it was called on.
ModelData addTubePosition(number position_x, number position_y, number position_z)
Returns the object it was called on.
ModelData addEngineEmitor(number position_x, number position_y, number position_z, number color_r, number color_g, number color_b, number scale)
Returns the object it was called on.
ModelData addEngineEmitter(number position_x, number position_y, number position_z, number color_r, number color_g, number color_b, number scale)
Returns the object it was called on.
boolean isValid()
Check if this is still looking at a valid object. Returns false when the objects that this variable references is destroyed.
ModelData destroy()
Removes this object from the game.
Returns the object it was called on.
typeName
Returns the class name of this object, this is not a function, but a direct member: if object.typeName == "Mine" then print("MINE!") end

ScienceDatabase

ScienceDatabase setName(string name)
Returns the object it was called on.
string getName()
number getId()
number getParentId()
ScienceDatabase addEntry(string name)
ScienceDatabase getEntryByName(string name)
returns a child entry by its case-insensitive name
ScienceDatabase[] getEntries()
returns a table of all child entries in arbitrary order
boolean hasEntries()
returns true if this entry has child entries
ScienceDatabase addKeyValue(string key, string value)
add a new key-value pair in the center column of the database
Returns the object it was called on.
ScienceDatabase setKeyValue(string key, string value)
if an entry with this key exists already, its value will be changed. If not, the pair is created.
Returns the object it was called on.
string getKeyValue(string key)
get the value of the key value-pair with the given key. returns empty string when key does not exist.
table getKeyValues()
get all the key value pairs as a table. Warning: if there are duplicate keys only appear once with the last value.
ScienceDatabase removeKey(string key)
remove all key value pairs with the case-insensitive key value name
Returns the object it was called on.
ScienceDatabase setLongDescription(string text)
Returns the object it was called on.
string getLongDescription()
ScienceDatabase setImage(string path)
Returns the object it was called on.
string getImage()
ScienceDatabase setModelDataName(string model_data_name)
Returns the object it was called on.
boolean isValid()
Check if this is still looking at a valid object. Returns false when the objects that this variable references is destroyed.
ScienceDatabase destroy()
Removes this object from the game.
Returns the object it was called on.
typeName
Returns the class name of this object, this is not a function, but a direct member: if object.typeName == "Mine" then print("MINE!") end

Script

Object which can be used to create and run another script.
Other scripts have their own lifetime, update and init functions.
Scripts can destroy themselves (destroyScript()), or be destroyed by the main script.
Example: local script = Script():run("script.lua"); script:destroy();
boolean run(string filename)
Run a script with a certain filename
Script setVariable(string variable_name, string value)
Set a global variable in this script instance, this variable can be accessed in the main script.
Returns the object it was called on.
boolean isValid()
Check if this is still looking at a valid object. Returns false when the objects that this variable references is destroyed.
Script destroy()
Removes this object from the game.
Returns the object it was called on.
typeName
Returns the class name of this object, this is not a function, but a direct member: if object.typeName == "Mine" then print("MINE!") end

ScriptStorage

string get(string key)
Get a value from persistent script storage.
Requires the key as a string.
Returns the value as a JSON string.
Returns nothing if the key is not found.
Example: storage = getScriptStorage()
storage:get('key')
ScriptStorage set(string key, string value)
Set a value in persistent script storage.
Requires the key and value as strings.
Creates scriptstorage.json if it doesn't exist.
Example: storage = getScriptStorage()
storage:set('key', 'value')
Returns the object it was called on.
boolean isValid()
Check if this is still looking at a valid object. Returns false when the objects that this variable references is destroyed.
ScriptStorage destroy()
Removes this object from the game.
Returns the object it was called on.
typeName
Returns the class name of this object, this is not a function, but a direct member: if object.typeName == "Mine" then print("MINE!") end

ShipTemplate

ShipTemplates are created when EmptyEpsilon is started.
And used to fill the ship starting statistics, and other information.
ShipTemplate setName(string name)
Returns the object it was called on.
ShipTemplate setLocaleName(string name)
Returns the object it was called on.
ShipTemplate setClass(string class_name, string sub_class_name)
Set the class name, and subclass name for the ship. Used to divide ships into different classes.
Returns the object it was called on.
ShipTemplate setDescription(string description)
Set the description shown for this ship in the science database.
Returns the object it was called on.
ShipTemplate setType(TemplateType type)
Sets the type of template. Defaults to normal ships, so then it does not need to be set.
Example: template:setType("ship"), template:setType("playership"), template:setType("station")
Returns the object it was called on.
ShipTemplate hidden()
Hides this template from GM creation features and science database.
Hidden templates exists mainly for backwards compatibility of scripts.
Returns the object it was called on.
ShipTemplate setDefaultAI(string default_ai_name)
Set the default AI behaviour. EE has 3 types of AI coded into the game right now: "default", "fighter", "missilevolley"
Returns the object it was called on.
ShipTemplate setModel(string model_name)
Set the 3D model to be used for this template. The model referers to data set in the model_data.lua file.
Returns the object it was called on.
ShipTemplate setDockClasses(string classes...)
Supply a list of ship classes that can be docked to this ship. setDockClasses("Starfighter") will allow all small starfighter type ships to dock with this ship.
(Same as setExternalDockClasses)
Returns the object it was called on.
ShipTemplate setExternalDockClasses(string classes...)
Supply a list of ship classes that can be docked to this ship. setExternalDockClasses("Starfighter") will allow all small starfighter type ships to dock with this ship.
External docking will keep the ship attached to the side of this ship.
Returns the object it was called on.
ShipTemplate setInternalDockClasses(string classes...)
Supply a list of ship classes that can be docked to this ship. setInternalDockClasses("Starfighter") will allow all small starfighter type ships to dock with this ship.
Internal docking will hide the docked ship inside the other ship.
Returns the object it was called on.
ShipTemplate setEnergyStorage(number energy_amount)
Set the amount of energy available for this ship. Note that only player ships use energy. So setting this for anything else is useless.
Returns the object it was called on.
ShipTemplate setRepairCrewCount(number amount)
Returns the object it was called on.
ShipTemplate setBeam(number index, number arc, number direction, number range, number cycle_time, number damage)
Setup a beam weapon.
Returns the object it was called on.
ShipTemplate setBeamWeapon(number index, number arc, number direction, number range, number cycle_time, number damage)
Setup a beam weapon.
Returns the object it was called on.
ShipTemplate setBeamWeaponTurret(number index, number arc, number direction, number rotation_rate)
Setup a beam's turret.
Returns the object it was called on.
ShipTemplate setBeamTexture(number index, string texture)
Setup a beam weapon texture
Returns the object it was called on.
ShipTemplate setBeamWeaponEnergyPerFire(number index, number energy)
Returns the object it was called on.
ShipTemplate setBeamWeaponHeatPerFire(number index, number heat)
Returns the object it was called on.
ShipTemplate setTubes(number amount, number load_time)
Set the amount of missile tubes, limited to a maximum of 16.
Returns the object it was called on.
ShipTemplate setTubeLoadTime(number index, number load_time)
Returns the object it was called on.
ShipTemplate weaponTubeAllowMissle(number index, EMissileWeapons type)
Returns the object it was called on.
ShipTemplate weaponTubeDisallowMissle(number index, EMissileWeapons type)
Returns the object it was called on.
ShipTemplate setWeaponTubeExclusiveFor(number index, EMissileWeapons type)
Returns the object it was called on.
ShipTemplate setTubeDirection(number index, number direction)
Returns the object it was called on.
ShipTemplate setTubeSize(number index, EMissileSizes size)
Returns the object it was called on.
ShipTemplate setHull(number amount)
Set the amount of starting hull
Returns the object it was called on.
ShipTemplate setShields(number values...)
Set the shield levels, amount of parameters defines the amount of shields. (Up to a maximum of 8 shields)
Example: setShieldData(400) setShieldData(100, 80) setShieldData(100, 50, 50)
Returns the object it was called on.
ShipTemplate setSpeed(number impulse, number turn, number acceleration, number reverse_speed=nil, number reverse_acceleration=nil)
Set the impulse speed, rotation speed and impulse acceleration for this ship.
Optional fourth and fifth arguments are reverse speed and reverse acceeleration.
If not explicitely set, reverse speed and reverse acceleration are set to forward speed and acceleration
Compare SpaceShip:setImpulseMaxSpeed, :setRotationMaxSpeed, :setAcceleration.
Returns the object it was called on.
ShipTemplate setCombatManeuver(number boost, number strafe)
Sets the combat maneuver power of this ship.
Returns the object it was called on.
ShipTemplate setWarpSpeed(number warp)
Set the warp speed for warp level 1 for this ship. Setting this will indicate that this ship has a warpdrive. (normal value is 1000)
Returns the object it was called on.
ShipTemplate setSharesEnergyWithDocked(boolean enabled)
Set if this ship shares energy with docked ships. Example: template:setSharesEnergyWithDocked(false)
Returns the object it was called on.
ShipTemplate setRepairDocked(boolean enabled)
Set if this ship repairs docked ships. Example: template:setRepairDocked(false)
Returns the object it was called on.
ShipTemplate setRestocksScanProbes(boolean enabled)
Set if this ship restocks scan probes on docked ships. Example: template:setRestocksScanProbes(false)
Returns the object it was called on.
ShipTemplate setRestocksMissilesDocked(boolean enabled)
Set if this ship restores missiles on docked cpuships. Example template:setRestocksMissilesDocked(false)
Returns the object it was called on.
ShipTemplate setJumpDrive(boolean enabled)
Set if this ship has a jump drive. Example: template:setJumpDrive(true)
Returns the object it was called on.
ShipTemplate setJumpDriveRange(number min, number max)
Set this ship's minimum and maximum jump drive distances.
Example: template:setJumpDrive(5000.0, 50000.0)
Returns the object it was called on.
ShipTemplate setCloaking(boolean enabled)
Returns the object it was called on.
ShipTemplate setWeaponStorage(EMissileWeapons weapon, number amount)
Returns the object it was called on.
ShipTemplate addRoom(number position_x, number position_y, number size_x, number size_y)
Add an empty room to a ship template.
Rooms are shown on the engineering and damcon screens.
If a system room isn't accessible via other rooms connected by doors, that system
might not be repairable.
Rooms are placed on an integer x/y grid. The minimum size for a room is 1x1.
Accepts four parameters: the room's x coordinate, y coordinate, width, and height.
Example: template:addRoom(1, 2, 3, 4)
Returns the object it was called on.
ShipTemplate addRoomSystem(number position_x, number position_y, number size_x, number size_y, ESystem system)
Add a room containing a ship system to a ship template.
Rooms are shown on the engineering and damcon screens.
If a system doesn't have a room, or repair crews can't reach a system's room, it
might not be repairable.
Accepts five parameters: the room's x coordinate, y coordinate, width, height, and
the ship system as the string equivalent of an ESystem value.
Example: template:addRoomSystem(1, 2, 3, 4, "Reactor")
Returns the object it was called on.
ShipTemplate addDoor(number position_x, number position_y, boolean horizontal)
Add a door between rooms in a ship template.
Rooms are shown on the engineering and damcon screens.
If a system room doesn't have a door connecting it to other rooms, repair crews
might not be able to reach it for repairs.
Accepts three parameters: the door's x coordinate, y coordinate, and a Boolean
value for whether it's horizontal (true) or vertical (false).
Example: template:addDoor(2, 2, false)
Returns the object it was called on.
ShipTemplate setRadarTrace(string trace)
Returns the object it was called on.
ShipTemplate setLongRangeRadarRange(number range)
Returns the object it was called on.
ShipTemplate setShortRangeRadarRange(number range)
Returns the object it was called on.
ShipTemplate setImpulseSoundFile(string sound)
Returns the object it was called on.
ShipTemplate setCanScan(boolean enabled)
Returns the object it was called on.
ShipTemplate setCanHack(boolean enabled)
Returns the object it was called on.
ShipTemplate setCanDock(boolean enabled)
Returns the object it was called on.
ShipTemplate setCanCombatManeuver(boolean enabled)
Returns the object it was called on.
ShipTemplate setCanSelfDestruct(boolean enabled)
Returns the object it was called on.
ShipTemplate setCanLaunchProbe(boolean enabled)
Returns the object it was called on.
ShipTemplate copy(string new_name)
Return a new template with the given name, which is an exact copy of this template.
Used to make easy variations of templates.
boolean isValid()
Check if this is still looking at a valid object. Returns false when the objects that this variable references is destroyed.
ShipTemplate destroy()
Removes this object from the game.
Returns the object it was called on.
typeName
Returns the class name of this object, this is not a function, but a direct member: if object.typeName == "Mine" then print("MINE!") end

SpaceObject

SpaceObject is the base for every object which can be seen in space.
General properties can read and set for each object.
Each object has a position, rotation, and collision shape.
SpaceObject setPosition(number v_x, number v_y)
Sets this object's position on the map, in meters from the origin.
Requires two numeric values.
Example: obj:setPosition(x, y)
Returns the object it was called on.
number x, number y getPosition()
Gets this object's position on the map.
Returns x, y as meters from the origin.
Example: local x, y = obj:getPosition()
SpaceObject setRotation(number angle)
Sets this object's absolute rotation, in degrees.
Unlike setHeading, a value of 0 points to the right of the map.
The value can also be unbounded; it can be negative, or greater than
360 degrees.
Requires a numeric value.
Example: obj:setRotation(270)
Returns the object it was called on.
number getRotation()
Gets this object's absolute rotation.
setHeading and setRotation do not change the target heading of
PlayerSpaceships; use PlayerSpaceship's commandTargetRotation.
Returns a value in degrees.
Example: local rotation = obj:getRotation()
SpaceObject setHeading(number heading)
Sets this object's heading, in degrees ranging from 0 to 360.
Unlike setRotation, a value of 0 points to the top of the map.
Values that are negative or greater than 360 are are converted to values
within that range.
setHeading and setRotation do not change the target heading of
PlayerSpaceships; use PlayerSpaceship's commandTargetRotation.
Requires a numeric value.
Example: obj:setHeading(0)
Returns the object it was called on.
number getHeading()
Gets this object's heading, in degrees ranging from 0 to 360.
Returns a value in degrees.
Example: local heading = obj:getHeading(0)
number x, number y getVelocity()
Gets this object's directional velocity within 2D space.
Returns a pair of values x, y which are relative x, y coordinates from current position (2D velocity vector).
Example: local vx, vy = obj:getVelocity()
number getAngularVelocity()
Gets this object's rotational velocity within 2D space.
Returns a value in degrees/second.
Example: local angular_velocity = obj:getAngularVelocity()
SpaceObject setFaction(string faction_name)
Sets the faction to which this object belongs, by faction name.
Factions are defined by the FactionInfo() function, and default
factions are defined in scripts/factionInfo.lua.
Requires a faction name string as input.
Example: obj:setFaction("Human Navy")
Returns the object it was called on.
string getFaction()
Gets the name of the faction to which this object belongs.
Example: local faction = obj:getFaction()
string getLocaleFaction()
Gets the localized name of the faction to which this object belongs, for displaying to the players.
Example: local faction = obj:getLocaleFaction()
SpaceObject setFactionId(number faction_id)
Sets the faction to which this object belongs, by the faction's index
in the faction list.
Requires the index of a faction in the faction list.
Example: local faction_id = obj:getFactionId()
Returns the object it was called on.
number getFactionId()
Gets the faction list index for the faction to which this object
belongs. Can be used in combination with setFactionId() to ensure that
two objects have the same faction.
Example: other:setFactionId(obj:getFactionId())
boolean isEnemy(SpaceObject obj)
Gets the friend-or-foe status of the parameter's faction relative to
this object's faction.
Requires a SpaceObject.
Returns true if the parameter's faction is hostile to this object's.
Example: local is_enemy = obj:isEnemy()
boolean isFriendly(SpaceObject obj)
Requires a SpaceObject.
Returns true if the parameter's faction is friendly to this object's.
If an object is neither friendly nor enemy, it is neutral.
Example: local is_friendly = obj:isFriendly()
SpaceObject setCommsScript(string script_name)
Sets the communications script used when this object is hailed.
Accepts the filename of a Lua script as a string, or can be set to an
empty string to disable comms with this object.
In the script, `comms_source` (or `player`, deprecated) (PlayerSpaceship)
and `comms_target` (SpaceObject) are available.
Compare `setCommsFunction`.
Examples:
obj:setCommsScript("")
obj:setCommsScript("comms_custom_script.lua")
Defaults:
"comms_station.lua" (in `spaceStation.cpp`)
"comms_ship.lua" (in `cpuShip.cpp`)
Call `setCommsMessage` once and `addCommsReply` zero or more times in each dialogue.
Returns the object it was called on.
SpaceObject setCommsFunction(ScriptSimpleCallback callback)
Defines a callback function to use when handling hails, in lieu of any
current or default comms script.
For a detailed example, see scenario_53_escape.lua.
Requires a function to call back to when hailed.
The globals `comms_source` (PlayerSpaceship)
and `comms_target` (SpaceObject) are made available in the scenario script.
(Note: They remain as globals. As usual, such globals are not accessible in required files.)
Compare `setCommsScript`.
Example: obj:setCommsFunction(commsStation)
where commsStation is a function
calling `setCommsMessage` once and `addCommsReply` zero or more times.
Instead of using the globals, the callback can take two parameters.
Example: obj:setCommsFunction(function(comms_source, comms_target) ... end)
Returns the object it was called on.
SpaceObject setCallSign(string new_callsign)
Set this object's callsign. Objects are assigned random callsigns at
creation; this function overrides that default.
Requires a string value.
Example: obj:setCallSign("Epsilon")
Returns the object it was called on.
boolean sendCommsMessage(PlayerSpaceship target, string message)
Hails a PlayerSpaceship from this object. The players' comms station is
notified and can accept or deny the hail. If the hail is answered, the
specified message is displayed to the player.
Returns true when the hail is accepted.
Returns false when the target player cannot be hailed right now, for
example because it's already communicating with something else.
A message will be logged in the comms log about this.
Requires a target option and message. The message can be an empty
string.
Example: obj:sendCommsMessage(player, "Prepare to die")
boolean sendCommsMessageNoLog(PlayerSpaceship target, string message)
Hails a PlayerSpaceship from this object. The players' comms station is
notified and can accept or deny the hail. If the hail is answered, the
specified message is displayed to the player.
Returns true when the hail is accepted.
Returns false when the target player cannot be hailed right now, for
example because it's already communicating with something else.
Requires a target option and message. The message can be an empty
string.
Example: obj:sendCommsMessageNoLog(player, "Prepare to die")
boolean openCommsTo(PlayerSpaceship target)
As sendCommsMessage, but sends an empty string as the message. This will call the object's comms function.
Example: obj:openCommsTo(player)
string getCallSign()
Gets this object's callsign.
Returns a string.
Example: local callsign = obj:getCallSign()
boolean areEnemiesInRange(number range)
Gets whether any objects from a hostile faction are within a specific
radius of this object, in meters.
Requires a numeric value for the radius.
Returns true if hostiles are in range.
Example: obj:areEnemiesInRange(5000)
SpaceObject[] getObjectsInRange(number range)
Gets any objects within a specific radius of this object, in meters.
Requires a numeric value for the radius.
Returns a list of SpaceObjects within range.
Example: for _, obj_in_range in ipairs(obj:getObjectsInRange(5000)) ...
SpaceObject setReputationPoints(number amount)
Sets this object's faction reputation to the specified amount.
Requires a numeric value.
Example: obj:setReputationPoints(1000)
Returns the object it was called on.
boolean takeReputationPoints(number amount)
Deduct a specified amount of faction reputation points from this object.
Requires a numeric value.
Returns true if there are enough points to deduct the specified amount.
Returns false if there are not enough points, and does not deduct any.
Example: local took_reputation = obj:takeReputationPoints(1000)
SpaceObject addReputationPoints(number amount)
Adds a specified amount of faction reputation points to this object.
Requires a numeric value.
Example: obj:addReputationPoints(1000)
Returns the object it was called on.
string getSectorName()
Gets the name of the map sector, such as "A4", where this object is
located.
Returns a string value.
Example: obj:getSectorName()
number getReputationPoints()
Gets this object's current faction reputation points.
Returns an integer value.
Example: local reputation = obj:getReputationPoints();
SpaceObject takeDamage(number damage_amount, DamageInfo info)
Deals a specific amount of a specific type of damage to this object.
Requires a numeric value for the damage amount, and accepts an optional
DamageInfo type.
The DamageInfo parameter can be empty, or a string that indicates
whether to deal the default "energy" damage, "kinetic" damage, or "emp"
damage, and can optionally be followed by the location of the damage's
origin (for instance, to damage the correct shield on ships).
SpaceObjects by default do not implement damage, instead leaving it to
be overridden by specialized subclasses.
Examples:
amount, type, x, y
obj:takeDamage(20, "emp", 1000, 0)
obj:takeDamage(20)
Returns the object it was called on.
SpaceObject setDescriptions(string unscanned_description, string scanned_description)
Sets this object's description in unscanned and scanned states. These
descriptions are displayed when this object is targeted from a ship's
Science station.
Requires two string values, one for the descriptions when unscanned
and another for when it has been scanned.
Example:
obj:setDescriptions([[A refitted Atlantis X23...]], [[It's a trap!]])
Returns the object it was called on.
SpaceObject setDescription(string description)
As setDescriptions, but sets the same description for both unscanned
and scanned states.
Requires a string value.
Example: obj:setDescription([[A refitted Atlantis X23 for more ...]])
Returns the object it was called on.
SpaceObject setDescriptionForScanState(EScannedState state, string description)
Sets a description for a specific EScannedState. String equivalents for
EScannedState are defined in the convert<EScannedState> function of
src/spaceObjects/spaceObject.cpp.
Requires a string-equivalent EScannedState and a string description.
Example:
obj:setDescriptionForScanState("friendorfoeidentified", [[This...]])
Returns the object it was called on.
string getDescription(EScannedState state)
Gets this object's description.
Accepts an optional string-equivalent EScannedState.
Returns a string.
Examples:
obj:getDescription()
obj:getDescription("friendorfoeidentified")
SpaceObject setRadarSignatureInfo(number grav, number elec, number bio)
Sets this object's radar signature, which creates noise on the Science
station's raw radar signal ring.
Certain SpaceObject types might modify their signatures using this value
as a baseline. Default values also depend on the SpaceObject type.
Requires numeric values ranging from 0.0 to 1.0 for the gravitational,
electrical, and biological radar bands.
Example: obj:setRadarSignatureInfo(0.0, 0.5, 1.0)
Returns the object it was called on.
number getRadarSignatureGravity()
Gets this object's component values from its radar signature.
Returns a numeric value between 0.0 and 1.0; larger and negative values
are possible, but currently have no visual effect on the bands.
Examples:
local grav_band = obj:getRadarSignatureGravity()
local elec_band = obj:getRadarSignatureElectrical()
local bio_band = obj:getRadarSignatureBiological()
number getRadarSignatureElectrical()
number getRadarSignatureBiological()
SpaceObject setScanningParameters(number complexity, number depth)
Sets this object's scanning complexity (number of bars in the scanning
minigame) and depth (number of scanning minigames to complete).
Also clears the scanned state.
Requires two integer values.
Example: obj:setScanningParameters(2, 3)
Returns the object it was called on.
number scanningComplexity(SpaceObject target)
Gets the scanning complexity for the parameter object.
Requires a SpaceObject.
Returns an integer value.
Example: local scan_complexity = obj:scanningComplexity(obj)
number scanningChannelDepth(SpaceObject target)
Gets the scanning depth for the parameter object.
Requires a SpaceObject.
Returns an integer value.
Example: local scan_depth = obj:scanningChannelDepth(obj)
SpaceObject setScanned(boolean scanned)
Sets whether all factions consider this object as having been scanned.
Requires a boolean value. If false, all factions treat this object as
unscanned; if true, all factions treat this object as fully scanned.
Example: obj:setScanned(true)
Returns the object it was called on.
boolean isScanned()
[DEPRECATED]
Gets whether this object has been scanned.
Use isScannedBy or isScannedByFaction instead.
boolean isScannedBy(SpaceObject obj)
Gets whether the parameter object has successfully scanned this object.
Requires a SpaceObject.
Returns a boolean value.
Example: obj:isScannedBy(other)
SpaceObject setScannedByFaction(string faction_name, boolean scanned)
Sets whether a specific faction considers this object as having been
scanned.
Requires a faction name string value and a boolean value.
Example: obj:setScannedByFaction("Human Navy", false)
Returns the object it was called on.
boolean isScannedByFaction(string faction)
Gets whether the parameter faction has successfully scanned this object.
Requires a faction name string value.
Returns a boolean value.
Example: obj:isScannedByFaction("Human Navy")
SpaceObject onDestroyed(ScriptSimpleCallback callback)
Returns the object it was called on.
boolean isValid()
Check if this is still looking at a valid object. Returns false when the objects that this variable references is destroyed.
SpaceObject destroy()
Removes this object from the game.
Returns the object it was called on.
typeName
Returns the class name of this object, this is not a function, but a direct member: if object.typeName == "Mine" then print("MINE!") end

Artifact

An artifact.
Can be used for mission scripting.
Subclass of: SpaceObject
Artifact setModel(string name)
Set the 3D model used for this artifact.
Example: setModel("artifact6"), setModel("shield_generator"), setModel("ammo_box").
Check model_data.lua for all possible options.
Returns the object it was called on.
Artifact explode()
Have this object explode with a visual explosion. The Artifact is destroyed by this action.
Returns the object it was called on.
Artifact allowPickup(boolean allow)
Set if this artifact can be picked up or not. When it is picked up, this artifact will be destroyed.
Returns the object it was called on.
Artifact onCollision(ScriptSimpleCallback callback)
Set a function that will be called every tick when a SpaceObject is
colliding with the artifact.
Passes the artifact and colliding SpaceObject.
Example:
artifact:onCollision(function(artifact, collider) print("Collision occurred") end)
Returns the object it was called on.
Artifact onPlayerCollision(ScriptSimpleCallback callback)
Set a function that will be called every tick when a PlayerSpaceship is
colliding with the artifact.
Passes the artifact and colliding PlayerSpaceship.
Example:
artifact:onCollision(function(artifact, player) print("Collision occurred") end)
Returns the object it was called on.
Artifact onPickUp(ScriptSimpleCallback callback)
Set a function that will be called once when a PlayerSpaceship collides
with the artifact while allowPickup is enabled. The artifact is
subsequently destroyed.
Passes the artifact and colliding PlayerSpaceship.
Example:
artifact:onPickUp(function(artifact, player) print("Artifact retrieved") end)
Returns the object it was called on.
Artifact onPickup(ScriptSimpleCallback callback)
Alias of onPickUp.
Returns the object it was called on.
Artifact setSpin(number spin=0.0)
Let the artifact rotate. For reference, normal asteroids in the game have spins between 0.1 and 0.8.
Returns the object it was called on.
Artifact setRadarTraceIcon(string icon)
Set the icon to be used for this artifact on the radar.
For example, artifact:setRadarTraceIcon("arrow.png") will show an arrow instead of a dot for this artifact.
Returns the object it was called on.
Artifact setRadarTraceScale(number scale)
Scales the radar trace. Setting to 0 restores to standard autoscaling.
Setting to 1 is needed for mimicking ship traces.
Returns the object it was called on.
Artifact setRadarTraceColor(number r, number g, number b)
Sets the color of the radar trace.
Example: 255,200,100 for mimicking asteroids.
Returns the object it was called on.

Asteroid

An asteroid in space. Which you can fly into and hit. Will do damage.
Subclass of: SpaceObject
Asteroid setSize(number size)
Set the radius of this asteroid
The default radius for an asteroid is between 110 and 130
Example: Asteroid():setSize(50)
Returns the object it was called on.
number getSize()
Gets the current radius of this asteroid
Example: local size=Asteroid():getSize()

BeamEffect

BeamEffect is a beam weapon fire effect that will fade after 1 seond
Example: BeamEffect():setSource(player, 0, 0, 0):setTarget(enemy_ship, 0, 0)
Subclass of: SpaceObject
BeamEffect setSource(SpaceObject source, number offset_x, number offset_y, number offset_z)
Returns the object it was called on.
BeamEffect setTarget(SpaceObject target, number hitLocation_x, number hitLocation_y)
Returns the object it was called on.
BeamEffect setTexture(string texture)
Returns the object it was called on.
BeamEffect setBeamFireSound(string sound)
Returns the object it was called on.
BeamEffect setBeamFireSoundPower(number power)
Returns the object it was called on.
BeamEffect setDuration(number duration)
Returns the object it was called on.
BeamEffect setRing(boolean ring)
Returns the object it was called on.

BlackHole

A blackhole has a 5km radius where it pulls in all near objects. At the center of the black hole everything gets a lot of damage.
Which will lead to the eventual destruction of said object.
Subclass of: SpaceObject

ElectricExplosionEffect

ElectricExplosionEffect is a visible electrical explosion, as seen from EMP missiles
Example: ElectricExplosionEffect():setPosition(500,5000):setSize(20)
Subclass of: SpaceObject
ElectricExplosionEffect setSize(number size)
Returns the object it was called on.
ElectricExplosionEffect setOnRadar(boolean on_radar)
Returns the object it was called on.

ExplosionEffect

ExplosionEffect is a visible explosion, like from nukes, missiles, ship destruction, etc
Example: ExplosionEffect():setPosition(500,5000):setSize(20)
Subclass of: SpaceObject
ExplosionEffect setSize(number size)
Returns the object it was called on.
ExplosionEffect setOnRadar(boolean on_radar)
Returns the object it was called on.

Mine

A mine object. Simple, effective, deadly.
Subclass of: SpaceObject
SpaceObject getOwner()
Mine onDestruction(ScriptSimpleCallback callback)
Returns the object it was called on.

MissileWeapon

Base class for every missile (mines are not missiles)
You cannot create a missile in script with this class, use derived classes
like HomingMissile, HVLI etc.
Subclass of: SpaceObject
SpaceObject getOwner()
Get the missile's owner's object.
SpaceObject getTarget()
Get the missile's target object.
MissileWeapon setTarget(SpaceObject target)
Must be an existing target, else does nothing. It does not check if really targetable or not.
Returns the object it was called on.
number getLifetime()
Lifetime is a number in seconds
MissileWeapon setLifetime(number lifetime)
Lifetime is a number in seconds
Returns the object it was called on.
EMissileSizes getMissileSize()
Set the missile size as for tube size.
Valid sizes: see EMissileSizes
MissileWeapon setMissileSize(EMissileSizes missile_size)
Get the missile size as for tube size.
Valid sizes: see EMissileSizes
Returns the object it was called on.

EMPMissile

EMP missile
Subclass of: MissileWeapon

HVLI

HVLI missile
Subclass of: MissileWeapon

HomingMissile

Homing missile
Subclass of: MissileWeapon

Nuke

Nuke missile
Subclass of: MissileWeapon

Nebula

Nebulae block long-range radar in a 5U range.
Subclass of: SpaceObject

Planet

A planet.
Subclass of: SpaceObject
Planet setPlanetAtmosphereColor(number r, number g, number b)
Returns the object it was called on.
Planet setPlanetAtmosphereTexture(string texture_name)
Returns the object it was called on.
Planet setPlanetSurfaceTexture(string texture_name)
Returns the object it was called on.
Planet setPlanetCloudTexture(string texture_name)
Returns the object it was called on.
number getPlanetRadius()
Planet setPlanetRadius(number size)
Returns the object it was called on.
number getCollisionSize()
Planet setPlanetCloudRadius(number size)
Returns the object it was called on.
Planet setDistanceFromMovementPlane(number distance_from_movement_plane)
Returns the object it was called on.
Planet setAxialRotationTime(number time)
Returns the object it was called on.
Planet setOrbit(SpaceObject target, number orbit_time)
Returns the object it was called on.

ScanProbe

A scan probe.
Subclass of: SpaceObject
ScanProbe setSpeed(number probe_speed)
Set the probe's speed. A value of 1000 = 1U/second.
Probes move at a fixed rate of speed and ignore physics.
Requires a float value. The default vaule is 1000.
Example: probe:setSpeed(2000)
Returns the object it was called on.
number getSpeed()
Get the probe's speed. A value of 1000 = 1U/second.
Returns a float value.
Example: local speed = probe:getSpeed()
ScanProbe setLifetime(number lifetime)
Set the probe's remaining lifetime, in seconds.
The default initial lifetime is 10 minutes.
Example: probe:setLifetime(60 * 5)
Returns the object it was called on.
number getLifetime()
Get the probe's remaining lifetime.
Example: local lifetime = probe:getLifetime()
ScanProbe setTarget(number target_x, number target_y)
Set the probe's target coordinates.
Example: probe:setTarget(1000, 5000)
Returns the object it was called on.
number x, number y getTarget()
Get the probe's target coordinates.
Example: local targetX, targetY = probe:getTarget()
ScanProbe setOwner(SpaceObject owner)
Set the probe's owner SpaceObject.
Requires a SpaceObject.
Example: probe:setOwner(owner_ship)
Returns the object it was called on.
SpaceObject getOwner()
Get the probe's owner SpaceObject.
Example: local owner_ship = probe:getOwner()
ScanProbe onArrival(ScriptSimpleCallback callback)
Callback when the probe arrives to its target coordinates.
Passes the probe and position as arguments to the callback.
Example: probe:onArrival(probeArrived)
Returns the object it was called on.
ScanProbe onExpiration(ScriptSimpleCallback callback)
Callback when the probe's lifetime expires.
Passes the probe as an argument to the callback.
Example: probe:onExpiration(probeExpired)
Returns the object it was called on.
ScanProbe onDestruction(ScriptSimpleCallback callback)
Callback when the probe is destroyed by damage.
Passes the probe and instigator as arguments to the callback.
Example: probe:onDestruction(probeDestroyed)
Returns the object it was called on.

ShipTemplateBasedObject

Subclass of: SpaceObject
ShipTemplateBasedObject setTemplate(string template_name)
Set the template to be used for this ship or station. Templates define hull/shields/looks etc.
Examples:
CpuShip():setTemplate("Phobos T3")
PlayerSpaceship():setTemplate("Phobos M3P")
SpaceStation():setTemplate("Large Station")
WARNING: Using a string that is not a valid template name lets the game crash! This is case-sensitive.
See `scripts/shipTemplates.lua` for the existing templates.
Returns the object it was called on.
ShipTemplateBasedObject setShipTemplate(string template_name)
[Depricated]
Returns the object it was called on.
ShipTemplateBasedObject setTypeName(string type_name)
Set the class name of this object. Normally the class name is copied from the template name (Ex "Cruiser") but you can override it with this function.
Returns the object it was called on.
string getTypeName()
number getHull()
Get the current amount of hull
number getHullMax()
Get the maximum hull value
ShipTemplateBasedObject setHull(number amount)
Set the current hull value, note that setting this to 0 does not destroy the station.
Returns the object it was called on.
ShipTemplateBasedObject setHullMax(number amount)
Set the maximum amount of hull for this station. Stations never repair hull damage, so this only effects the percentage displays
Returns the object it was called on.
ShipTemplateBasedObject setCanBeDestroyed(boolean enabled)
Set whether the object can be destroyed.
Requires a Boolean value.
Example: ship:setCanBeDestroyed(true)
Returns the object it was called on.
boolean getCanBeDestroyed()
Get whether the object can be destroyed.
Returns a Boolean value.
Example: ship:getCanBeDestroyed()
number getShieldLevel(number index)
Get the specified shield's current level.
Requires an integer index value.
Returns a float value.
Example to get shield level on front shields of a ship with two shields:
ship:getShieldLevel(0)
Rear shields: ship:getShieldLevel(1)
number getShieldCount()
Get the number of shields on this object.
For example, a ship with 1 shield count has a single shield covering
all angles, a ship with 2 covers front and back, etc.
Returns an integer count.
Example: ship:getShieldCount()
number getShieldMax(number index)
Get the maxium shield level.
ShipTemplateBasedObject setShields(number amounts...)
Set the current amount of shields.
Returns the object it was called on.
ShipTemplateBasedObject setShieldsMax(number amounts...)
Set the maximum shield level, amount of parameters defines the amount of shields. (Up to a maximum of 8 shields). Note that this does low the current shield level when the max becomes lower, but it does not increase the shield level.
A seperate call to setShield is needed for that.
Returns the object it was called on.
ShipTemplateBasedObject setRadarTrace(string trace)
Set the icon to be used for this object on the radar.
For example, station:setRadarTrace("arrow.png") will show an arrow instead of a dot for this station.
Returns the object it was called on.
ShipTemplateBasedObject setImpulseSoundFile(string sound)
Set the sound file to be used for this object's impulse engines.
Requires a string for a filename relative to the resources path.
Example: setImpulseSoundFile("engine.wav")
Returns the object it was called on.
boolean getShieldsActive()
Are the shields online or not. Currently always returns true except for player ships, as only players can turn off shields.
boolean getSharesEnergyWithDocked()
ShipTemplateBasedObject setSharesEnergyWithDocked(boolean enabled)
Returns the object it was called on.
boolean getRepairDocked()
ShipTemplateBasedObject setRepairDocked(boolean enabled)
Returns the object it was called on.
boolean getRestocksScanProbes()
ShipTemplateBasedObject setRestocksScanProbes(boolean enabled)
Returns the object it was called on.
boolean getRestocksMissilesDocked()
ShipTemplateBasedObject setRestocksMissilesDocked(boolean enabled)
Returns the object it was called on.
number getLongRangeRadarRange()
number getShortRangeRadarRange()
ShipTemplateBasedObject setLongRangeRadarRange(number range)
Returns the object it was called on.
ShipTemplateBasedObject setShortRangeRadarRange(number range)
Returns the object it was called on.
number getFrontShield()
[Depricated]
number getFrontShieldMax()
[Depricated]
ShipTemplateBasedObject setFrontShield(number amount)
[Depricated]
Returns the object it was called on.
ShipTemplateBasedObject setFrontShieldMax(number amount)
[Depricated]
Returns the object it was called on.
number getRearShield()
[Depricated]
number getRearShieldMax()
[Depricated]
ShipTemplateBasedObject setRearShield(number amount)
[Depricated]
Returns the object it was called on.
ShipTemplateBasedObject setRearShieldMax(number amount)
[Depricated]
Returns the object it was called on.
ShipTemplateBasedObject onTakingDamage(ScriptSimpleCallback callback)
Set a function that will be called if the object is taking damage.
First argument given to the function will be the object taking damage, the second the instigator SpaceObject (or nil).
Returns the object it was called on.
ShipTemplateBasedObject onDestruction(ScriptSimpleCallback callback)
Set a function that will be called if the object is destroyed by taking damage.
First argument given to the function will be the object taking damage, the second the instigator SpaceObject that gave the final blow (or nil).
Returns the object it was called on.

SpaceShip

Subclass of: ShipTemplateBasedObject
boolean isFriendOrFoeIdentified()
[DEPRECATED]
boolean isFullyScanned()
[DEPRECATED]
boolean isFriendOrFoeIdentifiedBy(SpaceObject other)
boolean isFullyScannedBy(SpaceObject other)
boolean isFriendOrFoeIdentifiedByFaction(number faction_id)
boolean isFullyScannedByFaction(number faction_id)
boolean isDocked(SpaceObject target)
SpaceObject getDockedWith()
EDockingState getDockingState()
SpaceObject getTarget()
number getWeaponStorage(EMissileWeapons weapon)
number getWeaponStorageMax(EMissileWeapons weapon)
SpaceShip setWeaponStorage(EMissileWeapons weapon, number amount)
Returns the object it was called on.
SpaceShip setWeaponStorageMax(EMissileWeapons weapon, number amount)
Returns the object it was called on.
number getShieldsFrequency()
SpaceShip setShieldsFrequency(number freq)
Returns the object it was called on.
number getBeamFrequency()
number getMaxEnergy()
SpaceShip setMaxEnergy(number amount)
Returns the object it was called on.
number getEnergy()
SpaceShip setEnergy(number amount)
Returns the object it was called on.
boolean hasSystem(ESystem system)
number getSystemHackedLevel(ESystem system)
SpaceShip setSystemHackedLevel(ESystem system, number hacked_level)
Returns the object it was called on.
number getSystemHealth(ESystem system)
SpaceShip setSystemHealth(ESystem system, number health)
Returns the object it was called on.
number getSystemHealthMax(ESystem system)
SpaceShip setSystemHealthMax(ESystem system, number health_max)
Returns the object it was called on.
number getSystemHeat(ESystem system)
SpaceShip setSystemHeat(ESystem system, number heat)
Returns the object it was called on.
number getSystemHeatRate(ESystem system)
SpaceShip setSystemHeatRate(ESystem system, number rate)
Returns the object it was called on.
number getSystemPower(ESystem system)
SpaceShip setSystemPower(ESystem system, number power)
Returns the object it was called on.
number getSystemPowerRate(ESystem system)
SpaceShip setSystemPowerRate(ESystem system, number rate)
Returns the object it was called on.
number getSystemPowerFactor(ESystem system)
SpaceShip setSystemPowerFactor(ESystem system, number factor)
Returns the object it was called on.
number getSystemCoolant(ESystem system)
SpaceShip setSystemCoolant(ESystem system, number coolant)
Returns the object it was called on.
number getSystemCoolantRate(ESystem system)
SpaceShip setSystemCoolantRate(ESystem system, number rate)
Returns the object it was called on.
Speeds getImpulseMaxSpeed()
Get multiple results, first one is forward speed and second one is reverse speed.
ex : forward,reverse = getImpulseMaxSpeed() (you can also use select or _ to get only reverse speed)
You can also only get forward speed, reverse speed will just be discarded :
forward = getImpulseMaxSpeed()
SpaceShip setImpulseMaxSpeed(number forward_speed, number reverse_speed=nil)
Sets max speed.
If called with only one argument, sets forward and reverse speed to equal values.
If called with two arguments, first one is forward speed and second one is reverse speed.
Returns the object it was called on.
number getRotationMaxSpeed()
SpaceShip setRotationMaxSpeed(number speed)
Returns the object it was called on.
Speeds getAcceleration()
Get multiple resulsts, first one is forward acceleration and second one is reverse acceleration.
ex : forward, reverse = getAcceleration (you can also use select or _ to get only reverse speed)
You can also only get forward speed, reverse speed will just be discarded :
forward = getAcceleration()
SpaceShip setAcceleration(number acceleration, number reverse_acceleration=nil)
Sets acceleration.
If called with one argument, sets forward and reverse acceleration to equal values.
If called with two arguments, first one is forward acceleration and second one is reverse acceleration.
Returns the object it was called on.
SpaceShip setCombatManeuver(number boost, number strafe)
Returns the object it was called on.
boolean hasJumpDrive()
SpaceShip setJumpDrive(boolean has_jump)
Returns the object it was called on.
SpaceShip setJumpDriveRange(number min, number max)
Returns the object it was called on.
SpaceShip setJumpDriveCharge(number charge)
sets the current jump range charged.
ships will be able to jump when this is equal to their max jump drive range.
Example ship:setJumpDriveCharge(50000)
Returns the object it was called on.
number getJumpDriveCharge()
returns the current amount of jump charged.
Example ship:getJumpDriveCharge()
number getJumpDelay()
boolean hasWarpDrive()
SpaceShip setWarpDrive(boolean has_warp)
Returns the object it was called on.
SpaceShip setWarpSpeed(number speed)
Set the warp speed for this ship's warp level 1.
Setting this is equivalent to also setting setWarpDrive(true).
If a value isn't specified in the ship template, the default is 1000.
Requires a numeric value.
Example: ship:setWarpSpeed(500);
Returns the object it was called on.
number getWarpSpeed()
number getBeamWeaponArc(number index)
number getBeamWeaponDirection(number index)
number getBeamWeaponRange(number index)
number getBeamWeaponTurretArc(number index)
number getBeamWeaponTurretDirection(number index)
number getBeamWeaponCycleTime(number index)
number getBeamWeaponDamage(number index)
number getBeamWeaponEnergyPerFire(number index)
number getBeamWeaponHeatPerFire(number index)
SpaceShip setBeamWeapon(number index, number arc, number direction, number range, number cycle_time, number damage)
Returns the object it was called on.
SpaceShip setBeamWeaponTurret(number index, number arc, number direction, number rotation_rate)
Returns the object it was called on.
SpaceShip setBeamWeaponTexture(number index, string texture)
Returns the object it was called on.
SpaceShip setBeamWeaponEnergyPerFire(number index, number energy)
Returns the object it was called on.
SpaceShip setBeamWeaponHeatPerFire(number index, number heat)
Returns the object it was called on.
SpaceShip setBeamWeaponArcColor(number index, number r, number g, number b, number fire_r, number fire_g, number fire_b)
Returns the object it was called on.
SpaceShip setBeamWeaponDamageType(number index, EDamageType type)
Returns the object it was called on.
SpaceShip setWeaponTubeCount(number amount)
Returns the object it was called on.
number getWeaponTubeCount()
EMissileWeapons getWeaponTubeLoadType(number index)
SpaceShip weaponTubeAllowMissle(number index, EMissileWeapons type)
Returns the object it was called on.
SpaceShip weaponTubeDisallowMissle(number index, EMissileWeapons type)
Returns the object it was called on.
SpaceShip setWeaponTubeExclusiveFor(number index, EMissileWeapons type)
Returns the object it was called on.
SpaceShip setWeaponTubeDirection(number index, number direction)
Returns the object it was called on.
SpaceShip setTubeSize(number index, EMissileSizes size)
Set the tube size
Example: ship:setTubeSize(0,"small")
Valid Sizes: "small" "medium" "large"
Returns the object it was called on.
EMissileSizes getTubeSize(number index)
Returns the size of the tube
Example: local size = ship:getTubeSize(0)
number getTubeLoadTime(number index)
SpaceShip setTubeLoadTime(number index, number time)
Returns the object it was called on.
SpaceShip setRadarTrace(string trace)
Set the icon to be used for this ship on the radar.
For example, ship:setRadarTrace("blip.png") will show a dot instead of an arrow for this ship.
Note: Icon is only shown after scanning, before the ship is scanned it is always shown as an arrow.
Returns the object it was called on.
number getDynamicRadarSignatureGravity()
Get the dynamic radar signature values for each component band.
Returns a float.
Example: obj:getDynamicRadarSignatureGravity()
number getDynamicRadarSignatureElectrical()
number getDynamicRadarSignatureBiological()
SpaceShip addBroadcast(number threshold, string message)
Returns the object it was called on.
SpaceShip setScanState(EScannedState scanned)
Set the scan state of this ship for every faction.
Returns the object it was called on.
SpaceShip setScanStateByFaction(string faction_name, EScannedState scanned)
Set the scane state of this ship for a particular faction.
Returns the object it was called on.

CpuShip

CpuShips are AI controlled ships.
They can get different orders.
Example: CpuShip():setTemplate("Fighter"):setPosition(random(-10000, 10000), random(0, 3000)):setFaction("Human Navy"):orderRoaming():setScanned(true)
Subclass of: SpaceShip
CpuShip setAI(string new_ai)
Switch the AI to a different state. AI state can be set per ship,
defined in the shipTemplate, or left to "default". AI state is distinct
from orders, and determines the AI's tactics and responses in combat.
Valid values are "default", "missileVolley", "fighter", and "evasion".
"missileVolley" prefers lining up missile attacks from long range.
"fighter" prefers attacking at close range with strafing maneuvers.
"evasion" maintains distance from enemy weapons and evades attacks.
Example: enemy:setAI("fighter")
Returns the object it was called on.
CpuShip orderIdle()
Order this ship to hold the current position. Do nothing; don't attack.
Orders are distinct from AI state, and determines what the ship's
current objectives.
Example: enemy:orderIdle()
Returns the object it was called on.
CpuShip orderRoaming()
Order this ship to roam and engage at will, without a specific target.
Example: enemy:orderRoaming()
Returns the object it was called on.
CpuShip orderRetreat(SpaceObject object)
Order this ship to dock at [order_target] to re-stock missiles and
repair its hull. If neccessary, roam to locate a dockable target.
Continue roaming after repairs and re-stocking, or if no dockable
target is found.
Requires a target ShipTemplateBasedObject that supports docking.
Example: enemy:orderRetreat(spaceStation)
Returns the object it was called on.
CpuShip orderStandGround()
Order this ship to hold the current position. Do not retreat, and
attack nearby targets.
Example: enemy:orderStandGround()
Returns the object it was called on.
CpuShip orderDefendLocation(number position_x, number position_y)
Order this ship to defend [order_target_location] against enemies that
get too close.
Requires x,y coordinates to defend.
Example: enemy:orderDefendLocation(500, 1000)
Returns the object it was called on.
CpuShip orderDefendTarget(SpaceObject object)
Order this ship to defend [order_target] against enemies that get too
close. Default to AI_Roaming if the defense target is destroyed.
Requires a SpaceObject to defend.
Example: enemy:orderDefendTarget(enemy2)
Returns the object it was called on.
CpuShip orderFlyFormation(SpaceObject object, number offset_x, number offset_y)
Order this ship to follow [order_target] from a specified distance, and
to use [order_target]'s target if one is selected.
Requires a SpaceObject to serve as the formation's flight leader, and a
float value for the offset distance to maintain.
Example: enemy:orderFlyFormation(enemy2, 500)
Returns the object it was called on.
CpuShip orderFlyTowards(number target_x, number target_y)
Order this ship to move towards [order_target_location] and attack
enemies that get too close during transit. Disengage from combat and
continue towards the destination if enemies are too distant.
Requires x,y coordinates to move towards.
Example: enemy:orderFlyTowards(500, 1000)
Returns the object it was called on.
CpuShip orderFlyTowardsBlind(number target_x, number target_y)
Order this ship to move towards [order_target_location] while ignoring
all enemies. Don't attack.
Requires x,y coordinates to move towards.
Example: enemy:orderFlyTowardsBlind(500, 1000)
Returns the object it was called on.
CpuShip orderAttack(SpaceObject object)
Order this ship to attack the specified [order_target].
Requires a SpaceObject to attack.
Example: enemy:orderAttack(player)
Returns the object it was called on.
CpuShip orderDock(SpaceObject object)
Order this ship to dock with the specified target, if possible.
Requires a dockable SpaceObject to dock with.
Example: enemy:orderDock(spaceStation)
Returns the object it was called on.
EAIOrder getOrder()
Get this ship's current orders.
Returns a string representation of the ship's current EAIOrder value.
Example: local ship_orders = enemy:getOrder()
number x, number y getOrderTargetLocation()
Get the target location of this ship's current orders.
Returns the targeted x,y coordinates, or 0,0 if not defined.
Example: local x, y = enemy:getOrderTargetLocation()
SpaceObject getOrderTarget()
Get the target SpaceObject of this ship's current orders.
Returns the targeted SpaceObject.
Example: local target = enemy:getOrderTarget()

PlayerSpaceship

Subclass of: SpaceShip
number x, number y getWaypoint(number index)
Returns the sf::Vector2f of a specific waypoint set by this ship.
Takes the index of the waypoint as its parameter.
number getWaypointCount()
Returns the total number of this ship's active waypoints.
EAlertLevel getAlertLevel()
Returns the ship's EAlertLevel.
PlayerSpaceship setShieldsActive(boolean active)
Sets whether this ship's shields are raised or lowered.
Takes a Boolean value.
Returns the object it was called on.
PlayerSpaceship addToShipLog(string message, Color color)
Adds a message to the ship's log. Takes a string as the message and a
color.
Returns the object it was called on.
PlayerSpaceship transferPlayersToShip(PlayerSpaceship other_ship)
Move all players connected to this ship to the same stations on a
different PlayerSpaceship. If the target isn't a PlayerSpaceship, this
function does nothing.
This can be used in scenarios to change the crew's ship.
Returns the object it was called on.
PlayerSpaceship transferPlayersAtPositionToShip(ECrewPosition position, PlayerSpaceship other_ship)
Transfers only the crew members who fill a specific station to another
PlayerSpaceship.
Returns the object it was called on.
boolean hasPlayerAtPosition(ECrewPosition position)
Returns true if a station is occupied by a player, and false if not.
boolean isCommsInactive()
boolean isCommsOpening()
boolean isCommsBeingHailed()
boolean isCommsBeingHailedByGM()
boolean isCommsFailed()
boolean isCommsBroken()
boolean isCommsClosed()
boolean isCommsChatOpen()
boolean isCommsChatOpenToGM()
boolean isCommsChatOpenToPlayer()
boolean isCommsScriptOpen()
PlayerSpaceship setEnergyLevel(number amount)
Returns the object it was called on.
PlayerSpaceship setEnergyLevelMax(number amount)
Returns the object it was called on.
number getEnergyLevel()
number getEnergyLevelMax()
number getEnergyShieldUsePerSecond()
PlayerSpaceship setEnergyShieldUsePerSecond(number rate)
Returns the object it was called on.
number getEnergyWarpPerSecond()
PlayerSpaceship setEnergyWarpPerSecond(number rate)
Returns the object it was called on.
PlayerSpaceship setMaxCoolant(number coolant)
Set the maximum coolant available to engineering. Default is 10.
Returns the object it was called on.
number getMaxCoolant()
PlayerSpaceship setScanProbeCount(number amount)
Returns the object it was called on.
number getScanProbeCount()
PlayerSpaceship setMaxScanProbeCount(number amount)
Returns the object it was called on.
number getMaxScanProbeCount()
PlayerSpaceship addCustomButton(ECrewPosition position, string name, string caption, ScriptSimpleCallback callback, number order=nil)
add a custom Button to the according station. Use order to sort (shared with custom info).
Returns the object it was called on.
PlayerSpaceship addCustomInfo(ECrewPosition position, string name, string caption, number order=nil)
add a custom Info Label to the according station. Use order to sort (shared with custom button).
Returns the object it was called on.
PlayerSpaceship addCustomMessage(ECrewPosition position, string name, string caption)
Returns the object it was called on.
PlayerSpaceship addCustomMessageWithCallback(ECrewPosition position, string name, string caption, ScriptSimpleCallback callback)
Returns the object it was called on.
PlayerSpaceship removeCustom(string name)
Returns the object it was called on.
ESystem getBeamSystemTarget()
string getBeamSystemTargetName()
Gets the name of the target system, instead of the ID
PlayerSpaceship commandTargetRotation(number target)
Returns the object it was called on.
PlayerSpaceship commandImpulse(number target)
Returns the object it was called on.
PlayerSpaceship commandWarp(number target)
Returns the object it was called on.
PlayerSpaceship commandJump(number distance)
Returns the object it was called on.
PlayerSpaceship commandSetTarget(SpaceObject target)
Returns the object it was called on.
PlayerSpaceship commandLoadTube(number tubeNumber, EMissileWeapons missileType)
Returns the object it was called on.
PlayerSpaceship commandUnloadTube(number tubeNumber)
Returns the object it was called on.
PlayerSpaceship commandFireTube(number tubeNumber, number missile_target_angle)
Returns the object it was called on.
PlayerSpaceship commandFireTubeAtTarget(number tubeNumber, SpaceObject target)
Returns the object it was called on.
PlayerSpaceship commandSetShields(boolean enabled)
Returns the object it was called on.
PlayerSpaceship commandMainScreenSetting(EMainScreenSetting mainScreen)
Returns the object it was called on.
PlayerSpaceship commandMainScreenOverlay(EMainScreenOverlay mainScreen)
Returns the object it was called on.
PlayerSpaceship commandScan(SpaceObject object)
Returns the object it was called on.
PlayerSpaceship commandSetSystemPowerRequest(ESystem system, number power_level)
Set power of the system to e.g. 1.5 ("150 percent")
Returns the object it was called on.
PlayerSpaceship commandSetSystemCoolantRequest(ESystem system, number coolant_level)
Returns the object it was called on.
PlayerSpaceship commandDock(SpaceObject station)
Returns the object it was called on.
PlayerSpaceship commandUndock()
Returns the object it was called on.
PlayerSpaceship commandAbortDock()
Returns the object it was called on.
PlayerSpaceship commandOpenTextComm(SpaceObject obj)
Returns the object it was called on.
PlayerSpaceship commandCloseTextComm()
Returns the object it was called on.
PlayerSpaceship commandAnswerCommHail(boolean awnser)
Returns the object it was called on.
PlayerSpaceship commandSendComm(number index)
Returns the object it was called on.
PlayerSpaceship commandSendCommPlayer(string message)
Returns the object it was called on.
PlayerSpaceship commandSetAutoRepair(boolean enabled)
Command repair crews to automatically move to damaged subsystems.
is command on ships to require less player interaction, especially
when combined with setAutoCoolant/auto_coolant_enabled.
Returns the object it was called on.
PlayerSpaceship commandSetBeamFrequency(number frequency)
Returns the object it was called on.
PlayerSpaceship commandSetBeamSystemTarget(ESystem system)
Returns the object it was called on.
PlayerSpaceship commandSetShieldFrequency(number frequency)
Returns the object it was called on.
PlayerSpaceship commandAddWaypoint(number position_x, number position_y)
Returns the object it was called on.
PlayerSpaceship commandRemoveWaypoint(number index)
Returns the object it was called on.
PlayerSpaceship commandMoveWaypoint(number index, number position_x, number position_y)
Returns the object it was called on.
PlayerSpaceship commandActivateSelfDestruct()
Returns the object it was called on.
PlayerSpaceship commandCancelSelfDestruct()
Returns the object it was called on.
PlayerSpaceship commandConfirmDestructCode(number index, number code)
Returns the object it was called on.
PlayerSpaceship commandCombatManeuverBoost(number amount)
Returns the object it was called on.
PlayerSpaceship commandLaunchProbe(number target_position_x, number target_position_y)
Returns the object it was called on.
PlayerSpaceship commandSetScienceLink(ScanProbe probe)
Command the science screen to link to the given ScanProbe object.
This is equivalent of selecting a probe on Relay and clicking
"Link to Science".
Example: player:commandSetScienceLink(probeObject)
Returns the object it was called on.
PlayerSpaceship commandClearScienceLink()
Command the science screen to clear its link to any ScanProbe object.
This is equivalent to clicking "Link to Science" on Relay when a link
is already active.
Example: player:commandClearScienceLink()
Returns the object it was called on.
PlayerSpaceship commandSetAlertLevel(EAlertLevel level)
Returns the object it was called on.
number getRepairCrewCount()
Return the number of Engineering repair crews on the ship.
PlayerSpaceship setRepairCrewCount(number amount)
Set the total number of Engineering repair crews. If this value is less
than the number of repair crews, this function removes repair crews.
If the value is greater, it adds new repair crews at random locations.
Returns the object it was called on.
PlayerSpaceship setAutoCoolant(boolean active)
Sets whether automatic coolant distribution is enabled. This sets the
amount of coolant proportionally to the amount of heat in that system.
Use this command on ships to require less player interaction, especially
when combined with commandSetAutoRepair/auto_repair_enabled.
Returns the object it was called on.
PlayerSpaceship setControlCode(string code)
Set a password to join the ship.
Returns the object it was called on.
PlayerSpaceship onProbeLaunch(ScriptSimpleCallback callback)
Callback when this ship launches a probe.
Passes the launching PlayerSpaceship and launched ScanProbe.
Example:
player:onProbeLaunch(function (player, probe)
print("Probe " .. probe:getCallSign() .. " launched from ship " .. player:getCallSign())
end)
Returns the object it was called on.
PlayerSpaceship onProbeLink(ScriptSimpleCallback callback)
Callback when this ship links a probe to the Science screen.
Passes the PlayerShip and linked ScanProbe.
Example:
player:onProbeLink(function (player, probe)
print("Probe " .. probe:getCallSign() .. " linked to Science on ship " .. player:getCallSign())
end)
Returns the object it was called on.
PlayerSpaceship onProbeUnlink(ScriptSimpleCallback callback)
Callback when this ship unlinks a probe on the Science screen.
Passes the PlayerShip and previously linked ScanProbe.
Does _not_ fire when the probe is destroyed or expires;
see ScanProbe:onDestruction() and ScanProbe:onExpiration().
Example:
player:onProbeUnlink(function (player, probe)
print("Probe " .. probe:getCallSign() .. " unlinked from Science on ship " .. player:getCallSign())
end)
Returns the object it was called on.
number getLongRangeRadarRange()
number getShortRangeRadarRange()
PlayerSpaceship setLongRangeRadarRange(number range)
Returns the object it was called on.
PlayerSpaceship setShortRangeRadarRange(number range)
Returns the object it was called on.
PlayerSpaceship setCanScan(boolean enabled)
Set whether the object can scan other objects.
Requires a Boolean value.
Example: ship:setCanScan(true)
Returns the object it was called on.
boolean getCanScan()
Get whether the object can scan other objects.
Returns a Boolean value.
Example: ship:getCanScan()
PlayerSpaceship setCanHack(boolean enabled)
Set whether the object can hack other objects.
Requires a Boolean value.
Example: ship:setCanHack(true)
Returns the object it was called on.
boolean getCanHack()
Get whether the object can hack other objects.
Returns a Boolean value.
Example: ship:getCanHack()
PlayerSpaceship setCanDock(boolean enabled)
Set whether the object can dock with other objects.
Requires a Boolean value.
Example: ship:setCanDock(true)
Returns the object it was called on.
boolean getCanDock()
Get whether the object can dock with other objects.
Returns a Boolean value.
Example: ship:getCanDock()
PlayerSpaceship setCanCombatManeuver(boolean enabled)
Set whether the object can perform combat maneuvers.
Requires a Boolean value.
Example: ship:setCanCombatManeuver(true)
Returns the object it was called on.
boolean getCanCombatManeuver()
Get whether the object can perform combat maneuvers.
Returns a Boolean value.
Example: ship:getCanCombatManeuver()
PlayerSpaceship setCanSelfDestruct(boolean enabled)
Set whether the object can self destruct.
Requires a Boolean value.
Example: ship:setCanSelfDestruct(true)
Returns the object it was called on.
boolean getCanSelfDestruct()
Get whether the object can self destruct.
This returns false if self destruct size and damage are both 0, even if
you set setCanSelfDestruct(true).
Returns a Boolean value.
Example: ship:getCanSelfDestruct()
PlayerSpaceship setCanLaunchProbe(boolean enabled)
Set whether the object can launch probes.
Requires a Boolean value.
Example: ship:setCanLaunchProbe(true)
Returns the object it was called on.
boolean getCanLaunchProbe()
Get whether the object can launch probes.
Returns a Boolean value.
Example: ship:getCanLaunchProbe()
PlayerSpaceship setSelfDestructDamage(number amount)
Set the amount of damage done by self destruction.
Requires a float; the value used is randomized +/- 33%.
Example: ship:setSelfDestructDamage(150)
Returns the object it was called on.
number getSelfDestructDamage()
Get the amount of damage done by self destruction.
Returns a float.
Example: ship:getSelfDestructDamage()
PlayerSpaceship setSelfDestructSize(number size)
Set the size of the explosion created by self destruction.
Requires a float.
Example: ship:setSelfDestructSize(1500)
Returns the object it was called on.
number getSelfDestructSize()
Get the size of the explosion created by self destruction.
Returns a float.
Example: ship:getSelfDestructSize()

SpaceStation

Subclass of: ShipTemplateBasedObject

SupplyDrop

A supply drop.
Subclass of: SpaceObject
SupplyDrop setEnergy(number amount)
Returns the object it was called on.
SupplyDrop setWeaponStorage(EMissileWeapons weapon, number amount)
Returns the object it was called on.
SupplyDrop onPickUp(ScriptSimpleCallback callback)
Set a function that will be called if a player picks up the supply drop.
First argument given to the function will be the supply drop, the second the player.
Returns the object it was called on.

VisualAsteroid

An asteroid in space. Outside of hit range, just for visuals.
Subclass of: SpaceObject
VisualAsteroid setSize(number size)
Set the radius of this asteroid
The default radius for an VisualAsteroid is between 110 and 130
Example: VisualAsteroid():setSize(50)
Returns the object it was called on.
number getSize()
Gets the current radius of this asteroid
Example: local size=VisualAsteroid():getSize()

WarpJammer

A warp jammer.
Subclass of: SpaceObject
WarpJammer setRange(number range)
Returns the object it was called on.
WarpJammer onTakingDamage(ScriptSimpleCallback callback)
Set a function that will be called if the warp jammer is taking damage.
First argument given to the function will be the warp jammer, the second the instigator SpaceObject (or nil).
Returns the object it was called on.
WarpJammer onDestruction(ScriptSimpleCallback callback)
Set a function that will be called if the warp jammer is destroyed by taking damage.
First argument given to the function will be the warp jammer, the second the instigator SpaceObject that gave the final blow (or nil).
Returns the object it was called on.

WormHole

A wormhole object that drags objects toward it like a black hole, and then
teleports them to another point when they reach its center.
Subclass of: SpaceObject
WormHole setTargetPosition(number v_x, number v_y)
Set the target of this wormhole
Returns the object it was called on.
number x, number y getTargetPosition()
WormHole onTeleportation(ScriptSimpleCallback callback)
Set a function that will be called if a SpaceObject is teleported.
First argument given to the function will be the WormHole, the second the SpaceObject that has been teleported.
Returns the object it was called on.

Zone

A zone area
Subclass of: SpaceObject
Zone setPoints(number points_x, number points_y...)
Set corners of n-gon to x_1, y_1, x_2, y_2, ..., x_n, y_n.
Recall that x goes right and y goes down.
Example: zone = Zone():setPoints(2000, 0, 0, 3000, -2000, 0)
Returns the object it was called on.
Zone setColor(number r, number g, number b)
Example: zone:setColor(255, 140, 0)
Returns the object it was called on.
Zone setLabel(string label)
Returns the object it was called on.
string getLabel()
boolean isInside(SpaceObject obj)

TutorialGame

The TutorialGame object is normally never created.
And it only used to setup the special tutorial level.
It contains functions to assist in explaining the game, but do not work outside of the tutorial.
TutorialGame setPlayerShip(PlayerSpaceship ship)
Returns the object it was called on.
TutorialGame switchViewToMainScreen()
Returns the object it was called on.
TutorialGame switchViewToTactical()
Returns the object it was called on.
TutorialGame switchViewToLongRange()
Returns the object it was called on.
TutorialGame switchViewToScreen(number n)
Returns the object it was called on.
TutorialGame showMessage(string message, boolean show_next)
Returns the object it was called on.
TutorialGame setMessageToTopPosition()
Returns the object it was called on.
TutorialGame setMessageToBottomPosition()
Returns the object it was called on.
TutorialGame onNext(ScriptSimpleCallback callback)
Returns the object it was called on.
TutorialGame finish()
Returns the object it was called on.
boolean isValid()
Check if this is still looking at a valid object. Returns false when the objects that this variable references is destroyed.
TutorialGame destroy()
Removes this object from the game.
Returns the object it was called on.
typeName
Returns the class name of this object, this is not a function, but a direct member: if object.typeName == "Mine" then print("MINE!") end