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 website 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:
- Color: A string that can either be a hex color code (#rrggbb), three comma-separated rgb integers (rrr,ggg,bbb), or one of the following: "black", "white", "red", "green", "blue", "yellow", "magenta", "cyan". Invalid values default to white.
- EAlertLevel: sets "normal", "yellow", "red" (
playerSpaceship.hpp), returns "Normal", "YELLOW ALERT", "RED ALERT" (playerSpaceship.cpp)
- ECrewPosition: "Helms", "Weapons", "Engineering", "Science", "Relay", "Tactical", "Engineering+", "Operations", "Single", "DamageControl", "PowerManagement", "Database", "AltRelay", "CommsOnly", "ShipLog" (
playerInfo.cpp)
- EDockingState: 0 (not docking), 1 (docking), 2 (docked) (
spaceship.h)
- EMainScreenOverlay: "hidecomms", "showcomms" (
spaceship.hpp)
- EMainScreenSetting: "front", "back", "left", "right", "target", "tactical", "longrange" (
spaceship.hpp)
- EMissileSizes: "small", "medium", "large" (
missileWeaponData.hpp)
- EMissileWeapons: "Homing", "Nuke", "Mine", "EMP", "HVLI" (
missileWeaponData.hpp)
- EScannedState: "notscanned", "friendorfoeidentified", "simplescan", "fullscan" (
spaceObject.h)
- ESystem: "reactor", "beamweapons", "missilesystem", "maneuver", "impulse", "warp", "jumpdrive", "frontshield", "rearshield"
- Factions: "Independent", "Kraylor", "Arlenians", "Exuari", "Ghosts", "Ktlitans", "TSN", "USN", "CUF" (
factionInfo.lua)
- ScriptSimpleCallback / function: Note that the callback function must reference something global, otherwise you get an error like "??[convert<ScriptSimpleCallback>::param] Upvalue 1 of function is not a table...". Use e.g. `math.abs(0) -- Provides global context for SeriousProton` to do nothing.
Note that most SpaceObjects directly switch to fully scanned, only SpaceShips go through all the states.
Functions
- number random(number min_value, number max_value)
- Returns a random floating point number between the min and max values, inclusive.
Floating point numbers are fractional numbers, such as 1.5, 2.333333, 3.141.
To generate an integer value, use irandom().
This function is provided by SeriousProton (src/scriptInterface.cpp).
Example: value = random(0.0,1.0) - number irandom(number min_value, number max_value)
- Returns a random integer number between the min and max values, inclusive.
Integer numbers are whole numbers, so 1, 2, 3, 5, 1400.
To generate a floating point value, use random().
This function is provided by SeriousProton (src/scriptInterface.cpp).
Example: value = random(0,10) - string traceback()
- Returns a string containing a list of function calls up to the current point.
Use this function for debugging and error reporting.
This function is provided by SeriousProton (src/scriptInterface.cpp).
Example:
player:getHull()
traceback = traceback()
-- traceback contains the string [[player:getHull()
-- traceback = traceback()]] - destroyScript()
- Destroys this script instance.
The script continues running until the end of the current script call.
This function is provided by SeriousProton (src/scriptInterface.cpp). - addGMMessage(string message)
- Displays a dismissable message on the GM console.
Example: addGMMessage("Five minutes remaining!") - addGMFunction(string name, ScriptSimpleCallback callback)
- Defines a function to call from a button on the GM console.
The name is also used as the button text.
Use this to create helper scripts for the GM or give the GM console certain controls over the scenario.
These work only when added via scenario script, but not via the HTTP API. (#1807)
Example: addGMFunction("Humans Win", function() victory("Human Navy") end) - removeGMFunction(string name)
- Removes a function from the GM console.
Example: removeGMFunction("Humans Win") - clearGMFunctions()
- Removes all functions from the GM console.
- SpaceObject[] getGMSelection()
- Returns a list of SpaceObjects selected on the GM console.
Use in GM functions to apply them to specific objects.
Example: addGMFunction("Destroy selected", function() for _, obj in ipairs(getGMSelection()) do obj:destroy() end end) - onGMClick(ScriptSimpleCallback callback)
- Defines a function to call when the GM clicks on the background of their console.
Passes the x and y game-space coordinates of the click location.
These work only when added via scenario script, but not via the HTTP API. (#1807)
Examples:
onGMClick(function(x,y) print(x,y) end) -- print the clicked position's coordinates
onGMClick(nil) -- reset the callback - setCommsMessage(string message)
- Sets the content of an accepted hail, or in a comms reply.
If no message is set, attempting to open comms results in "no reply", or a dialogue with the message "?" in a reply.
Use this only in replies (addCommsReply()), comms scripts (SpaceObject:setCommsScript()), or comms functions (SpaceObject:setCommsFunction()).
When used in the callback function of addCommsReply(), this clears all existing replies.
Example:
-- Send a greeting upon hail if the player is friendly with the comms target
function friendlyComms()
if comms_source:isFriendly(comms_target) then
setCommsMessage("Hello, friend!")
else
setCommsMessage("Who are you?")
end
end
-- When some_ship is hailed, run friendlyComms() with some_ship as the comms_target and the player as the comms_source
some_ship:setCommsFunction(friendlyComms) - addCommsReply(string message, ScriptSimpleCallback callback)
- Adds a selectable reply option to a communications dialogue as a button with the given text.
When clicked, the button calls the given function.
Use this only after comms messages (setCommsMessage() in comms scripts (SpaceObject:setCommsScript()), or comms functions (SpaceObject:setCommsFunction()).
Comms scripts pass global variables `comms_target` and `comms_source`. See SpaceObject:setCommsScript().
Comms functions pass only `comms_source`. See SpaceObject:setCommsFunction().
Instead of using these globals, the callback function can take two parameters.
To present multiple options in one comms message, call addCommsReply() for each option.
To create a dialogue tree, run setCommsMessage() inside the addCommsReply() callback, then add new comms replies.
Example:
if comms_source:isFriendly(comms_target) then
setCommsMessage("Hello, friend!")
addCommsReply("Can you send a supply drop?", function(comms_source, comms_target) ... end) -- runs the given function when selected
...
Deprecated: In a comms script, `player` can also be used for `comms_source`. - commsSwitchToGM()
- Switches a PlayerSpaceship communications dialogue from a comms script/function to interactive chat with the GM.
When triggered, this opens a comms chat window on both the player crew's screen and GM console.
Use this in a communication callback function, such as addCommsReply() or SpaceObject:setCommsFunction().
Example:
if comms_source:isFriendly(comms_target) then
setCommsMessage("Hello, friend!")
addCommsReply("I want to speak to your manager!", function() commsSwitchToGM() end) -- launches a GM chat when selected
... - FactionInfo getFactionInfo(string faction_name)
- Returns a reference to the FactionInfo object with the given name.
Use this to modify faction details and relationships with FactionInfo functions.
Example: faction = getFactionInfo("Human Navy") -- faction = the Human Navy FactionInfo object - string getSectorName(number x, number y)
- Returns the name of the sector containing the given x/y coordinates.
Coordinates 0,0 are the top-left ("northwest") point of sector F5.
See also SpaceObject:getSectorName().
Example: getSectorName(20000,-40000) -- returns "D6" - number x, number y sectorToXY(string sector_name)
- Returns the top-left ("northwest") x/y coordinates for the given sector mame.
Examples:
x,y = sectorToXY("A0") -- x = -100000, y = -100000
x,y = sectorToXY("zz-23") -- x = -560000, y = -120000
x,y = sectorToXY("BA12") -- x = 140000, y = 940000 - victory(string faction_name)
- Sets the given faction as the scenario's victor and ends the scenario.
(The GM can unpause the game, but the scenario with its update function is destroyed.)
Example: victory("Exuari") -- ends the scenario, Exuari win - globalMessage(string message, number timeout=nil)
- Displays a message on the main screens of all active player ships.
The message appears for 5 seconds, but new messages immediately replace any displayed message.
Example: globalMessage("You will soon die!") - setBanner(string banner)
- Displays a scrolling banner containing the given text on the cinematic and top-down views.
Example: setBanner("You will soon die!") - number getScenarioTime()
- Returns the elapsed time of the scenario, in seconds.
This timer stops when the game is paused.
Example: getScenarioTime() -- after two minutes, returns 120.0 - PlayerSpaceship getPlayerShip(number index)
- Returns the PlayerSpaceship with the given index.
PlayerSpaceships are 1-indexed.
A new ship is assigned the lowest available index, and a destroyed ship leaves its index vacant.
Pass -1 to return the first active player ship.
Pass -2 to return the current player ship.
Example: getPlayerShip(2) -- returns the second-indexed ship, if it exists - PlayerSpaceship[] getActivePlayerShips()
- Returns a 1-indexed list of active PlayerSpaceships.
Unlike getPlayerShip()'s index, destroyed ships don't leave gaps.
Example: getActivePlayerShips()[2] -- returns the second-indexed active ship - SpaceObject[] getObjectsInRadius(number x, number y, number radius)
- Returns a list of all SpaceObjects within the given radius of the given x/y coordinates.
Example: getObjectsInRadius(0,0,5000) -- returns all objects within 5U of 0,0 - SpaceObject[] getAllObjects()
- Returns a list of all SpaceObjects.
This can return a very long list and could slow down the game if called every tick.
Example: getAllObjects() - string getScenarioVariation()
- [DEPRECATED]
As getScenarioSetting("variation"). - string getScenarioSetting(string key)
- Returns the given scenario setting's value, or an empty string if the setting is not found.
Warning: Headless server modes might load scenarios without default setting values.
Example: getScenarioSetting("Difficulty") -- if a scenario has Setting[Difficulty], returns its value, such as "Easy" or "Normal" - string getGameLanguage()
- Returns the language as the string value of the language key in game preferences.
Example: getGameLanguage() -- returns "en" if the game language is set to English - setScenario(string script_name, string variation_name=nil)
- Launches the given scenario, even if another scenario is running.
Paths are relative to the scripts/ directory.
Example: setScenario("scenario_03_waves.lua") -- launches the scenario at scripts/scenario_03_waves.lua - shutdownGame()
- Shuts down the server.
Use to gracefully shut down a headless server.
Example: shutdownGame() - pauseGame()
- Pauses the game.
Use to pause a headless server, which doesn't have access to the GM screen.
Example: pauseGame() - unpauseGame()
- Unpauses the game.
Use to unpause a headless server, which doesn't have access to the GM screen.
Example: unpauseGame() - playSoundFile(string filename)
- Plays the given audio file on the server.
Paths are relative to the resources/ directory.
Works with any file format supported by SDL, including .wav, .ogg, .flac.
The sound is played only on the server, and not on any clients.
Example: playSoundFile("sfx/laser.wav") - EScanningComplexity getScanningComplexity()
- Returns the running scenario's scanning complexity setting.
Example: getScanningComplexity() -- returns "normal" by default - number getHackingDifficulty()
- Returns the running scenario's hacking difficulty setting.
The returned value is an integer between 0 and 3:
0 = Simple
1 = Normal
2 = Difficult (default)
3 = Fiendish
Example: getHackingDifficulty() -- returns 2 by default - EHackingGames getHackingGames()
- Returns the running scenario's hacking difficulty setting.
Example: getHackingGames() -- returns "all" by default - boolean areBeamShieldFrequenciesUsed()
- Returns whether the "Beam/Shield Frequencies" setting is enabled in the running scenario.
Example: areBeamShieldFrequenciesUsed() -- returns true by default - boolean isPerSystemDamageUsed()
- Returns whether the "Per-System Damage" setting is enabled in the running scenario.
Example: isPerSystemDamageUsed() -- returns true by default - boolean isTacticalRadarAllowed()
- Returns whether the "Tactical Radar" setting for main screens is enabled in the running scenario.
Example: isTacticalRadarAllowed() -- returns true by default - boolean isLongRangeRadarAllowed()
- Returns whether the "Long Range Radar" setting for main screens is enabled in the running scenario.
Example: isLongRangeRadarAllowed() -- returns true by default - onNewPlayerShip(ScriptSimpleCallback callback)
- Defines a function to call when a new PlayerSpaceship is created, whether on the ship selection screen or with the constructor in a Lua script.
Passes the newly created PlayerSpaceship.
Example: onNewPlayerShip(function(player) print(player:getCallSign()) end) -- prints the callsign of new PlayerSpaceships to the console - allowNewPlayerShips(boolean allow)
- Defines whether the "Spawn player ship" button appears on the ship creation screen.
Example: allowNewPlayerShips(false) -- removes the button - string getEEVersion()
- Returns a string with the current EmptyEpsilon version number, such as "20221029".
Example: getEEVersion() -- returns 20221029 on EE-2022.10.29 - ScienceDatabase queryScienceDatabaseById(number id)
- Returns the ScienceDatabase entry with the given unique multiplayer_id.
Returns nil if no entry is found.
Example: queryScienceDatabaseById(4) -- returns the entry with ID 4 - ScienceDatabase queryScienceDatabase(string path...)
- Returns the first ScienceDatabase entry with a matching case-insensitive name within the ScienceDatabase hierarchy.
You must provide the full path to the entry by using multiple arguments, starting with the top-level entry.
Returns nil if no entry is found.
Example: queryScienceDatabase("natural", "mine") -- returns the entry named "Mine" with the parent named "Natural" - ScienceDatabase[] getScienceDatabases()
- Returns a 1-indexed table of all ScienceDatabase entries that don't have a parent entry.
Use ScienceDatabase:getEntries() or ScienceDatabase:getEntryByName() to inspect the result.
See also queryScienceDatabase().
Example:
sdbs = getScienceDatabases() -- returns all top-level science databases
entry = sdbs[1] -- returns the first top-level entry - require(string filename)
- Runs the Lua script with the given filename in the same context as the running Script.
Loads the localized file if it exists at locale/<FILENAME>.<LANGUAGE>.po. - string _(string text, string default=nil)
- Adds a translation context to the given string.
Accepts either one or two values.
If passed one value, this function makes the string available for translation without a category.
If passed two values, the first value is the category, and the second is the string to translate.
Categorizing strings allows for organization, and for the content to be translated differently in multiple contexts if necessary.
Examples:
message1 = _("We will destroy you!") -- tags the string for translation
message2 = _("taunt", "We will destroy you!") -- categorizes the same string as a "taunt" for translation
message3 = _("promise", "We will destroy you!") -- categorizes the same string as a "promise" for translation - ScriptStorage getScriptStorage()
- Returns the ScriptStorage object, which can save and load key/value pairs.
These key/value pairs are permanently stored and survive server restarts.
To use this object, see ScriptStorage:get() and :set().
Example: storage = getScriptStorage();
FactionInfo
A FactionInfo object contains presentation details and faction relationships for member SpaceObjects.
EmptyEpsilon has a hardcoded limit of 32 factions.
SpaceObjects belong to a faction that determines which objects are friendly, neutral, or hostile toward them.
For example, these relationships determine whether a SpaceObject can be targeted by weapons, docked with, or receive comms from another SpaceObject.
If a faction doesn't have a relationship with another faction, it treats those factions as neutral.
Friendly and hostile faction relationships are automatically reciprocated when set with setEnemy() and setFriendly().
If this faction consideres another faction to be hostile, it can target and fire weapons at it, and CpuShips with certain orders might pursue it.
If neutral, this faction can't target and fire weapons at the other faction, and other factions can dock with its stations or dockable ships.
If friendly, this faction acts as neutral but also shares short-range radar with PlayerSpaceships in Relay, and can grant reputation points to PlayerSpaceships of the same faction.
Many scenario and comms scripts also give friendly factions benefits at a reputation cost that netural factions do not.
Factions are loaded from resources/factionInfo.lua upon launching a scenario, and accessed by using the getFactionInfo() global function.
Example:
human_navy = getFactionInfo("Human Navy")
exuari = getFactionInfo("Exuari")
faction = FactionInfo():setName("USN"):setLocaleName(_("USN")) -- sets the internal and translatable faction names
faction:setGMColor(255,128,255) -- uses purple icons for this faction's SpaceObjects in GM and Spectator views
faction:setFriendly(human_navy):setEnemy(exuari) -- sets this faction's friendly and hostile relationships
faction:setDescription(_("The United Stellar Navy, or USN...")) -- sets a translatable description for this faction
- FactionInfo FactionInfo:setName(string name)
- Sets this faction's internal string name, used to reference this faction regardless of EmptyEpsilon's language setting.
If no locale name is defined, this sets the locale name to the same value.
Example: faction:setName("USN")
Returns the object it was called on. - FactionInfo FactionInfo:setLocaleName(string name)
- Sets this faction's name as presented in the user interface.
Wrap the string in the _() function to make it available for translation.
Example: faction:setLocaleName(_("USN"))
Returns the object it was called on. - FactionInfo FactionInfo:setGMColor(number r, number g, number b)
- Sets the RGB color used for SpaceObjects of this faction as seen on the GM and Spectator views.
Defaults to white (255,255,255).
Example: faction:setGMColor(255,0,0) -- sets the color to red
Returns the object it was called on. - FactionInfo FactionInfo:setDescription(string description)
- Sets this faction's longform description as shown in its Factions ScienceDatabase child entry.
Wrap the string in the _() function to make it available for translation.
Example: faction:setDescription(_("The United Stellar Navy, or USN...")) -- sets a translatable description for this faction
Returns the object it was called on. - FactionInfo FactionInfo:setEnemy(FactionInfo other)
- Sets the given faction to appear as hostile to SpaceObjects of this faction.
For example, Spaceships of this faction can target and fire at SpaceShips of the given faction.
Defaults to no hostile factions.
Warning: A faction can be designated as hostile to itself, but the behavior is not well-defined.
Example: faction:setEnemy(exuari) -- sets the Exuari to appear as hostile to this faction
Returns the object it was called on. - FactionInfo FactionInfo:setFriendly(FactionInfo other)
- Sets the given faction to appear as friendly to SpaceObjects of this faction.
For example, PlayerSpaceships of this faction can gain reputation with it.
Defaults to no friendly factions.
Example: faction:setFriendly(exuari) -- sets the Human Navy to appear as friendly to this faction
Returns the object it was called on. - FactionInfo FactionInfo:setNeutral(FactionInfo other)
- Sets the given faction to appear as neutral to SpaceObjects of this faction.
This removes any existing faction relationships between the two factions.
Example: faction:setNeutral(human_navy) -- sets the Human Navy to appear as neutral to this faction
Returns the object it was called on. - boolean FactionInfo:isValid()
- Returns whether this object is still valid. Returns false if this object was destroyed or doesn't exist.
- FactionInfo FactionInfo:destroy()
- Removes this object from the game.
Returns the object it was called on. - FactionInfo:typeName
- Returns the class name of this object. This is not a function, but a direct member. Example: if object.typeName == "Mine" then print("MINE!") end
ModelData
A ModelData object contains 3D appearance and SeriousProton physics collision details.
Almost all SpaceObjects have a ModelData associated with them to define how they appear in 3D views.
A ScienceDatabase entry can also have ModelData associated with and displayed in it.
This defines a 3D mesh file, an albedo map ("texture"), a specular/normal map, and an illumination map.
These files might be located in the resources/ directory or loaded from resource packs.
ModelData also defines the model's position offset and scale relative to its mesh coordinates.
If the model is for a SpaceShip with weapons or thrusters, this also defines the origin positions of its weapon effects, and particle emitters for thruster and engine effects.
For physics, this defines the model's radius for a circle collider, or optional box collider dimensions.
(While ModelData defines 3D models, EmptyEpsilon uses a 2D physics engine for collisions.)
EmptyEpsilon loads ModelData from scripts/model_data.lua when launched, and loads meshes and textures when an object using this ModelData is first viewed.
For complete examples, see scripts/model_data.lua.
- ModelData ModelData:setName(string name)
- Sets this ModelData's name.
Use this name when referencing a ModelData from other objects.
Example: model:setName("space_station_1")
Returns the object it was called on. - ModelData ModelData:setMesh(string mesh_name)
- Sets this ModelData's mesh file.
Required; if omitted, this ModelData generates an error.
Valid values include OBJ-format (.obj extension) 3D models relative to the resources/ directory.
You can also reference models from resource packs, which have ".model" extensions.
To view resource pack paths, extract strings from the pack, such as by running "strings packs/Angryfly.pack | grep -i model" on *nix.
For example, this lists "battleship_destroyer_2_upgraded/battleship_destroyer_2_upgraded.model", which is a valid mesh path.
Examples:
setMesh("space_station_1/space_station_1.model") -- loads this model from a resource pack
setMesh("mesh/sphere.obj") -- loads this model from the resources/ directory
Returns the object it was called on. - ModelData ModelData:setTexture(string texture_name)
- Sets this ModelData's albedo map, or base flat-light color texture.
Required; if omitted, this ModelData generates an error.
Valid values include PNG- or JPG-format images relative to the resources/ directory.
You can also reference textures from resource packs.
To view resource pack paths, extract strings from the pack, such as by running "strings packs/Angryfly.pack | egrep -i (png|jpg)" on *nix.
Examples:
model:setTexture("space_station_1/space_station_1_color.jpg") -- loads this texture from a resource pack
model:setTexture("mesh/ship/Ender Battlecruiser.png") -- loads this texture from the resources/ directory
Returns the object it was called on. - ModelData ModelData:setSpecular(string specular_texture_name)
- Sets this ModelData's specular map, or shininess texture. Some models use this to load a normal map.
Optional; if omitted, no specular map is applied.
Valid values include PNG- or JPG-format images relative to the resources/ directory.
You can also reference textures from resource packs.
To view resource pack paths, extract strings from the pack, such as by running "strings packs/Angryfly.pack | egrep -i (png|jpg)" on *nix.
Examples:
model:setSpecular("space_station_1/space_station_1_specular.jpg") -- loads this texture from a resource pack
model:setSpecular("mesh/various/debris-blog-specular.jpg") -- loads this texture from the resources/ directory
Returns the object it was called on. - ModelData ModelData:setIllumination(string illumination_texture_name)
- Sets this ModelData's illumination map, or glow texture, which defines which parts of the texture appear to be luminescent.
Optional; if omitted, no illumination map is applied.
Valid values include PNG- or JPG-format images relative to the resources/ directory.
You can also reference textures from resource packs.
To view resource pack paths, extract strings from the pack, such as by running "strings packs/Angryfly.pack | egrep -i (png|jpg)" on *nix.
Examples:
model:setIllumination("space_station_1/space_station_1_illumination.jpg") -- loads this texture from a resource pack
model:setIllumination("mesh/ship/Ender Battlecruiser_illumination.png") -- loads this texture from the resources/ directory
Returns the object it was called on. - ModelData ModelData:setRenderOffset(number mesh_offset_x, number mesh_offset_y, number mesh_offset_z)
- Sets this ModelData's mesh offset, relative to its position in its mesh data.
If a 3D mesh's central origin point is not at 0,0,0, use this to compensate.
If you view the model in Blender, these values are equivalent to -X,+Y,+Z.
Example: model:setRenderOffset(1,2,5) -- offsets its in-game position from its mesh file position when rendered
Returns the object it was called on. - ModelData ModelData:setScale(number scale)
- Scales this ModelData's mesh by the given factor.
Values greater than 1.0 scale the model up, and values between 0 and 1.0 scale it down.
Use this if models you load are smaller or larger than expected.
Defaults to 1.0.
Example: model:setScale(20) -- scales the model up by 20x
Returns the object it was called on. - ModelData ModelData:setRadius(number radius)
- Sets this ModelData's base radius.
By default, EmptyEpsilon uses this to create a circular collider around objects that use this ModelData.
SpaceObject:setRadius() can override this for colliders.
Setting a box collider with ModelData:setCollisionBox() also overrides this.
Defaults to 1.0.
Example: model:setRadius(100) -- sets the object's collisionable radius to 0.1U
Returns the object it was called on. - ModelData ModelData:setCollisionBox(number collision_box_x, number collision_box_y)
- Sets a 2D box collider for this ModelData.
If both values are greater than 0.0, this overrides ModelData:setRadius() for collisions.
Defaults to 0,0.
Example: model:setCollisionBox(400, 400) -- sets the object's collision box to 0.4U by 0.4U
Returns the object it was called on. - ModelData ModelData:addBeamPosition(number position_x, number position_y, number position_z)
- Adds a BeamEffect origin position to this ModelData.
If no origin positions are defined, this defaults to the model's origin (0,0,0).
If you view the model in Blender, these coordinate values are equivalent to -X,+Y,+Z.
Example:
-- Add a beam position at the given model X/Y/Z coordinates.
model:addBeamPosition(21,-28.2,-2)
Returns the object it was called on. - ModelData ModelData:addTubePosition(number position_x, number position_y, number position_z)
- Adds a WeaponTube origin position to this ModelData.
If no origin positions are defined, this defaults to the model's origin (0,0,0).
If you view the model in Blender, these coordinate values are equivalent to -X,+Y,+Z.
-- Add a tube position at the given model X/Y/Z coordinates.
model:addTubePosition(21,-28.2,-2)
Returns the object it was called on. - ModelData ModelData:addEngineEmitor(number position_x, number position_y, number position_z, number color_r, number color_g, number color_b, number scale)
- [DEPRECATED]
Use ModelData:addEngineEmitter().
Returns the object it was called on. - ModelData ModelData:addEngineEmitter(number position_x, number position_y, number position_z, number color_r, number color_g, number color_b, number scale)
- Adds an impulse engine particle effect emitter to this ModelData.
When a SpaceShip engages impulse engines, this defines the position, color, and size of a particle trail effect.
If no origin positions are defined, this defaults to the model's origin (0,0,0).
If you view the model in Blender, these coordinate values are equivalent to -X,+Y,+Z.
Example:
-- Add an engine emitter at the given model X/Y/Z coordinates, with a RGB color of 1.0/0.2/0.2 and scale of 3.
model:addEngineEmitter(-28, 1.5,-5,1.0,0.2,0.2,3.0)
Returns the object it was called on. - boolean ModelData:isValid()
- Returns whether this object is still valid. Returns false if this object was destroyed or doesn't exist.
- ModelData ModelData:destroy()
- Removes this object from the game.
Returns the object it was called on. - ModelData:typeName
- Returns the class name of this object. This is not a function, but a direct member. Example: if object.typeName == "Mine" then print("MINE!") end
ScienceDatabase
A ScienceDatabase entry stores information displayed to all players in the Science database tab or Database standalone screen.
Each ScienceDatabase entry can contain key/value pairs, an image, and a 3D ModelData.
A ScienceDatabase entry can also be the parent of many ScienceDatabases or the child of one ScienceDatabase, creating a hierarchical structure.
Each ScienceDatabase without a parent is a top-level entry in the player-viewed database interface.
Each child ScienceDatabase entry is displayed only when its parent entry is selected.
By default, EmptyEpsilon creates parentless entries for Factions, "Natural" (terrain), Ships, and Weapons.
Their child entries are populated by EmptyEpsilon upon launching a scenario, either with hardcoded details, entries loaded from scripts/science_db.lua, or the contents of script-defined objects such as ShipTemplates and FactionInfo.
Entries for ShipTemplates are also linked to from Science radar info of scanned ships of that template.
Each ScienceDatabase entry has a unique identifier regardless of its displayed order, and multiple entries can have the same name.
Changes to ScienceDatabases appear in the UI only after a player opens the Database or selects an entry.
To retrieve a 1-indexed table of all parentless entries, use the global function getScienceDatabases().
You can then use this class's functions to get child entries and entry data.
Example:
-- Creates a new parentless entry named "Species", with an entry containing a key/value
ScienceDatabase():setName("Species"):addEntry("Canines"):addKeyValue("Legs","4")
sdb = getScienceDatabases() -- returns a 1-indexed table of top-level entries
for i,db in pairs(sdb) do
if (db:getName() == "Species") then
entry = db -- assigns the ScienceDatabase with the name "Species"
end
end
species = entry:getEntries()[1] -- species = "Canines"
legs = species:getKeyValue("Legs") -- legs = "4"
- ScienceDatabase ScienceDatabase:setName(string name)
- Sets this ScienceDatabase entry's displayed name.
Example: entry:setName("Species")
Returns the object it was called on. - string ScienceDatabase:getName()
- Returns this ScienceDatabase entry's displayed name.
Example: entry:getName() - number ScienceDatabase:getId()
- Returns this ScienceDatabase entry's unique multiplayer_id.
Examples: entry:getId() -- returns the entry's ID - number ScienceDatabase:getParentId()
- Return this ScienceDatabase entry's parent entry's unique multiplayer_id.
Returns 0 if the entry has no parent.
Example: entry:getParentId() -- returns the parent entry's ID - ScienceDatabase ScienceDatabase:addEntry(string name)
- Creates a ScienceDatabase entry with the given name as a child of this ScienceDatabase entry.
Returns the newly created entry. Chaining addEntry() creates a child of the new child entry.
Examples:
species:addEntry("Canines") -- adds an entry named "Canines" as a child of ScienceDatabase species
-- Adds an entry named "Felines" as a child of species, and an entry named "Calico" as a child of "Felines"
species:addEntry("Felines"):addEntry("Calico") - ScienceDatabase ScienceDatabase:getEntryByName(string name)
- Returns the first child ScienceDatabase entry of this ScienceDatabase entry found with the given case-insensitive name.
Multiple entries can have the same name.
Returns nil if no entry is found.
Example: entry:getEntryByName("canines") -- returns the "Canines" entry in sdb - ScienceDatabase[] ScienceDatabase:getEntries()
- Returns a 1-indexed table of all child entries in this ScienceDatabase entry, in arbitrary order.
To return parentless top-level ScienceDatabase entries, use the global function getScienceDatabases().
Examples:
entry = getScienceDatabases()[1] -- returns the first parentless entry
entry:getEntries() -- returns all of its child entries - boolean ScienceDatabase:hasEntries()
- Returns true if this ScienceDatabase entry has child entries.
Example: entry:hasEntries() - ScienceDatabase ScienceDatabase:addKeyValue(string key, string value)
- Adds a key/value pair to this ScienceDatabase entry's key/value data.
The Database view's center column displays all key/value data when its entry is selected.
Chaining addKeyValue() adds each key/value to the same entry.
Warning: addKeyValue() can add entries with duplicate keys. To avoid this, use setKeyValue() instead.
Example:
-- Adds "Legs","4" and "Ears","2" to the entry's key/value data.
entry:addKeyValue("Legs","4"):addKeyValue("Ears","2")
entry:addKeyValue("Legs","2") -- adds "Legs","2", even if "Legs","4" is already present
Returns the object it was called on. - ScienceDatabase ScienceDatabase:setKeyValue(string key, string value)
- Sets the value of all key/value pairs matching the given case-insensitive key in this ScienceDatabase entry's key/value data.
If the key already exists, this changes its value.
If duplicate matching keys exist, this changes all of their values.
If the key doesn't exist, this acts as addKeyValue().
Examples:
-- Assuming entry already has "Legs","4" as a key/value
entry:setKeyValue("Legs","2") -- changes this entry's "Legs" value to "2"
entry:setKeyValue("Arms","2") -- adds "Arms","2" to the entry's key/value data
Returns the object it was called on. - string ScienceDatabase:getKeyValue(string key)
- Returns the value of the first matching case-insensitive key found in this ScienceDatabase entry's key/value data.
Returns an empty string if the key doesn't exist.
Example: entry:getKeyValue("Legs") -- returns the value if found or "" if not - table ScienceDatabase:getKeyValues()
- Returns a table containing all key/value pairs in this ScienceDatabase entry.
Warning: Duplicate keys appear only once, with the last value found.
Example:
entry:getKeyValues() -- returns the key/value table for this entry
for k,v in pairs(kv) do print(k,v) end -- Print each key/value pair for this entry to the console - ScienceDatabase ScienceDatabase:removeKey(string key)
- Removes all key/value pairs matching the given case-insensitive key in this ScienceDatabase entry's key/value data.
If duplicate matching keys exist, this removes all of them.
Example: entry:removeKey("Legs") -- removes all key/value data with the key "Legs"
Returns the object it was called on. - ScienceDatabase ScienceDatabase:setLongDescription(string text)
- Sets this ScienceDatabase entry's longform description to the given string.
The Database view's right column displays the longform description when its entry is selected.
Example: entry:setLongDescription("This species is known for its loyalty...")
Returns the object it was called on. - string ScienceDatabase:getLongDescription()
- Returns this ScienceDatabase entry's longform description.
Returns an empty string if no description is set.
Example: entry:getLongDescription() - ScienceDatabase ScienceDatabase:setImage(string path)
- Sets this ScienceDatabase entry's image file to the given filename.
Valid values are filenames to PNG files relative to the resources/ directory.
An empty string removes any set image.
Example: entry:setImage("retriever.png") -- sets the entry's image to the file "resources/retriever.png"
Returns the object it was called on. - string ScienceDatabase:getImage()
- Returns this ScienceDatabase entry's image filename.
Returns an empty string if no image is set.
Example: entry:getImage() - ScienceDatabase ScienceDatabase:setModelDataName(string model_data_name)
- Sets the 3D appearance, by ModelData name, used for this ScienceDatabase entry.
ModelData objects define a 3D mesh, textures, adjustments, and collision box, and are loaded from scripts/model_data.lua when EmptyEpsilon is launched.
Example: entry:setModelDataName("AtlasHeavyFighterYellow") -- uses the ModelData named "AtlasHeavyFighterYellow"
Returns the object it was called on. - boolean ScienceDatabase:isValid()
- Returns whether this object is still valid. Returns false if this object was destroyed or doesn't exist.
- ScienceDatabase ScienceDatabase:destroy()
- Removes this object from the game.
Returns the object it was called on. - ScienceDatabase:typeName
- Returns the class name of this object. This is not a function, but a direct member. Example: if object.typeName == "Mine" then print("MINE!") end
Script
A Script object can create and run another Lua 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 Script:run(string filename)
- Runs a script with the given filename.
Loads the localized file if it exists at locale/<FILENAME>.<LANGUAGE>.po.
Returns true if the resulting SeriousProton ScriptObject was successfully run.
Example: script = Script():run("script.lua") - Script Script:setVariable(string variable_name, string value)
- Sets a global variable in this Script instance that is accessible from the main Script.
Returns the object it was called on. - boolean Script:isValid()
- Returns whether this object is still valid. Returns false if this object was destroyed or doesn't exist.
- Script Script:destroy()
- Removes this object from the game.
Returns the object it was called on. - Script:typeName
- Returns the class name of this object. This is not a function, but a direct member. Example: if object.typeName == "Mine" then print("MINE!") end
ScriptStorage
The ScriptStorage persistently saves key/value pairs to a file.
These key/value pairs are permanently stored and survive server restarts.
Its default file path is $HOME/.emptyepsilon/scriptstorage.json.
See getScriptStorage().
- string ScriptStorage:get(string key)
- Returns the value for the given key from the persistent ScriptStorage as a JSON string.
Returns nothing if the key is not found.
Example:
storage = getScriptStorage()
storage:set('key', 'value')
storage:get('key') -- returns "value" - ScriptStorage ScriptStorage:set(string key, string value)
- Sets a key/value pair in the persistent ScriptStorage file.
If the scriptstorage.json file doesn't exist, this function creates it.
If the given key already exists, this function overwrites its value.
Example:
storage = getScriptStorage()
storage:set('key', 'value') -- writes {"key":"value"} to scriptstorage.json
Returns the object it was called on. - boolean ScriptStorage:isValid()
- Returns whether this object is still valid. Returns false if this object was destroyed or doesn't exist.
- ScriptStorage ScriptStorage:destroy()
- Removes this object from the game.
Returns the object it was called on. - ScriptStorage:typeName
- Returns the class name of this object. This is not a function, but a direct member. Example: if object.typeName == "Mine" then print("MINE!") end
ShipTemplate
A ShipTemplate defines the base functionality, stats, models, and other details for the ShipTemplateBasedObjects created from it.
ShipTemplateBasedObjects belong to either the SpaceStation or SpaceShip subclasses. SpaceShips in turn belong to the CpuShip or PlayerSpaceship classes.
ShipTemplates appear in ship and space station creation lists, such as the ship selection screen on scenarios that allow player ship creation, or the GM console's object creation tool.
They also appear as default entries in the science database.
EmptyEpsilon loads scripts/shipTemplates.lua at launch, which requires files containing ShipTemplates located in scripts/shiptemplates/.
New ShipTemplates can't be defined while a scenario is running.
Use Lua variables to apply several ShipTemplate functions to the same template.
Example:
-- Create a ShipTemplate for a Cruiser Frigate-class CpuShip designated Phobos T3
template = ShipTemplate():setName("Phobos T3"):setLocaleName(_("ship","Phobos T3")):setClass(_("class","Frigate"),_("subclass","Cruiser"))
-- Set the Phobos T3's appearance to the ModelData named "AtlasHeavyFighterYellow"
template:setModel("AtlasHeavyFighterYellow")
- ShipTemplate ShipTemplate:setName(string name)
- Sets this ShipTemplate's unique reference name.
Use this value for referencing this ShipTemplate in scripts.
If this value begins with "Player ", including the trailing space, EmptyEpsilon uses only what follows as the name.
If this ShipTemplate lacks a localized name (ShipTemplate:setLocaleName()), it defaults to this reference name.
Example: template:setName("Phobos T3")
Returns the object it was called on. - ShipTemplate ShipTemplate:setLocaleName(string name)
- Sets the displayed vessel model designation for ShipTemplateBasedObjects created from this ShipTemplate.
Use with the _ function to expose the localized name to translation.
Examples:
template:setLocaleName("Phobos T3")
template:setLocaleName(_("ship","Phobos T3")) -- with a translation-exposed name
Returns the object it was called on. - ShipTemplate ShipTemplate:setClass(string class_name, string sub_class_name)
- Sets the vessel class and subclass for ShipTemplateBasedObjects created from this ShipTemplate.
Vessel classes are used to define certain traits across similar ships, such as dockability.
See also ShipTemplate:setExternalDockClasses() and ShipTemplate:setInternalDockClasses().
For consistent class usage across translations, wrap class name strings in the _ function.
Defaults to the equivalent value of (_("No class"),_("No sub-class")).
Examples:
template:setClass(_("class","Frigate"),_("subclass","Cruiser"))
Returns the object it was called on. - ShipTemplate ShipTemplate:setDescription(string description)
- Sets the description shown in the science database for ShipTemplateBasedObjects created from this ShipTemplate.
Example: template:setDescription(_("The Phobos T3 is most any navy's workhorse frigate."))
Returns the object it was called on. - ShipTemplate ShipTemplate:setType(TemplateType type)
- Sets the object-oriented subclass of ShipTemplateBasedObject to create from this ShipTemplate.
Defaults to "ship" (CpuShip).
Valid values are "ship", "playership" (PlayerSpaceship), and "station" (SpaceStation).
Using setType("station") is equivalent to also using ShipTemplate:setRepairDocked(true) and ShipTemplate:setRadarTrace("blip.png").
Example: template:setType("playership")
Returns the object it was called on. - ShipTemplate ShipTemplate:hidden()
- If declared, this function hides this ShipTemplate from creation features and the science database.
Hidden templates provide backward compatibility to older scenario scripts.
Example: template:hidden() -- hides this template
Returns the object it was called on. - ShipTemplate ShipTemplate:setDefaultAI(string default_ai_name)
- Sets the default combat AI state for CpuShips created from this ShipTemplate.
Combat AI states determine the AI's combat tactics and responses.
They're distinct from orders, which determine the ship's active objectives and are defined by CpuShip:order...() functions.
Valid combat AI states are:
- "default" directly pursues enemies at beam range while making opportunistic missile attacks
- "evasion" maintains distance from enemy weapons and evades attacks
- "fighter" prefers strafing maneuvers and attacks briefly at close range while passing
- "missilevolley" prefers lining up missile attacks from long range
Example: template:setAI("fighter") -- default to the "fighter" combat AI state
Returns the object it was called on. - ShipTemplate ShipTemplate:setModel(string model_name)
- Sets the 3D appearance, by ModelData name, of ShipTemplateBasedObjects created from this ShipTemplate.
ModelData objects define a 3D mesh, textures, adjustments, and collision box, and are loaded from scripts/model_data.lua when EmptyEpsilon is launched.
Example: template:setModel("AtlasHeavyFighterYellow") -- uses the ModelData named "AtlasHeavyFighterYellow"
Returns the object it was called on. - ShipTemplate ShipTemplate:setDockClasses(string classes...)
- As ShipTemplate:setExternalDockClasses().
Returns the object it was called on. - ShipTemplate ShipTemplate:setExternalDockClasses(string classes...)
- Defines a list of vessel classes that can be externally docked to ShipTemplateBasedObjects created from this ShipTemplate.
External docking keeps the docked ship attached to the outside of the carrier.
By default, SpaceStations allow all classes of SpaceShips to dock externally.
For consistent class usage across translations, wrap class name strings in the _ function.
Example: template:setExternalDockClasses(_("class","Frigate"),_("class","Corvette")) -- all Frigate and Corvette ships can dock to the outside of this ShipTemplateBasedObject
Returns the object it was called on. - ShipTemplate ShipTemplate:setInternalDockClasses(string classes...)
- Defines a list of ship classes that can be docked inside of ShipTemplateBasedObjects created from this ShipTemplate.
Internal docking stores the docked ship inside of this derived ShipTemplateBasedObject.
For consistent class usage across translations, wrap class name strings in the _ function.
Example: template:setInternalDockClasses(_("class","Starfighter")) -- all Starfighter ships can dock inside of this ShipTemplateBasedObject
Returns the object it was called on. - ShipTemplate ShipTemplate:setEnergyStorage(number energy_amount)
- Sets the amount of energy available for PlayerSpaceships created from this ShipTemplate.
Only PlayerSpaceships consume energy. Setting this for other ShipTemplateBasedObject types has no effect.
Defaults to 1000.
Example: template:setEnergyStorage(500)
Returns the object it was called on. - ShipTemplate ShipTemplate:setRepairCrewCount(number amount)
- Sets the default number of repair crew for PlayerSpaceships created from this ShipTemplate.
Defaults to 3.
Only PlayerSpaceships use repair crews. Setting this for other ShipTemplateBasedObject types has no effect.
Example: template:setRepairCrewCount(5)
Returns the object it was called on. - ShipTemplate ShipTemplate:setBeam(number index, number arc, number direction, number range, number cycle_time, number damage)
- As ShipTemplate:setBeamWeapon().
Returns the object it was called on. - ShipTemplate ShipTemplate:setBeamWeapon(number index, number arc, number direction, number range, number cycle_time, number damage)
- Defines the traits of a BeamWeapon for ShipTemplateBasedObjects created from this ShipTemplate.
- index: Each beam weapon in this ShipTemplate must have a unique index.
- arc: Sets the arc of its firing capability, in degrees.
- direction: Sets the default center angle of the arc, in degrees relative to the ship's forward bearing. Value can be negative.
- range: Sets how far away the beam can fire.
- cycle_time: Sets the base firing delay, in seconds. System effectiveness modifies the cycle time.
- damage: Sets the base damage done by the beam to the target. System effectiveness modifies the damage.
To add multiple beam weapons to a ship, invoke this function multiple times, assigning each weapon a unique index value.
To create a turreted beam, also add ShipTemplate:setBeamWeaponTurret(), and set the beam weapon's arc to be smaller than the turret's arc.
Example: setBeamWeapon(0,90,-15,1200,3,1) -- index 0, 90-degree arc centered -15 degrees from forward, extending 1.2U, firing every 3 seconds and dealing 1 damage
Returns the object it was called on. - ShipTemplate ShipTemplate:setBeamWeaponTurret(number index, number arc, number direction, number rotation_rate)
- Converts a BeamWeapon into a turret and defines its traits for SpaceShips created from this ShipTemplate.
A turreted beam weapon rotates within its turret arc toward the weapons target at the given rotation rate.
- index: Must match the index of an existing beam weapon.
- arc: Sets the turret's maximum targeting angles, in degrees. The turret arc must be larger than the associated beam weapon's arc.
- direction: Sets the default center angle of the turret arc, in degrees relative to the ship's forward bearing. Value can be negative.
- rotation_rate: Sets how many degrees per tick that the associated beam weapon's direction can rotate toward the target within the turret arc. System effectiveness modifies the rotation rate.
To create a turreted beam, also add ShipTemplate:setBeamWeapon(), and set the beam weapon's arc to be smaller than the turret's arc.
Example:
-- Makes beam weapon 0 a turret with a 200-degree turret arc centered on 90 degrees from forward, rotating at 5 degrees per tick (unit?)
template:setBeamWeaponTurret(0,200,90,5)
Returns the object it was called on. - ShipTemplate ShipTemplate:setBeamTexture(number index, string texture)
- Sets the BeamEffect texture, by filename, for the BeamWeapon with the given index on SpaceShips created from this ShipTemplate.
See BeamEffect:setTexture().
Example: template:setBeamWeaponTexture("texture/beam_blue.png")
Returns the object it was called on. - ShipTemplate ShipTemplate:setBeamWeaponEnergyPerFire(number index, number energy)
- Sets how much energy is drained each time the BeamWeapon with the given index is fired.
Only PlayerSpaceships consume energy. Setting this for other ShipTemplateBasedObject types has no effect.
Defaults to 3.0, as defined in src/spaceObjects/spaceshipParts/beamWeapon.cpp.
Example: template:setBeamWeaponEnergyPerFire(0,1) -- sets beam 0 to use 1 energy per firing
Returns the object it was called on. - ShipTemplate ShipTemplate:setBeamWeaponHeatPerFire(number index, number heat)
- Sets how much "beamweapon" system heat is generated, in percentage of total system heat capacity, each time the BeamWeapon with the given index is fired.
Only PlayerSpaceships generate and manage heat. Setting this for other ShipTemplateBasedObject types has no effect.
Defaults to 0.02, as defined in src/spaceObjects/spaceshipParts/beamWeapon.cpp.
Example: template:setBeamWeaponHeatPerFire(0,0.5) -- sets beam 0 to generate 0.5 (50%) system heat per firing
Returns the object it was called on. - ShipTemplate ShipTemplate:setTubes(number amount, number load_time)
- Sets the number of WeaponTubes for ShipTemplateBasedObjects created from this ShipTemplate, and the default delay for loading and unloading each tube, in seconds.
Weapon tubes are 0-indexed. For example, 3 tubes would be indexed 0, 1, and 2.
Ships are limited to a maximum of 16 weapon tubes.
The default ShipTemplate adds 0 tubes and an 8-second loading time.
Example: template:setTubes(6,15.0) -- creates 6 weapon tubes with 15-second loading times
Returns the object it was called on. - ShipTemplate ShipTemplate:setTubeLoadTime(number index, number load_time)
- Sets the delay, in seconds, for loading and unloading the WeaponTube with the given index.
Defaults to 8.0.
Example: template:setTubeLoadTime(0,12) -- sets the loading time for tube 0 to 12 seconds
Returns the object it was called on. - ShipTemplate ShipTemplate:weaponTubeAllowMissle(number index, EMissileWeapons type)
- Sets which weapon types the WeaponTube with the given index can load.
Note the spelling of "missle".
Example: template:weaponTubeAllowMissle(0,"Homing") -- allows Homing missiles to be loaded in tube 0
Returns the object it was called on. - ShipTemplate ShipTemplate:weaponTubeDisallowMissle(number index, EMissileWeapons type)
- Sets which weapon types the WeaponTube with the given index can't load.
Note the spelling of "missle".
Example: template:weaponTubeDisallowMissle(0,"Homing") -- prevents Homing missiles from being loaded in tube 0
Returns the object it was called on. - ShipTemplate ShipTemplate:setWeaponTubeExclusiveFor(number index, EMissileWeapons type)
- Sets a WeaponTube with the given index to allow loading only the given weapon type.
Example: template:setWeaponTubeExclusiveFor(0,"Homing") -- allows only Homing missiles to be loaded in tube 0
Returns the object it was called on. - ShipTemplate ShipTemplate:setTubeDirection(number index, number direction)
- Sets the angle, relative to the ShipTemplateBasedObject's forward bearing, toward which the WeaponTube with the given index points.
Defaults to 0. Accepts negative and positive values.
Example:
-- Sets tube 0 to point 90 degrees right of forward, and tube 1 to point 90 degrees left of forward
template:setTubeDirection(0,90):setTubeDirection(1,-90)
Returns the object it was called on. - ShipTemplate ShipTemplate:setTubeSize(number index, EMissileSizes size)
- Sets the weapon size launched from the WeaponTube with the given index.
Defaults to "medium".
Example: template:setTubeSize(0,"large") -- sets tube 0 to fire large weapons
Returns the object it was called on. - ShipTemplate ShipTemplate:setHull(number amount)
- Sets the number of default hull points for ShipTemplateBasedObjects created from this ShipTemplate.
Defaults to 70.
Example: template:setHull(100)
Returns the object it was called on. - ShipTemplate ShipTemplate:setShields(number values...)
- Sets the maximum points per shield segment for ShipTemplateBasedObjects created from this ShipTemplate.
Each argument segments the shield clockwise by dividing the arc equally for each segment, up to a maximum of 8 segments.
The center of the first segment's arc always faces forward.
A ShipTemplateBasedObject with one shield segment has only a front shield generator system, and one with two or more segments has only front and rear generator systems.
If not defined, the ShipTemplateBasedObject defaults to having no shield capabilities.
Examples:
template:setShields(400) -- one shield segment; hits from all angles damage the same shield
template:setShields(100,80) -- two shield segments; the front 180-degree shield has 100 points, the rear 80
template:setShields(100,50,40,30) -- four shield segments; the front 90-degree shield has 100, right 50, rear 40, and left 30
Returns the object it was called on. - ShipTemplate ShipTemplate:setSpeed(number impulse, number turn, number acceleration, number reverse_speed=nil, number reverse_acceleration=nil)
- Sets the impulse speed, rotational speed, and impulse acceleration for SpaceShips created from this ShipTemplate.
(unit?)
The optional fourth and fifth arguments set the reverse speed and reverse acceleration.
If the reverse speed and acceleration aren't explicitly set, the defaults are equal to the forward speed and acceleration.
See also SpaceShip:setImpulseMaxSpeed(), SpaceShip:setRotationMaxSpeed(), SpaceShip:setAcceleration().
Defaults to the equivalent value of (500,10,20).
Example:
-- Sets the forward impulse speed to 80, rotational speed to 15, forward acceleration to 25, reverse speed to 20, and reverse acceleration to the same as the forward acceleration
template:setSpeed(80,15,25,20)
Returns the object it was called on. - ShipTemplate ShipTemplate:setCombatManeuver(number boost, number strafe)
- Sets the combat maneuver capacity for SpaceShips created from this ShipTemplate.
The boost value sets the forward maneuver capacity, and the strafe value sets the lateral maneuver capacity.
Defaults to (0,0).
Example: template:setCombatManeuver(400,250)
Returns the object it was called on. - ShipTemplate ShipTemplate:setWarpSpeed(number warp)
- Sets the warp speed factor for SpaceShips created from this ShipTemplate.
Defaults to 0. The typical warp speed value for a warp-capable ship is 1000, which is equivalent to 60U/minute at warp 1.
Setting any value also enables the "warp" system and controls.
Example: template:setWarpSpeed(1000)
Returns the object it was called on. - ShipTemplate ShipTemplate:setSharesEnergyWithDocked(boolean enabled)
- Defines whether ShipTemplateBasedObjects created from this ShipTemplate supply energy to docked PlayerSpaceships.
Defaults to true.
Example: template:setSharesEnergyWithDocked(false)
Returns the object it was called on. - ShipTemplate ShipTemplate:setRepairDocked(boolean enabled)
- Defines whether ShipTemplateBasedObjects created from this template repair docked SpaceShips.
Defaults to false. ShipTemplate:setType("station") sets this to true.
Example: template:setRepairDocked(true)
Returns the object it was called on. - ShipTemplate ShipTemplate:setRestocksScanProbes(boolean enabled)
- Defines whether ShipTemplateBasedObjects created from this ShipTemplate restock scan probes on docked PlayerSpaceships.
Defaults to false.
Example: template:setRestocksScanProbes(true)
Returns the object it was called on. - ShipTemplate ShipTemplate:setRestocksMissilesDocked(boolean enabled)
- Defines whether ShipTemplateBasedObjects created from this ShipTemplate restock missiles on docked CpuShips.
To restock docked PlayerSpaceships' weapons, use a comms script. See ShipTemplateBasedObject:setCommsScript() and :setCommsFunction().
Defaults to false.
Example template:setRestocksMissilesDocked(true)
Returns the object it was called on. - ShipTemplate ShipTemplate:setJumpDrive(boolean enabled)
- Defines whether SpaceShips created from this ShipTemplate have a jump drive.
Defaults to false.
Example: template:setJumpDrive(true)
Returns the object it was called on. - ShipTemplate ShipTemplate:setJumpDriveRange(number min, number max)
- Sets the minimum and maximum jump distances for SpaceShips created from this ShipTemplate.
Defaults to (5000,50000).
Example: template:setJumpDriveRange(2500,25000) -- sets the minimum jump distance to 2.5U and maximum to 25U
Returns the object it was called on. - ShipTemplate ShipTemplate:setCloaking(boolean enabled)
- Not implemented.
Defaults to false.
Returns the object it was called on. - ShipTemplate ShipTemplate:setWeaponStorage(EMissileWeapons weapon, number amount)
- Sets the storage capacity of the given weapon type for ShipTemplateBasedObjects created from this ShipTemplate.
Example: template:setWeaponStorage("HVLI", 6):setWeaponStorage("Homing",4) -- sets HVLI capacity to 6 and Homing capacity to 4
Returns the object it was called on. - ShipTemplate ShipTemplate:addRoom(number position_x, number position_y, number size_x, number size_y)
- Adds an empty room to a ShipTemplate.
Rooms are displayed on the engineering and damcon screens.
If a system room isn't accessible via other rooms connected by doors, repair crews on PlayerSpaceships might not be able to repair that system.
Rooms are placed on a 0-indexed integer x/y grid, with the given values representing the room's upper-left corner, and are sized by damage crew capacity (minimum 1x1).
To place multiple rooms, declare addRoom() multiple times.
Example: template::addRoom(0,0,3,2) -- adds a 3x2 room with its upper-left coordinate at position 0,0
Returns the object it was called on. - ShipTemplate ShipTemplate:addRoomSystem(number position_x, number position_y, number size_x, number size_y, ESystem system)
- Adds a room containing a ship system to a ShipTemplate.
Rooms are displayed on the engineering and damcon screens.
If a system room doesn't exist or isn't accessible via other rooms connected by doors, repair crews on PlayerSpaceships won't be able to repair that system.
Rooms are placed on a 0-indexed integer x/y grid, with the given values representing the room's upper-left corner, and are sized by damage crew capacity (minimum 1x1).
To place multiple rooms, declare addRoomSystem() multiple times.
Example: template:addRoomSystem(1,2,3,4,"reactor") -- adds a 3x4 room with its upper-left coordinate at position 1,2 that contains the Reactor system
Returns the object it was called on. - ShipTemplate ShipTemplate:addDoor(number position_x, number position_y, boolean horizontal)
- Adds a door between rooms in a ShipTemplate.
Doors connect rooms as displayed on the engineering and damcon screens. All doors are 1 damage crew wide.
If a system room isn't accessible via other rooms connected by doors, repair crews on PlayerSpaceships might not be able to repair that system.
The horizontal value defines whether the door is oriented horizontally (true) or vertically (false).
Doors are placed on a 0-indexed integer x/y grid, with the given values representing the door's left-most point (horizontal) or top-most point (vertical) point.
To place multiple doors, declare addDoor() multiple times.
Example: template:addDoor(2,1,true) -- places a horizontal door with its left-most point at 2,1
Returns the object it was called on. - ShipTemplate ShipTemplate:setRadarTrace(string trace)
- Sets the default radar trace image for ShipTemplateBasedObjects created from this ShipTemplate.
Valid values are filenames of PNG images relative to the resources/radar/ directory.
Radar trace images should be white with a transparent background.
Defaults to ship.png. ShipTemplate:setType("station") sets this to blip.png.
Example: template:setRadarTrace("cruiser.png")
Returns the object it was called on. - ShipTemplate ShipTemplate:setLongRangeRadarRange(number range)
- Sets the long-range radar range of SpaceShips created from this ShipTemplate.
PlayerSpaceships use this range on the science and operations screens' radar.
AI orders of CpuShips use this range to detect potential targets.
Defaults to 30000.0 (30U).
Example: template:setLongRangeRadarRange(20000) -- sets the long-range radar range to 20U
Returns the object it was called on. - ShipTemplate ShipTemplate:setShortRangeRadarRange(number range)
- Sets the short-range radar range of SpaceShips created from this ShipTemplate.
PlayerSpaceships use this range on the helms, weapons, and single pilot screens' radar.
AI orders of CpuShips use this range to decide when to disengage pursuit of fleeing targets.
This also defines the shared radar radius on the relay screen for friendly ships and stations, and how far into nebulae that this SpaceShip can detect objects.
Defaults to 5000.0 (5U).
Example: template:setShortRangeRadarRange(4000) -- sets the short-range radar range to 4U
Returns the object it was called on. - ShipTemplate ShipTemplate:setImpulseSoundFile(string sound)
- Sets the sound file used for the impulse drive sounds on SpaceShips created from this ShipTemplate.
Valid values are filenames to WAV files relative to the resources directory.
Use a looping sound file that tolerates being pitched up and down as the ship's impulse speed changes.
Defaults to sfx/engine.wav.
Example: template:setImpulseSoundFile("sfx/engine_fighter.wav")
Returns the object it was called on. - ShipTemplate ShipTemplate:setCanScan(boolean enabled)
- Defines whether scanning features appear on related crew screens in PlayerSpaceships created from this ShipTemplate.
Defaults to true.
Example: template:setCanScan(false)
Returns the object it was called on. - ShipTemplate ShipTemplate:setCanHack(boolean enabled)
- Defines whether hacking features appear on related crew screens in PlayerSpaceships created from this ShipTemplate.
Defaults to true.
Example: template:setCanHack(false)
Returns the object it was called on. - ShipTemplate ShipTemplate:setCanDock(boolean enabled)
- Defines whether the "Request Docking" button appears on related crew screens in PlayerSpaceships created from this ShipTemplate.
Defaults to true.
Example: template:setCanDock(false)
Returns the object it was called on. - ShipTemplate ShipTemplate:setCanCombatManeuver(boolean enabled)
- Defines whether combat maneuver controls appear on related crew screens in PlayerSpaceships created from this ShipTemplate.
Defaults to true.
Example: template:setCanCombatManeuver(false)
Returns the object it was called on. - ShipTemplate ShipTemplate:setCanSelfDestruct(boolean enabled)
- Defines whether self-destruct controls appear on related crew screens in PlayerSpaceships created from this ShipTemplate.
Defaults to true.
Example: template:setCanSelfDestruct(false)
Returns the object it was called on. - ShipTemplate ShipTemplate:setCanLaunchProbe(boolean enabled)
- Defines whether ScanProbe-launching controls appear on related crew screens in PlayerSpaceships created from this ShipTemplate.
Defaults to true.
Example: template:setCanLaunchProbe(false)
Returns the object it was called on. - ShipTemplate ShipTemplate:copy(string new_name)
- Returns an exact copy of this ShipTemplate and sets the new copy's reference name to the given name, as ShipTemplate:setName().
The copy retains all other traits of the copied ShipTemplate.
Use this function to create variations of an existing ShipTemplate.
Example:
-- Create two ShipTemplates: one with 50 hull points and one 50-point shield segment,
-- and a second with 50 hull points and two 25-point shield segments.
template = ShipTemplate():setName("Stalker Q7"):setHull(50):setShields(50)
variation = template:copy("Stalker Q5"):setShields(25,25) - boolean ShipTemplate:isValid()
- Returns whether this object is still valid. Returns false if this object was destroyed or doesn't exist.
- ShipTemplate ShipTemplate:destroy()
- Removes this object from the game.
Returns the object it was called on. - ShipTemplate:typeName
- Returns the class name of this object. This is not a function, but a direct member. Example: if object.typeName == "Mine" then print("MINE!") end
SpaceObject
SpaceObject is the base class for every object in the game universe.
Scripts can't create SpaceObjects directly, but all objects of SpaceObject subclasses can also access these core functions.
Each object has a position, rotation, and collision shape.
The Collisionable class is provided by SeriousProton.
- SpaceObject SpaceObject:setPosition(number v_x, number v_y)
- Sets this SpaceObject's position on the map, in meters from the origin.
Example: obj:setPosition(x,y)
Returns the object it was called on. - number x, number y SpaceObject:getPosition()
- Returns this object's position on the map.
Example: x,y = obj:getPosition() - SpaceObject SpaceObject:setRotation(number angle)
- Sets this SpaceObject's absolute rotation, in degrees.
Unlike SpaceObject:setHeading(), a value of 0 points to the right of the map ("east").
The value can also be unbounded; it can be negative, or greater than 360 degrees.
SpaceObject:setHeading() and SpaceObject:setRotation() do not change the helm's target heading on PlayerSpaceships. To do that, use PlayerSpaceship:commandTargetRotation().
Example: obj:setRotation(270)
Returns the object it was called on. - number SpaceObject:getRotation()
- Returns this SpaceObject's absolute rotation, in degrees.
Example: local rotation = obj:getRotation() - SpaceObject SpaceObject:setHeading(number heading)
- Sets this SpaceObject's heading, in degrees ranging from 0 to 360.
Unlike SpaceObject:setRotation(), a value of 0 points to the top of the map ("north").
Values that are negative or greater than 360 are converted to values within that range.
SpaceObject:setHeading() and SpaceObject:setRotation() do not change the helm's target heading on PlayerSpaceships. To do that, use PlayerSpaceship:commandTargetRotation().
Example: obj:setHeading(0)
Returns the object it was called on. - number SpaceObject:getHeading()
- Returns this SpaceObject's heading, in degrees ranging from 0 to 360.
Example: heading = obj:getHeading(0) - number x, number y SpaceObject:getVelocity()
- Returns this SpaceObject's directional velocity within 2D space as an x/y vector.
The values are relative x/y coordinates from the SpaceObject's current position (a 2D velocity vector).
Example: vx,vy = obj:getVelocity() - number SpaceObject:getAngularVelocity()
- Returns this SpaceObject's rotational velocity within 2D space, in degrees per second.
Example: obj:getAngularVelocity() - SpaceObject SpaceObject:setFaction(string faction_name)
- Sets the faction to which this SpaceObject belongs, by faction name.
Factions are defined by the FactionInfo class, and default factions are defined in scripts/factionInfo.lua.
Requires a faction name string.
Example: obj:setFaction("Human Navy")
Returns the object it was called on. - string SpaceObject:getFaction()
- Returns the name of the faction to which this SpaceObject belongs.
Example: obj:getFaction() - string SpaceObject:getLocaleFaction()
- Returns the localized name of the faction to which this SpaceObject belongs.
Example: obj:getLocaleFaction() - SpaceObject SpaceObject:setFactionId(number faction_id)
- Returns the faction to which this SpaceObject belongs, by the faction's index in the faction list.
Use with SpaceObject:getFactionId() to ensure that two objects belong to the same faction.
Example: local faction_id = obj:getFactionId()
Returns the object it was called on. - number SpaceObject:getFactionId()
- Returns the faction list index for the faction to which this SpaceObject belongs.
Use with SpaceObject:setFactionId() to ensure that two objects belong to the same faction.
Example: obj:setFactionId(target:getFactionId()) - boolean SpaceObject:isEnemy(SpaceObject obj)
- Returns the friend-or-foe status of the given faction relative to this SpaceObject's faction.
Returns true if the given SpaceObject's faction is hostile to this object's.
Example: obj:isEnemy(target) - boolean SpaceObject:isFriendly(SpaceObject obj)
- Returns the friend-or-foe status of the given faction relative to this SpaceObject's faction.
Returns true if the given SpaceObject's faction is friendly to this object's.
If an object is neither friendly nor enemy, it is neutral.
Example: obj:isFriendly(target) - SpaceObject SpaceObject:setCommsScript(string script_name)
- Sets the communications script used when this SpaceObject is hailed.
Accepts the filename of a Lua script relative to the scripts/ directory.
If set to an empty string, comms with this object are disabled.
The globals comms_source (PlayerSpaceship) and comms_target (SpaceObject) are made available in the scenario script.
Subclasses set their own default comms scripts.
For object types without defaults, or when creating custom comms scripts, use setCommsMessage() to define the message and addCommsReply() to provide player response options.
See also SpaceObject:setCommsFunction().
Examples:
obj:setCommsScript("comms_custom_script.lua") -- sets scripts/comms_custom_script.lua as this object's comms script
obj:setCommsScript("") -- disables comms with this object
Returns the object it was called on. - SpaceObject SpaceObject:setCommsFunction(ScriptSimpleCallback callback)
- Defines a function to call when this SpaceObject is hailed, in lieu of any current or default comms script.
For a detailed example, see scripts/scenario_53_escape.lua.
TODO: Confirm this: The globals comms_source (PlayerSpaceship) and comms_target (SpaceObject) are made available in the scenario script.
They remain as globals. As usual, such globals are not accessible in required files.
Instead of using the globals, the callback can optionally take two equivalent parameters.
See also SpaceObject:setCommsScript().
Examples:
obj:setCommsFunction(function(comms_source, comms_target) ... end)
Example: obj:setCommsFunction(commsStation) -- where commsStation is a function that calls setCommsMessage() at least once, and uses addCommsReply() to let players respond
Returns the object it was called on. - SpaceObject SpaceObject:setCallSign(string new_callsign)
- Sets this SpaceObject's callsign.
EmptyEpsilon generates random callsigns for objects upon creation, and this function overrides that default.
Example: obj:setCallSign("Epsilon")
Returns the object it was called on. - boolean SpaceObject:sendCommsMessage(PlayerSpaceship target, string message)
- Hails a PlayerSpaceship from this SpaceObject.
The PlayerSpaceship's comms position is notified and can accept or refuse the hail.
If the PlayerSpaceship accepts the hail, this displays the given message.
Returns true when the hail is accepted.
Returns false if the hail is refused, or when the target player cannot be hailed right now, for example because it's already communicating with something else.
This logs a message in the target's comms log. To avoid logging, use SpaceObject:sendCommsMessageNoLog().
Requires a target PlayerShip and message, though the message can be an empty string.
Example: obj:sendCommsMessage(player, "Prepare to die") - boolean SpaceObject:sendCommsMessageNoLog(PlayerSpaceship target, string message)
- As SpaceObject:sendCommsMessage(), but does not log a failed hail to the target ship's comms log.
Example: obj:sendCommsMessageNoLog(player, "Prepare to die") - boolean SpaceObject:openCommsTo(PlayerSpaceship target)
- As SpaceObject:sendCommsMessage(), but sends an empty string as the message.
This calls the SpaceObject's comms function.
Example: obj:openCommsTo(player) - string SpaceObject:getCallSign()
- Returns this SpaceObject's callsign.
Example: obj:getCallSign() - boolean SpaceObject:areEnemiesInRange(number range)
- Returns whether any SpaceObject from a hostile faction are within a given radius of this SpaceObject, in (unit?).
Example: obj:areEnemiesInRange(5000) -- returns true if hostiles are within 5U of this object - SpaceObject[] SpaceObject:getObjectsInRange(number range)
- Returns any SpaceObject within a specific radius, in (unit?), of this SpaceObject.
Returns a list of all SpaceObjects within range.
Example: obj:getObjectsInRange(5000) -- returns all objects within 5U of this SpaceObject. - number SpaceObject:getReputationPoints()
- Returns this SpaceObject's faction reputation points.
Example: obj:getReputationPoints() - SpaceObject SpaceObject:setReputationPoints(number amount)
- Sets this SpaceObject's faction reputation points to the given amount.
Example: obj:setReputationPoints(1000)
Returns the object it was called on. - boolean SpaceObject:takeReputationPoints(number amount)
- Deducts a given number of faction reputation points from this SpaceObject.
Returns true if there are enough points to deduct the specified amount, then does so.
Returns false if there are not enough points, then does not deduct any.
Example: obj:takeReputationPoints(1000) -- returns false if `obj` has fewer than 1000 reputation points, otherwise returns true and deducts the points - SpaceObject SpaceObject:addReputationPoints(number amount)
- Adds a given number of faction reputation points to this SpaceObject.
Example: obj:addReputationPoints(1000)
Returns the object it was called on. - string SpaceObject:getSectorName()
- Returns the name of the map sector, such as "A4", where this SpaceObject is located.
Example: obj:getSectorName() - SpaceObject SpaceObject:takeDamage(number damage_amount, DamageInfo info)
- Deals a specific amount of a specific type of damage to this SpaceObject.
Requires a numeric value for the damage amount, and accepts an optional DamageInfo type.
The optional DamageInfo parameter can be empty, which deals "energy" damage, or a string that indicates which type of damage to deal.
Valid damage types are "energy", "kinetic", and "emp".
If you specify a damage type, you can also optionally specify the location of the damage's origin, for instance to damage a specific shield segment on the target.
SpaceObjects by default do not implement damage, instead leaving it to be overridden by specialized subclasses.
Examples:
obj:takeDamage(20, "emp", 1000, 0) -- deals 20 EMP damage as if it had originated from coordinates 1000,0
obj:takeDamage(20) -- deals 20 energy damage
Returns the object it was called on. - SpaceObject SpaceObject:setDescriptions(string unscanned_description, string scanned_description)
- Sets this SpaceObject's description in unscanned and scanned states.
The science screen displays these descriptions when targeting a scanned object.
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 SpaceObject:setDescription(string description)
- As setDescriptions, but sets the same description for both unscanned and scanned states.
Example: obj:setDescription("A refitted Atlantis X23 for more ...")
Returns the object it was called on. - SpaceObject SpaceObject:setDescriptionForScanState(EScannedState state, string description)
- Sets a description for a given EScannedState on this SpaceObject.
Only SpaceShip objects are created in an unscanned state. Other SpaceObjects are created as fully scanned.
- "notscanned" or "not": The object has not been scanned.
- "friendorfoeidentified": The object has been identified as hostile or friendly, but has not been scanned.
- "simplescan" or "simple": The object has been scanned once under default server settings, displaying only basic information about the object.
- "fullscan" or "full": The object is fully scanned.
Example: obj:setDescriptionForScanState("friendorfoeidentified", "A refitted...")
Returns the object it was called on. - string SpaceObject:getDescription(EScannedState state)
- Returns this SpaceObject's description for the given EScannedState.
Accepts an optional string-equivalent EScannedState, which determines which description to return.
Defaults to returning the "fullscan" description.
Examples:
obj:getDescription() -- returns the "fullscan" description
obj:getDescription("friendorfoeidentified") -- returns the "friendorfoeidentified" description - SpaceObject SpaceObject:setRadarSignatureInfo(number grav, number elec, number bio)
- Sets this SpaceObject's radar signature, which creates noise on the science screen's raw radar signal ring.
The raw signal ring contains red, green, and blue bands of waveform noise.
Certain SpaceObject subclasses might set their own defaults or dynamically modify their signatures using this value as a baseline.
Requires numeric values ranging from 0.0 to 1.0 for the gravitational, electrical, and biological radar bands, in that order.
Larger and negative values are possible, but currently have no visual effect on the bands.
- Gravitational signatures amplify noise on all bands, particularly the green and blue bands.
- Electrical signatures amplify noise on the red and blue bands.
- Biological signatures amplify noise on the red and green bands.
Example: obj:setRadarSignatureInfo(0.0, 0.5, 1.0) -- a radar signature of 0 gravitational, 0.5 electrical, and 1.0 biological
Returns the object it was called on. - number SpaceObject:getRadarSignatureGravity()
- Returns this SpaceObject's gravitational radar signature value.
Example: obj:getRadarSignatureGravity() - number SpaceObject:getRadarSignatureElectrical()
- Returns this SpaceObject's electical radar signature value.
Example: obj:getRadarSignatureElectrical() - number SpaceObject:getRadarSignatureBiological()
- Returns this SpaceObject's biological radar signature value.
Example: obj:getRadarSignatureBiological() - SpaceObject SpaceObject:setScanningParameters(number complexity, number depth)
- Sets this SpaceObject's scanning complexity (number of bars in the scanning minigame) and depth (number of scanning minigames to complete until fully scanned), respectively.
Setting this also clears the object's scanned state.
Example: obj:setScanningParameters(2, 3)
Returns the object it was called on. - number SpaceObject:scanningComplexity(SpaceObject target)
- Returns the scanning complexity for the given SpaceObject.
Example: obj:scanningComplexity(obj) - number SpaceObject:scanningChannelDepth(SpaceObject target)
- Returns the maximum scanning depth for the given SpaceObject.
Example: obj:scanningChannelDepth(obj) - SpaceObject SpaceObject:setScanned(boolean scanned)
- Defines whether all factions consider this SpaceObject as having been scanned.
Only SpaceShip objects are created in an unscanned state. Other SpaceObjects are created as fully scanned.
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 SpaceObject:isScanned()
- [DEPRECATED]
Returns whether this SpaceObject has been scanned.
Use SpaceObject:isScannedBy() or SpaceObject:isScannedByFaction() instead. - boolean SpaceObject:isScannedBy(SpaceObject obj)
- Returns whether the given SpaceObject has successfully scanned this SpaceObject.
Example: obj:isScannedBy(other) - SpaceObject SpaceObject:setScannedByFaction(string faction_name, boolean scanned)
- Defines whether a given faction considers this SpaceObject as having been scanned.
Requires a faction name string value as defined by its FactionInfo, and a Boolean value.
Example: obj:setScannedByFaction("Human Navy", false)
Returns the object it was called on. - boolean SpaceObject:isScannedByFaction(string faction)
- Returns whether the given faction has successfully scanned this SpaceObject.
Requires a faction name string value as defined by its FactionInfo.
Example: obj:isScannedByFaction("Human Navy") - SpaceObject SpaceObject:onDestroyed(ScriptSimpleCallback callback)
- Defines a function to call when this SpaceObject is destroyed by any means.
Example:
-- Prints to the console window or logging file when this SpaceObject is destroyed
obj:onDestroyed(function() print("Object destroyed!") end)
Returns the object it was called on. - boolean SpaceObject:isValid()
- Returns whether this object is still valid. Returns false if this object was destroyed or doesn't exist.
- SpaceObject SpaceObject:destroy()
- Removes this object from the game.
Returns the object it was called on. - SpaceObject:typeName
- Returns the class name of this object. This is not a function, but a direct member. Example: if object.typeName == "Mine" then print("MINE!") end
Artifact
An Artifact is a configurable SpaceObject that can interact with other objects via collisions or scripting.
Use this to define arbitrary objects or collectible pickups in scenario scripts.
Example: artifact = Artifact():setModel("artifact6"):setSpin(0.5)
Subclass of:
SpaceObject- Artifact Artifact:setModel(string name)
- Sets the 3D model used for this artifact, by its ModelData name.
ModelData is defined in scripts/model_data.lua.
Defaults to a ModelData whose name starts with "artifact" and ends with a random number between 1 and 8.
Example: artifact:setModel("artifact6")
Returns the object it was called on. - Artifact Artifact:explode()
- Immediately destroys this artifact with a visual explosion.
Example: artifact:explode() -- artifact is destroyed
Returns the object it was called on. - Artifact Artifact:allowPickup(boolean allow)
- Defines whether this artifact can be picked up via collision.
The artifact is destroyed upon being picked up.
Defaults to false.
Example: artifact:allowPickup(true)
Returns the object it was called on. - Artifact Artifact:onCollision(ScriptSimpleCallback callback)
- Defines a function to call every tick when a SpaceObject is colliding with the artifact.
Passes the artifact and colliding SpaceObject to the called function.
Example: artifact:onCollision(function(artifact, collider) print("Collision occurred") end)
Returns the object it was called on. - Artifact Artifact:onPlayerCollision(ScriptSimpleCallback callback)
- Defines a function to call every tick when a PlayerSpaceship is colliding with the artifact.
Passes the artifact and colliding PlayerSpaceship to the called function.
Example: artifact:onCollision(function(artifact, player) print("Collision occurred") end)
Returns the object it was called on. - Artifact Artifact:onPickUp(ScriptSimpleCallback callback)
- Defines a function to call once when a PlayerSpaceship collides with the artifact and allowPickup is enabled.
Passes the artifact and colliding PlayerSpaceship to the called function.
Example: artifact:onPickUp(function(artifact, player) print("Artifact retrieved") end)
Returns the object it was called on. - Artifact Artifact:onPickup(ScriptSimpleCallback callback)
- Alias of Artifact:onPickUp().
Returns the object it was called on. - Artifact Artifact:setSpin(number spin=0.0)
- Defines whether the artifact rotates, and if so at what rotational velocity. (unit?)
For reference, normal asteroids spin at a rate between 0.1 and 0.8.
Example: artifact:setSpin(0.5)
Returns the object it was called on. - Artifact Artifact:setRadarTraceIcon(string icon)
- Sets the radar trace image for this artifact.
Optional. Defaults to "blip.png".
Valid values are filenames to PNG files relative to resources/radar/.
Example: artifact:setRadarTraceIcon("arrow.png") -- displays an arrow instead of a blip for this artifact
Returns the object it was called on. - Artifact Artifact:setRadarTraceScale(number scale)
- Scales the radar trace for this artifact.
A value of 0 restores standard autoscaling relative to the artifact's radius.
Set to 1 to mimic ship traces.
Example: artifact:setRadarTraceScale(0.7)
Returns the object it was called on. - Artifact Artifact:setRadarTraceColor(number r, number g, number b)
- Sets the color of this artifact's radar trace.
Optional. Defaults to solid white (255,255,255)
Example: artifact:setRadarTraceColor(255,200,100) -- mimics an asteroid
Returns the object it was called on.
Asteroid
An Asteroid is an inert piece of space terrain.
Upon collision with another SpaceObject, it deals damage and is destroyed.
It has a default rotation speed, random z-offset, and model, and AI behaviors attempt to avoid hitting them.
To create a customizable object with more complex actions upon collisions, use an Artifact or SupplyDrop.
For a purely decorative asteroid positioned outside of the movement plane, use a VisualAsteroid.
Example: asteroid = Asteroid():setSize(150):setPosition(1000,2000)
Subclass of:
SpaceObject- Asteroid Asteroid:setSize(number size)
- Sets this Asteroid's radius.
Defaults to a random value between 110 and 130.
Example: asteroid:setSize(150)
Returns the object it was called on. - number Asteroid:getSize()
- Returns this Asteroid's radius.
Example: asteroid:getSize()
BeamEffect
A BeamEffect is a beam weapon firing audio/visual effect that fades after its duration expires.
This is a cosmetic effect and does not deal damage on its own.
Example: beamfx = BeamEffect():setSource(player,0,0,0):setTarget(enemy,0,0,0)
Subclass of:
SpaceObject- BeamEffect BeamEffect:setSource(SpaceObject source, number offset_x, number offset_y, number offset_z)
- Sets the BeamEffect's origin SpaceObject.
Requires a 3D x/y/z vector positional offset relative to the object's origin point.
Example: beamfx:setSource(0,0,0)
Returns the object it was called on. - BeamEffect BeamEffect:setTarget(SpaceObject target, number hitLocation_x, number hitLocation_y)
- Sets the BeamEffect's target SpaceObject.
Requires a 3D x/y/z vector positional offset relative to the object's origin point.
Example: beamfx:setTarget(target,0,0,0)
Returns the object it was called on. - BeamEffect BeamEffect:setTexture(string texture)
- Sets the BeamEffect's texture.
Valid values are filenames of PNG files relative to the resources/ directory.
Defaults to "texture/beam_orange.png".
Example: beamfx:setTexture("beam_blue.png")
Returns the object it was called on. - BeamEffect BeamEffect:setBeamFireSound(string sound)
- Sets the BeamEffect's sound effect.
Valid values are filenames of WAV files relative to the resources/ directory.
Defaults to "sfx/laser_fire.wav".
Example: beamfx:setBeamFireSound("sfx/hvli_fire.wav")
Returns the object it was called on. - BeamEffect BeamEffect:setBeamFireSoundPower(number power)
- Sets the magnitude of the BeamEffect's sound effect.
Defaults to 1.0.
Larger values are louder and can be heard from larger distances.
This value also affects the sound effect's pitch.
Example: beamfx:setBeamFireSoundPower(0.5)
Returns the object it was called on. - BeamEffect BeamEffect:setDuration(number duration)
- Sets the BeamEffect's duration, in seconds.
Defaults to 1.0.
Example: beamfx:setDuration(1.5)
Returns the object it was called on. - BeamEffect BeamEffect:setRing(boolean ring)
- Defines whether the BeamEffect generates an impact ring on the target end.
Defaults to true.
Example: beamfx:setRing(false)
Returns the object it was called on.
BlackHole
A BlackHole is a piece of space terrain that pulls all nearby SpaceObjects within a 5U radius, including otherwise immobile objects like SpaceStations, toward its center.
A SpaceObject capable of taking damage is dealt an increasing amount of damage as it approaches the BlackHole's center.
Upon reaching the center, any SpaceObject is instantly destroyed even if it's otherwise incapable of taking damage.
AI behaviors avoid BlackHoles by a 2U margin.
In 3D space, a BlackHole resembles a black sphere with blue horizon.
Example: black_hole = BlackHole():setPosition(1000,2000)
Subclass of:
SpaceObject
ElectricExplosionEffect
An ElectricExplosionEffect is a visual electrical explosion used by EMP missiles.
This is a cosmetic effect and does not deal damage on its own.
See also the ExplosionEffect class for conventional explosion effects.
Example: elec_explosion = ElectricExplosionEffect():setPosition(500,5000):setSize(20):setOnRadar(true)
Subclass of:
SpaceObject- ElectricExplosionEffect ElectricExplosionEffect:setSize(number size)
- Sets the ElectricExplosionEffect's radius.
Defaults to 1.0.
Example: elec_explosion:setSize(1000) -- sets the explosion radius to 1U
Returns the object it was called on. - ElectricExplosionEffect ElectricExplosionEffect:setOnRadar(boolean on_radar)
- Defines whether to draw the ElectricExplosionEffect on short-range radar.
Defaults to false.
Example: elec_explosion:setOnRadar(true)
Returns the object it was called on.
ExplosionEffect
An ExplosionEffect is a visual explosion used by nukes, homing missiles, ship destruction, and other similar events.
This is a cosmetic effect and does not deal damage on its own.
See also the ElectricExplosionEffect class for EMP missile effects.
Example: explosion = ExplosionEffect():setPosition(500,5000):setSize(20):setOnRadar(true)
Subclass of:
SpaceObject- ExplosionEffect ExplosionEffect:setSize(number size)
- Sets the ExplosionEffect's radius.
Defaults to 1.0.
Example: explosion:setSize(1000) -- sets the explosion radius to 1U
Returns the object it was called on. - ExplosionEffect ExplosionEffect:setOnRadar(boolean on_radar)
- Defines whether to draw the ExplosionEffect on short-range radar.
Defaults to false.
Example: explosion:setOnRadar(true)
Returns the object it was called on.
Mine
A Mine is an explosive weapon that detonates and deals kinetic damage when a SpaceObject collides with its trigger range.
Mines can be owned by factions but are triggered by SpaceObjects of any faction can trigger them.
Mines can be launched from a SpaceShip's weapon tube or added by a GM or scenario script.
When launched from a SpaceShip, the mine has an eject timeout, during which its trigger range is inactive.
In 3D views, mines are represented by a particle effect at the center of its trigger range.
To create objects with more complex collision mechanics, use an Artifact.
Example: mine = Mine():setPosition(1000,1000):onDestruction(this_mine, instigator) print("Tripped a mine!") end)
Subclass of:
SpaceObject- SpaceObject Mine:getOwner()
- Returns this Mine owner's SpaceObject.
Works only on the server; mine ownership isn't replicated to clients.
Example: mine:getOwner() - Mine Mine:onDestruction(ScriptSimpleCallback callback)
- Defines a function to call when this Mine is destroyed.
Passes the mine object and the object of the mine's owner/instigator (or nil if there isn't one) to the function.
Example: mine:onDestruction(function(this_mine, instigator) print("Tripped a mine!") end)
Returns the object it was called on.
MissileWeapon
A MissileWeapon is a self-propelled weapon that can be fired from a WeaponTube at either a target SpaceObject or on a trajectory.
MissileWeapons that can explode detonate with a blast radius at either the end of its lifetime or upon collision with another collisionable SpaceObject.
MissileWeapon-class objects can't be created directly. Use these functions with subclasses derived from MissileWeapon, such as HomingMissile, HVLI, etc.
(While also launchable from WeaponTubes, Mines are not MissileWeapons. See the Mine class.)
Subclass of:
SpaceObject- SpaceObject MissileWeapon:getOwner()
- Returns this MissileWeapon owner's SpaceObject.
Example: missile:getOwner() - SpaceObject MissileWeapon:getTarget()
- Returns this MissileWeapon's target.
Example: missile:getTarget() - MissileWeapon MissileWeapon:setTarget(SpaceObject target)
- Sets this MissileWeapon's target.
The target must already exist. If it does not, this has no effect.
MissileWeapon:setTarget() does NOT check whether the target can be targeted by a player.
Example: missile:setTarget(enemy)
Returns the object it was called on. - number MissileWeapon:getLifetime()
- Returns this MissileWeapon's lifetime, in seconds.
Example: missile:getLifetime() - MissileWeapon MissileWeapon:setLifetime(number lifetime)
- Sets this MissileWeapon's lifetime, in seconds.
A missile that can explode does so at the end of its lifetime if it don't hit another collisionable SpaceObject first.
Example: missile:setLifetime(5.0)
Returns the object it was called on. - EMissileSizes MissileWeapon:getMissileSize()
- Returns this MissileWeapon's size as an EMissileSizes string.
Example: missile:getMissileSize() - MissileWeapon MissileWeapon:setMissileSize(EMissileSizes missile_size)
- Sets this MissileWeapon's size.
Size modifies a missile's maneuverability, speed, blast radius, lifetime, and damage.
Smaller missiles are weaker, faster, and more nimble. Larger missiles are more powerful, slower, and have a longer lifetime.
Example: missile:setMissileSize("large") -- sets this missile to be large
Returns the object it was called on.
EMPMissile
An EMPMissile is an electromagnetic pulse MissileWeapon that pursues a target and, upon explosion, deals a base of 30-160 EMP damage to shields within its 1U base blast radius.
It inherits functions and behaviors from its parent MissileWeapon class.
Missiles can be fired by SpaceShips or created by scripts, and their damage and blast radius can be modified by missile size.
AI behaviors attempt to avoid EMPMissiles.
Example: emp_missile = EMPMissile:setPosition(1000,1000):setTarget(enemy):setLifetime(40):setMissileSize("large")
Subclass of:
MissileWeapon
HVLI
An HVLI is a high-velocity lead impactor, a fancy name for an unguided bullet MissileWeapon that deals kinetic damage upon impact.
Damage is reduced if the HVLI has been alive for less than 2 seconds.
It inherits functions and behaviors from its parent MissileWeapon class.
Missiles can be fired by SpaceShips or created by scripts, and their damage and blast radius can be modified by missile size.
Example: hvli = HVLI:setPosition(1000,1000):setRotation(90):setLifetime(40):setMissileSize("large")
Subclass of:
MissileWeapon
HomingMissile
A HomingMissile is a nimble MissileWeapon that pursues a target and, upon explosion, deals a base of 35 kinetic damage to its target.
It inherits functions and behaviors from its parent MissileWeapon class.
Missiles can be fired by SpaceShips or created by scripts, and their damage and blast radius can be modified by missile size.
Example: homing_missile = HomingMissile:setPosition(1000,1000):setTarget(enemy):setLifetime(40):setMissileSize("large")
Subclass of:
MissileWeapon
Nuke
A HomingMissile is a MissileWeapon that pursues a target and, upon explosion, deals a base of 30-160 kinetic damage to all SpaceObjects within its 1U base blast radius.
It inherits functions and behaviors from its parent MissileWeapon class.
Missiles can be fired by SpaceShips or created by scripts, and their damage and blast radius can be modified by missile size.
AI behaviors attempt to avoid EMPMissiles.
Example: nuke_missile = Nuke:setPosition(1000,1000):setTarget(enemy):setLifetime(40):setMissileSize("large")
Subclass of:
MissileWeapon
Nebula
A Nebula is a piece of space terrain with a 5U radius that blocks long-range radar, but not short-range radar.
This hides any SpaceObjects inside of a Nebula, as well as SpaceObjects on the other side of its radar "shadow", from any SpaceShip outside of it.
Likewise, a SpaceShip fully inside of a nebula has effectively no long-range radar functionality.
In 3D space, a Nebula resembles a dense cloud of colorful gases.
Example: nebula = Nebula():setPosition(1000,2000)
Subclass of:
SpaceObject
Planet
A Planet is a spherical piece of space terrain that can orbit other SpaceObjects.
Each Planet has separate textures for its surface, atmosphere, and cloud layers.
Several planetary textures are included in the resources/planets/ directory.
Planets can collide with objects and run callback functions upon collisions.
Examples:
-- Creates a small planetary system with a sun, a planet orbiting the sun, and a moon orbiting the planet.
sun = Planet():setPosition(5000, 15000):setPlanetRadius(1000):setPlanetAtmosphereTexture("planets/star-1.png"):setPlanetAtmosphereColor(1.0, 1.0, 1.0)
planet = Planet():setPosition(5000, 5000):setPlanetRadius(3000):setPlanetSurfaceTexture("planets/planet-1.png")
planet:setPlanetCloudTexture("planets/clouds-1.png"):setPlanetAtmosphereTexture("planets/atmosphere.png"):setPlanetAtmosphereColor(0.2, 0.2, 1.0):setOrbit(sun,40)
moon = Planet():setPosition(5000, 0):setPlanetRadius(1000):setPlanetSurfaceTexture("planets/moon-1.png"):setAxialRotationTime(20.0):setOrbit(planet,20)
Subclass of:
SpaceObject- Planet Planet:setPlanetAtmosphereColor(number r, number g, number b)
- Sets this Planet's atmospheric effect color.
Example: planet:setPlanetAtmosphereColor(0.2,0.2,1.0) -- sets a blue atmosphere
Returns the object it was called on. - Planet Planet:setPlanetAtmosphereTexture(string texture_name)
- Sets this Planet's atmospheric effect texture.
Valid values are filenames of PNG files relative to the resources/ directory.
Optional; if defined, atmosphere textures should be transparent or translucent.
For stars, you can set an atmosphere texture such as planets/star-1.png with no surface texture.
Example: planet:setPlanetSurfaceTexture("planets/atmosphere.png")
Returns the object it was called on. - Planet Planet:setPlanetSurfaceTexture(string texture_name)
- Sets this Planet's surface texture.
Valid values are filenames of PNG files relative to the resources/ directory.
Optional; if defined, surface textures should be opaque and use a 2:1-ratio equirectangular projection.
Example: planet:setPlanetSurfaceTexture("planets/planet-1.png")
Returns the object it was called on. - Planet Planet:setPlanetCloudTexture(string texture_name)
- Sets this Planet's cloud layer effect texture, which rotates independently of the planet.
Valid values are filenames of PNG files relative to the resources/ directory.
Optional; if defined, cloud layer textures should be transparent or translucent.
Example: planet:setPlanetCloudTexture("planets/cloud-1.png")
Returns the object it was called on. - number Planet:getPlanetRadius()
- Returns this Planet's radius.
Example: planet:getPlanetRadius() - Planet Planet:setPlanetRadius(number size)
- Sets this Planet's radius, which also sets:
- its cloud radius to 1.05x this value
- its atmosphere radius to 1.2x this value
- its collision size to a function of this value and the planet's z-position
Defaults to 5000 (5U).
Example: planet:setPlanetRadius(2000)
Returns the object it was called on. - number Planet:getCollisionSize()
- Sets this Planet's collision radius.
Defaults to a function of the Planet's radius and its z-position.
AI behaviors use this size to plot routes that try to avoid colliding with this Planet.
Example: planet:getCollisionSize() - Planet Planet:setPlanetCloudRadius(number size)
- Sets this Planet's cloud radius, overriding Planet:setPlanetRadius().
Defaults to 1.05x this Planet's radius.
If this value isn't larger than the Planet's radius, the cloud layer won't be visible.
Example: planet:setPlanetCloudRadius(2500) -- sets this Planet's cloud radius to 2.5U
Returns the object it was called on. - Planet Planet:setDistanceFromMovementPlane(number distance_from_movement_plane)
- Sets the z-position of this Planet, the distance by which it's offset above (positive) or below (negative) the movement plane.
This value also modifies the Planet's collision radius.
Defaults to 0.
Example: planet:setDistanceFromMovementPlane(-500) -- sets the planet 0.5U below the movement plane
Returns the object it was called on. - Planet Planet:setAxialRotationTime(number time)
- Sets this Planet's axial rotation time, in degrees per tick.
Defaults to 0.
Example: planet:setAxialRotationTime(20)
Returns the object it was called on. - Planet Planet:setOrbit(SpaceObject target, number orbit_time)
- Sets a SpaceObject around which this Planet orbits, as well as its orbital period in orbital degrees per tick.
Example: moon:setOrbit(planet,20)
Returns the object it was called on.
ScanProbe
A ScanProbe deploys a short-range radar with a limited lifetime at a high speed to a specific point.
ScanProbes can be targeted and destroyed by hostiles.
It's typically launched by the relay officer and can be linked to the science radar, but can also be created by scripts.
PlayerSpaceships have a limited stock of ScanProbes typically replenished automatically when docked to a SpaceStation or SpaceShip with the ScanProbe restocking feature enabled.
Example: probe = ScanProbe():setSpeed(1500):setLifetime(60 * 30):setTarget(10000,10000):onArrival(function() print("Probe arrived!") end)
Subclass of:
SpaceObject- ScanProbe ScanProbe:setSpeed(number probe_speed)
- Sets this ScanProbe's speed.
Probes move at a fixed rate of speed and ignore collisions and physics while moving.
Defaults to 1000 (1U/second).
Example: probe:setSpeed(2000)
Returns the object it was called on. - number ScanProbe:getSpeed()
- Returns this ScanProbe's speed.
Example: probe:getSpeed() - ScanProbe ScanProbe:setLifetime(number lifetime)
- Sets this ScanProbe's remaining lifetime, in seconds.
Defaults to 600 seconds (10 minutes).
Example: probe:setLifetime(60 * 5) -- sets the lifetime to 5 minutes
Returns the object it was called on. - number ScanProbe:getLifetime()
- Returns this ScanProbe's remaining lifetime.
Example: probe:getLifetime() - ScanProbe ScanProbe:setTarget(number target_x, number target_y)
- Sets this ScanProbe's target coordinates.
If the probe has reached its target, ScanProbe:setTarget() moves it again toward the new target coordinates.
Example: probe:setTarget(1000,5000)
Returns the object it was called on. - number x, number y ScanProbe:getTarget()
- Returns this ScanProbe's target coordinates.
Example: targetX,targetY = probe:getTarget() - ScanProbe ScanProbe:setOwner(SpaceObject owner)
- Sets this ScanProbe's owner SpaceObject.
Example: probe:setOwner(owner)
Returns the object it was called on. - SpaceObject ScanProbe:getOwner()
- Returns this ScanProbe's owner SpaceObject.
Example: probe:getOwner() - ScanProbe ScanProbe:onArrival(ScriptSimpleCallback callback)
- Defines a function to call when this ScanProbe arrives to its target coordinates.
Passes the probe and position as arguments to the function.
Example: probe:onArrival(function(this_probe, coords) print("Probe arrived!") end)
Returns the object it was called on. - ScanProbe ScanProbe:onExpiration(ScriptSimpleCallback callback)
- Defines a function to call when this ScanProbe's lifetime expires.
Passes the probe as an argument to the function.
Example: probe:onExpiration(function(this_probe) print("Probe expired!") end)
Returns the object it was called on. - ScanProbe ScanProbe:onDestruction(ScriptSimpleCallback callback)
- Defines a function to call when this ScanProbe is destroyed by damage.
Passes the probe and instigator as arguments to the function.
Example: probe:onDestruction(function(this_probe, instigator) print("Probe destroyed!") end)
Returns the object it was called on.
ShipTemplateBasedObject
A ShipTemplateBasedObject (STBO) is an object class created from a ShipTemplate.
This is the parent class of SpaceShip (CpuShip, PlayerSpaceship) and SpaceStation objects, which inherit all STBO functions and can be created by scripts.
Objects of this class can't be created by scripts, but SpaceStation and child classes of SpaceShip can.
Subclass of:
SpaceObject- ShipTemplateBasedObject ShipTemplateBasedObject:setTemplate(string template_name)
- Sets this ShipTemplate that defines this STBO's traits, and then applies them to this STBO.
ShipTemplates define the STBO's class, weapons, hull and shield strength, 3D appearance, and more.
See the ShipTemplate class for details, and files in scripts/shiptemplates/ for the default templates.
WARNING: Using a string that is not a valid ShipTemplate name crashes the game!
ShipTemplate string names are case-sensitive.
Examples:
CpuShip():setTemplate("Phobos T3")
PlayerSpaceship():setTemplate("Phobos M3P")
SpaceStation():setTemplate("Large Station")
Returns the object it was called on. - ShipTemplateBasedObject ShipTemplateBasedObject:setShipTemplate(string template_name)
- [DEPRECATED]
Use ShipTemplateBasedObject:setTemplate().
Returns the object it was called on. - ShipTemplateBasedObject ShipTemplateBasedObject:setTypeName(string type_name)
- Sets this STBO's vessel classification name, such as "Starfighter" or "Cruiser".
This overrides the vessel class name provided by the ShipTemplate.
Example: stbo:setTypeName("Prototype")
Returns the object it was called on. - string ShipTemplateBasedObject:getTypeName()
- Returns this STBO's vessel classification name.
Example:
stbo:setTypeName("Prototype")
stbo:getTypeName() -- returns "Prototype" - number ShipTemplateBasedObject:getHull()
- Returns this STBO's hull points.
Example: stbo:getHull() - number ShipTemplateBasedObject:getHullMax()
- Returns this STBO's maximum limit of hull points.
Example: stbo:getHullMax() - ShipTemplateBasedObject ShipTemplateBasedObject:setHull(number amount)
- Sets this STBO's hull points.
If set to a value larger than the maximum, this sets the value to the limit.
If set to a value less than 0, this sets the value to 0.
Note that setting this value to 0 doesn't immediately destroy the STBO.
Example: stbo:setHull(100) -- sets the hull point limit to either 100, or the limit if less than 100
Returns the object it was called on. - ShipTemplateBasedObject ShipTemplateBasedObject:setHullMax(number amount)
- Sets this STBO's maximum limit of hull points.
Note that SpaceStations can't repair their own hull, so this only changes the percentage of remaining hull.
Example: stbo:setHullMax(100) -- sets the hull point limit to 100
Returns the object it was called on. - ShipTemplateBasedObject ShipTemplateBasedObject:setCanBeDestroyed(boolean enabled)
- Defines whether this STBO can be destroyed by damage.
Defaults to true.
Example: stbo:setCanBeDestroyed(false) -- prevents the STBO from being destroyed by damage
Returns the object it was called on. - boolean ShipTemplateBasedObject:getCanBeDestroyed()
- Returns whether the STBO can be destroyed by damage.
Example: stbo:getCanBeDestroyed() - number ShipTemplateBasedObject:getShieldLevel(number index)
- Returns the shield points for this STBO's shield segment with the given index.
Shield segments are 0-indexed.
Example for a ship with two shield segments:
stbo:getShieldLevel(0) -- returns front shield points
stbo:getShieldLevel(1) -- returns rear shield points - number ShipTemplateBasedObject:getShieldCount()
- Returns this STBO's number of shield segments.
Each segment divides the 360-degree shield arc equally for each segment, up to a maximum of 8 segments.
The segments' order starts with the front-facing segment, then proceeds clockwise.
Example: stbo:getShieldCount() - number ShipTemplateBasedObject:getShieldMax(number index)
- Returns the maximum shield points for the STBO's shield segment with the given index.
Example: stbo:getShieldMax(0) -- returns the max shield strength for segment 0 - ShipTemplateBasedObject ShipTemplateBasedObject:setShields(number amounts...)
- Sets this STBO's shield points.
Each number provided as a parameter sets the points for a corresponding shield segment.
Note that the segments' order starts with the front-facing segment, then proceeds clockwise.
If more parameters are provided than the ship has shield segments, the excess parameters are discarded.
Example:
-- On a ship with 4 segments, this sets the forward shield segment to 50, right to 40, rear 30, left 20
-- On a ship with 2 segments, this sets forward 50, rear 40
stbo:setShields(50,40,30,20)
Returns the object it was called on. - ShipTemplateBasedObject ShipTemplateBasedObject:setShieldsMax(number amounts...)
- Sets this STBO's maximum shield points per segment, and can also create new segments.
The number of parameters defines the STBO's number of shield segments, to a maximum of 8 segments.
The segments' order starts with the front-facing segment, then proceeds clockwise.
If more parameters are provided than the STBO has shield segments, the excess parameters create new segments with the defined max but 0 current shield points.
A STBO with one shield segment has only a front shield generator system, and a STBO with two or more segments has only front and rear generator systems.
Setting a lower maximum points value than the segment's current number of points also reduces the points to the limit.
However, increasing the maximum value to a higher value than the current points does NOT automatically increase the current points,
which requires a separate call to ShipTemplateBasedObject:setShield().
Example:
-- On a ship with 4 segments, this sets the forward shield max to 50, right to 40, rear 30, left 20
-- On a ship with 2 segments, this does the same, but its current rear shield points become right shield points, and the new rear and left shield segments have 0 points
stbo:setShieldsMax(50,40,30,20)
Returns the object it was called on. - ShipTemplateBasedObject ShipTemplateBasedObject:setRadarTrace(string trace)
- Sets this STBO's trace image.
Valid values are filenames of PNG images relative to the resources/radar directory.
Radar trace images should be white with a transparent background.
Example: stbo:setRadarTrace("arrow.png") -- sets the radar trace to resources/radar/arrow.png
Returns the object it was called on. - ShipTemplateBasedObject ShipTemplateBasedObject:setImpulseSoundFile(string sound)
- Sets this STBO's impulse engine sound effect.
Valid values are filenames of WAV files relative to the resources/ directory.
Use a looping sound file that tolerates being pitched up and down as the ship's impulse speed changes.
Example: stbo:setImpulseSoundFile("sfx/engine_fighter.wav") -- sets the impulse sound to resources/sfx/engine_fighter.wav
Returns the object it was called on. - boolean ShipTemplateBasedObject:getShieldsActive()
- Defines whether this STBO's shields are activated.
Always returns true except for PlayerSpaceships, because only players can deactivate shields.
Example stbo:getShieldsActive() -- returns true if up, false if down - boolean ShipTemplateBasedObject:getSharesEnergyWithDocked()
- Returns whether this STBO supplies energy to docked PlayerSpaceships.
Example: stbo:getSharesEnergyWithDocked() - ShipTemplateBasedObject ShipTemplateBasedObject:setSharesEnergyWithDocked(boolean enabled)
- Defines whether this STBO supplies energy to docked PlayerSpaceships.
Example: stbo:getSharesEnergyWithDocked(false)
Returns the object it was called on. - boolean ShipTemplateBasedObject:getRepairDocked()
- Returns whether this STBO repairs docked SpaceShips.
Example: stbo:getRepairDocked() - ShipTemplateBasedObject ShipTemplateBasedObject:setRepairDocked(boolean enabled)
- Defines whether this STBO repairs docked SpaceShips.
Example: stbo:setRepairDocked(true)
Returns the object it was called on. - boolean ShipTemplateBasedObject:getRestocksScanProbes()
- Returns whether the STBO restocks scan probes for docked PlayerSpaceships.
Example: stbo:getRestocksScanProbes() - ShipTemplateBasedObject ShipTemplateBasedObject:setRestocksScanProbes(boolean enabled)
- Defines whether the STBO restocks scan probes for docked PlayerSpaceships.
Example: stbo:setRestocksScanProbes(true)
Returns the object it was called on. - boolean ShipTemplateBasedObject:getRestocksMissilesDocked()
- Returns whether this STBO restocks missiles for docked CpuShips.
Example: stbo:getRestocksMissilesDocked() - ShipTemplateBasedObject ShipTemplateBasedObject:setRestocksMissilesDocked(boolean enabled)
- Defines whether this STBO restocks missiles for docked CpuShips.
To restock docked PlayerSpaceships' weapons, use a comms script. See ShipTemplateBasedObject:setCommsScript() and :setCommsFunction().
Example: stbo:setRestocksMissilesDocked(true)
Returns the object it was called on. - number ShipTemplateBasedObject:getLongRangeRadarRange()
- Returns this STBO's long-range radar range.
Example: stbo:getLongRangeRadarRange() - ShipTemplateBasedObject ShipTemplateBasedObject:setLongRangeRadarRange(number range)
- Sets this STBO's long-range radar range.
PlayerSpaceships use this range on the science and operations screens' radar.
AI orders of CpuShips use this range to detect potential targets.
Example: stbo:setLongRangeRadarRange(20000) -- sets the long-range radar range to 20U
Returns the object it was called on. - number ShipTemplateBasedObject:getShortRangeRadarRange()
- Returns this STBO's short-range radar range.
- ShipTemplateBasedObject ShipTemplateBasedObject:setShortRangeRadarRange(number range)
- Sets this STBO's short-range radar range.
PlayerSpaceships use this range on the helms, weapons, and single pilot screens' radar.
AI orders of CpuShips use this range to decide when to disengage pursuit of fleeing targets.
This also defines the shared radar radius on the relay screen for friendly ships and stations, and how far into nebulae that this SpaceShip can detect objects.
Example: stbo:setShortRangeRadarRange(4000) -- sets the short-range radar range to 4U
Returns the object it was called on. - number ShipTemplateBasedObject:getFrontShield()
- [DEPRECATED]
Use ShipTemplateBasedObject:getShieldLevel() with an index value. - number ShipTemplateBasedObject:getFrontShieldMax()
- [DEPRECATED]
Use ShipTemplateBasedObject:setShieldsMax(). - ShipTemplateBasedObject ShipTemplateBasedObject:setFrontShield(number amount)
- [DEPRECATED]
Use ShipTemplateBasedObject:setShieldLevel() with an index value.
Returns the object it was called on. - ShipTemplateBasedObject ShipTemplateBasedObject:setFrontShieldMax(number amount)
- [DEPRECATED]
Use ShipTemplateBasedObject:setShieldsMax().
Returns the object it was called on. - number ShipTemplateBasedObject:getRearShield()
- [DEPRECATED]
Use ShipTemplateBasedObject:getShieldLevel() with an index value. - number ShipTemplateBasedObject:getRearShieldMax()
- [DEPRECATED]
Use ShipTemplateBasedObject:setShieldsMax(). - ShipTemplateBasedObject ShipTemplateBasedObject:setRearShield(number amount)
- [DEPRECATED]
Use ShipTemplateBasedObject:setShieldLevel() with an index value.
Returns the object it was called on. - ShipTemplateBasedObject ShipTemplateBasedObject:setRearShieldMax(number amount)
- [DEPRECATED]
Use ShipTemplateBasedObject:setShieldsMax().
Returns the object it was called on. - ShipTemplateBasedObject ShipTemplateBasedObject:onTakingDamage(ScriptSimpleCallback callback)
- Defines a function to call when this STBO takes damage.
Passes the object taking damage and the instigator SpaceObject (or nil) to the function.
Example: stbo:onTakingDamage(function(this_stbo,instigator) print(this_stbo:getCallSign() .. " was damaged by " .. instigator:getCallSign()) end)
Returns the object it was called on. - ShipTemplateBasedObject ShipTemplateBasedObject:onDestruction(ScriptSimpleCallback callback)
- Defines a function to call when this STBO is destroyed by taking damage.
Passes the object taking damage and the instigator SpaceObject that delivered the destroying damage (or nil) to the function.
Example: stbo:onTakingDamage(function(this_stbo,instigator) print(this_stbo:getCallSign() .. " was destroyed by " .. instigator:getCallSign()) end)
Returns the object it was called on.
SpaceShip
A SpaceShip is a ShipTemplateBasedObject controlled by either the AI (CpuShip) or players (PlayerSpaceship).
It can carry and deploy weapons, dock with or carry docked ships, and move using impulse, jump, or warp drives.
It's also subject to being moved by collision physics, unlike SpaceStations, which remain stationary.
This is the parent class of CpuShip and PlayerSpaceship objects, which inherit all STBO and SpaceShip functions.
Objects of this class can't be created by scripts, but its child classes can.
Subclass of:
ShipTemplateBasedObject- boolean SpaceShip:isFriendOrFoeIdentified()
- [DEPRECATED]
Use SpaceShip:isFriendOrFoeIdentifiedBy() or SpaceShip:isFriendOrFoeIdentifiedByFaction(). - boolean SpaceShip:isFullyScanned()
- [DEPRECATED]
Use SpaceShip:isFullyScannedBy() or SpaceShip:isFullyScannedByFaction(). - boolean SpaceShip:isFriendOrFoeIdentifiedBy(SpaceObject other)
- Returns whether this SpaceShip has been identified by the given ship as either hostile or friendly.
- boolean SpaceShip:isFullyScannedBy(SpaceObject other)
- Returns whether this SpaceShip has been fully scanned by the given ship.
- boolean SpaceShip:isFriendOrFoeIdentifiedByFaction(number faction_id)
- Returns whether this SpaceShip has been identified by the given faction as either hostile or friendly.
- boolean SpaceShip:isFullyScannedByFaction(number faction_id)
- Returns whether this SpaceShip has been fully scanned by the given faction.
- boolean SpaceShip:isDocked(SpaceObject target)
- Returns whether this SpaceShip is docked with a station or another ship.
- SpaceObject SpaceShip:getDockedWith()
- Returns the object with which this SpaceShip is docked.
- boolean SpaceShip:isFriendOrFoeIdentifiedBy(SpaceObject other)
- Returns whether this SpaceShip has been identified by the given SpaceObject as either hostile or friendly.
Example: ship:isFriendOrFoeIdentifiedBy(enemy) - boolean SpaceShip:isFullyScannedBy(SpaceObject other)
- Returns whether this SpaceShip has been fully scanned by the given SpaceObject.
See also SpaceObject:isScannedBy().
Example: ship:isFullyScannedBy(enemy) - boolean SpaceShip:isFriendOrFoeIdentifiedByFaction(number faction_id)
- Returns whether this SpaceShip has been identified by the given faction as either hostile or friendly.
Example: ship:isFriendOrFoeIdentifiedByFaction("Kraylor") - boolean SpaceShip:isFullyScannedByFaction(number faction_id)
- Returns whether this SpaceShip has been fully scanned by the given faction.
See also SpaceObject:isScannedByFaction().
Example: ship:isFullyScannedByFaction("Kraylor") - boolean SpaceShip:isDocked(SpaceObject target)
- Returns whether this SpaceShip is docked with the given SpaceObject.
Example: ship:isDocked(base) -- returns true if `ship` is fully docked with `base` - SpaceObject SpaceShip:getDockedWith()
- Returns the SoaceObject with which this SpaceShip is docked.
Example: base = ship:getDockedWith() - EDockingState SpaceShip:getDockingState()
- Returns the EDockingState value of this SpaceShip.
0 = Not docked
1 = Docking in progress
2 = Docked
Example: ds = ship:getDockingState() - SpaceObject SpaceShip:getTarget()
- Returns this SpaceShip's weapons target.
For a CpuShip, this can differ from its orders target.
Example: target = ship:getTarget() - number SpaceShip:getWeaponStorage(EMissileWeapons weapon)
- Returns the number of the given weapon type stocked by this SpaceShip.
Example: homing = ship:getWeaponStorage("Homing") - number SpaceShip:getWeaponStorageMax(EMissileWeapons weapon)
- Returns this SpaceShip's capacity for the given weapon type.
Example: homing_max = ship:getWeaponStorageMax("Homing") - SpaceShip SpaceShip:setWeaponStorage(EMissileWeapons weapon, number amount)
- Sets the number of the given weapon type stocked by this SpaceShip.
Example: ship:setWeaponStorage("Homing", 2) -- this ship has 2 Homing missiles
Returns the object it was called on. - SpaceShip SpaceShip:setWeaponStorageMax(EMissileWeapons weapon, number amount)
- Sets this SpaceShip's capacity for the given weapon type.
If this ship has more stock of that weapon type than the new capacity, its stock is reduced.
However, if this ship's capacity for a weapon type is increased, its stocks are not.
Use SpaceShip:setWeaponStorage() to update the stocks.
Example: ship:setWeaponStorageMax("Homing", 4) -- this ship can carry 4 Homing missiles
Returns the object it was called on. - number SpaceShip:getShieldsFrequency()
- Returns this SpaceShip's shield frequency index.
To convert the index to the value used by players, multiply it by 20, then add 400.
Example:
frequency = ship:getShieldsFrequency() -- frequency index is 10
-- Outputs "Ship's shield frequency is 600THz"
print("Ship's shield frequency is " .. (frequency * 20) + 400 .. "THz") - SpaceShip SpaceShip:setShieldsFrequency(number freq)
- Sets this SpaceShip's shield frequency index.
To convert the index to the value used by players, multiply it by 20, then add 400.
Valid values are 0 (400THz) to 20 (800THz). Defaults to a random value.
Unlike PlayerSpaceship:commandSetShieldFrequency(), this instantly changes the frequency with no calibration delay.
Example: frequency = ship:setShieldsFrequency(10) -- frequency is 600THz
Returns the object it was called on. - number SpaceShip:getBeamFrequency()
- Returns this SpaceShip's beam weapon frequency.
To convert the index to the value used by players, multiply it by 20, then add 400.
Example:
frequency = ship:getBeamFrequency() -- frequency index is 10
-- Outputs "Ship's beam frequency is 600THz"
print("Ship's beam frequency is " .. (frequency * 20) + 400 .. "THz") - number SpaceShip:getMaxEnergy()
- Returns this SpaceShip's energy capacity.
Example: ship:getMaxEnergy() - SpaceShip SpaceShip:setMaxEnergy(number amount)
- Sets this SpaceShip's energy capacity.
CpuShips don't consume energy. Setting this value has no effect on their behavior or functionality.
For PlayerSpaceships, see PlayerSpaceship:setEnergyLevelMax().
Example: ship:setMaxEnergy(800)
Returns the object it was called on. - number SpaceShip:getEnergy()
- Returns this SpaceShip's energy level.
Example: ship:getEnergy() - SpaceShip SpaceShip:setEnergy(number amount)
- Sets this SpaceShip's energy level.
Valid values are any greater than 0 and less than the energy capacity (getMaxEnergy()).
Invalid values are ignored.
CpuShips don't consume energy. Setting this value has no effect on their behavior or functionality.
For PlayerSpaceships, see PlayerSpaceship:setEnergyLevel().
Example: ship:setEnergy(1000) -- sets the ship's energy to 1000 if its capacity is 1000 or more
Returns the object it was called on. - boolean SpaceShip:hasSystem(ESystem system)
- Returns whether this SpaceShip has the given system.
Example: ship:hasSystem("impulse") -- returns true if the ship has impulse drive - number SpaceShip:getSystemHackedLevel(ESystem system)
- Returns the hacked level for the given system on this SpaceShip.
Returns a value between 0.0 (unhacked) and 1.0 (fully hacked).
Example: ship:getSystemHackedLevel("impulse") - SpaceShip SpaceShip:setSystemHackedLevel(ESystem system, number hacked_level)
- Sets the hacked level for the given system on this SpaceShip.
Valid range is 0.0 (unhacked) to 1.0 (fully hacked).
Example: ship:setSystemHackedLevel("impulse",0.5) -- sets the ship's impulse drive to half hacked
Returns the object it was called on. - number SpaceShip:getSystemHealth(ESystem system)
- Returns the given system's health on this SpaceShip.
System health is related to damage, and is separate from its hacked level.
Returns a value between 0.0 (fully disabled) and 1.0 (undamaged).
Example: ship:getSystemHealth("impulse") - SpaceShip SpaceShip:setSystemHealth(ESystem system, number health)
- Sets the given system's health on this SpaceShip.
System health is related to damage, and is separate from its hacked level.
Valid range is 0.0 (fully disabled) and 1.0 (undamaged).
Example: ship:setSystemHealth("impulse",0.5) -- sets the ship's impulse drive to half damaged
Returns the object it was called on. - number SpaceShip:getSystemHealthMax(ESystem system)
- Returns the given system's maximum health on this SpaceShip.
Returns a value between 0.0 (fully disabled) and 1.0 (undamaged).
Example: ship:getSystemHealthMax("impulse") - SpaceShip SpaceShip:setSystemHealthMax(ESystem system, number health_max)
- Sets the given system's maximum health on this SpaceShip.
Valid range is 0.0 (fully disabled) and 1.0 (undamaged).
Example: ship:setSystemHealthMax("impulse", 0.5) -- limits the ship's impulse drive health to half
Returns the object it was called on. - number SpaceShip:getSystemHeat(ESystem system)
- Returns the given system's heat level on this SpaceShip.
Returns a value between 0.0 (no heat) and 1.0 (overheating).
Example: ship:getSystemHeat("impulse") - SpaceShip SpaceShip:setSystemHeat(ESystem system, number heat)
- Sets the given system's heat level on this SpaceShip.
CpuShips don't generate or manage heat. Setting this has no effect on them.
Valid range is 0.0 (fully disabled) to 1.0 (undamaged).
Example: ship:setSystemHeat("impulse", 0.5) -- sets the ship's impulse drive heat to half of capacity
Returns the object it was called on. - number SpaceShip:getSystemHeatRate(ESystem system)
- Returns the given system's rate of heating or cooling, in percent (0.01 = 1%) per second?, on this SpaceShip.
Example: ship:getSystemHeatRate("impulse") - SpaceShip SpaceShip:setSystemHeatRate(ESystem system, number rate)
- Sets the given system's rate of heating or cooling, in percent (0.01 = 1%) per second?, on this SpaceShip.
CpuShips don't generate or manage heat. Setting this has no effect on them.
Example: ship:setSystemHeatRate("impulse", 0.05)
Returns the object it was called on. - number SpaceShip:getSystemPower(ESystem system)
- Returns the given system's power level on this SpaceShip.
Returns a value between 0.0 (unpowered) and 1.0 (fully powered).
Example: ship:getSystemPower("impulse") - SpaceShip SpaceShip:setSystemPower(ESystem system, number power)
- Sets the given system's power level.
Valid range is 0.0 (unpowered) to 1.0 (fully powered).
Example: ship:setSystemPower("impulse", 0.5) -- sets the ship's impulse drive to half power
Returns the object it was called on. - number SpaceShip:getSystemPowerRate(ESystem system)
- Returns the given system's rate of consuming power, in points per second?, in this SpaceShip.
Example: ship:getSystemPowerRate("impulse") - SpaceShip SpaceShip:setSystemPowerRate(ESystem system, number rate)
- Sets the given system's rate of consuming power, in points per second?, in this SpaceShip.
CpuShips don't consume energy. Setting this has no effect.
Example: ship:setSystemPowerRate("impulse", 0.4)
Returns the object it was called on. - number SpaceShip:getSystemPowerFactor(ESystem system)
- Returns the relative power drain factor for the given system.
Example: ship:getSystemPowerFactor("impulse") - SpaceShip SpaceShip:setSystemPowerFactor(ESystem system, number factor)
- Sets the relative power drain factor? for the given system in this SpaceShip.
"reactor" has a negative value because it generates power rather than draining it.
CpuShips don't consume energy. Setting this has no effect.
Example: ship:setSystemPowerFactor("impulse", 4)
Returns the object it was called on. - number SpaceShip:getSystemCoolant(ESystem system)
- Returns the coolant distribution for the given system in this SpaceShip.
Returns a value between 0.0 (none) and 1.0 (capacity).
Example: ship:getSystemCoolant("impulse") - SpaceShip SpaceShip:setSystemCoolant(ESystem system, number coolant)
- Sets the coolant quantity for the given system in this SpaceShip.
CpuShips don't generate or manage heat. Setting this has no effect on them.
Valid range is 0.0 (none) to 1.0 (capacity).
Example: ship:setSystemPowerFactor("impulse", 4)
Returns the object it was called on. - number SpaceShip:getSystemCoolantRate(ESystem system)
- Returns the rate at which the given system in this SpaceShip takes coolant, in points per second?
Example: ship:getSystemCoolantRate("impulse") - SpaceShip SpaceShip:setSystemCoolantRate(ESystem system, number rate)
- Sets the rate at which the given system in this SpaceShip takes coolant, in points per second?
CpuShips don't generate or manage heat. Setting this has no effect on them.
Example: ship:setSystemCoolantRate("impulse", 1.2)
Returns the object it was called on. - Speeds SpaceShip:getImpulseMaxSpeed()
- Returns this SpaceShip's forward and reverse impulse speed limits.
Examples:
forward,reverse = getImpulseMaxSpeed()
forward = getImpulseMaxSpeed() -- forward speed only - SpaceShip SpaceShip:setImpulseMaxSpeed(number forward_speed, number reverse_speed=nil)
- Sets this SpaceShip's maximum forward and reverse impulse speeds.
The reverse maximum speed value is optional.
Calling this with a single argument sets both forward and reverse maximum speeds to the same value.
Examples:
ship:setImpulseMaxSpeed(30,20) -- sets the max forward speed to 30 and reverse to 20
ship:setImpulseMaxSpeed(30) -- sets the max forward and reverse speed to 30
Returns the object it was called on. - number SpaceShip:getRotationMaxSpeed()
- Returns this SpaceShip's maximum rotational speed, in degrees per second?
Example: ship:getRotationMaxSpeed() - SpaceShip SpaceShip:setRotationMaxSpeed(number speed)
- Sets this SpaceShip's maximum rotational speed, in degrees per second?
Example: ship:setRotationMaxSpeed(10)
Returns the object it was called on. - Speeds SpaceShip:getAcceleration()
- Returns the SpaceShip's forward and reverse impulse acceleration values, in (unit?)
Examples:
forward,reverse = getAcceleration()
forward = getAcceleration() -- forward acceleration only - SpaceShip SpaceShip:setAcceleration(number acceleration, number reverse_acceleration=nil)
- Sets the SpaceShip's forward and reverse impulse acceleration values, in (unit?)
The reverse acceleration value is optional.
Calling with a single argument sets both forward and reverse acceleration to the same value.
Examples:
ship:setAcceleration(5,3.5) -- sets the max forward acceleration to 5 and reverse to 3.5
ship:setAcceleration(5) -- sets the max forward and reverse acceleration to 5
Returns the object it was called on. - SpaceShip SpaceShip:setCombatManeuver(number boost, number strafe)
- Sets the SpaceShip's combat maneuvering capacities.
The boost value sets the forward maneuver capacity, and the strafe value sets the lateral maneuver capacity.
Example: ship:setCombatManeuver(400,250) -- sets boost capacity to 400 and lateral to 250
Returns the object it was called on. - boolean SpaceShip:hasJumpDrive()
- Returns whether the SpaceShip has a jump drive.
Example: ship:hasJumpDrive() - SpaceShip SpaceShip:setJumpDrive(boolean has_jump)
- Defines whether the SpaceShip has a jump drive.
If true, this ship gains jump drive controls and a "jumpdrive" ship system.
Example: ship:setJumpDrive(true) -- gives this ship a jump drive
Returns the object it was called on. - SpaceShip SpaceShip:setJumpDriveRange(number min, number max)
- Sets the minimum and maximum jump distances for this SpaceShip.
Defaults to (5000,50000) if not set by the ShipTemplate.
Example: ship:setJumpDriveRange(2500,25000) -- sets the minimum jump distance to 2.5U and maximum to 25U
Returns the object it was called on. - SpaceShip SpaceShip:setJumpDriveCharge(number charge)
- Sets this SpaceShip's current jump drive charge.
Jumping depletes the ship's jump drive charge by a value equal to the distance jumped.
For example, a 5U jump depletes the charge by 5000.
A SpaceShip with a jump drive can jump only when this value is equal to or greater than the ship's maximum jump range.
Any numeric value is valid, including negative values (longer to recharge) and values larger than the ship's maximum jump range (can jump again with a shorter, or no, recharge required).
Jump drive charge regenerates at a rate modified by the "jumpdrive" system's effectiveness.
Example: ship:setJumpDriveCharge(50000)
Returns the object it was called on. - number SpaceShip:getJumpDriveCharge()
- Returns this SpaceShip's current jump drive charge.
Example: jump_charge = ship:getJumpDriveCharge() - number SpaceShip:getJumpDelay()
- Returns the time required by this SpaceShip to complete a jump once initiated.
A ship can't perform certain actions, such as docking, while its jump delay is not 0.
Returns a value between 0.0 (no delay, ready to jump) to 10.0.
With normal "jumpdrive" system effectiveness, this delay is 10 seconds.
System effectiveness can modify this delay.
Example: ship:getJumpDelay() - boolean SpaceShip:hasWarpDrive()
- Returns whether this SpaceShip has a warp drive.
Example: ship:hasWarpDrive() - SpaceShip SpaceShip:setWarpDrive(boolean has_warp)
- Defines whether this SpaceShip has a warp drive.
If true, this ship gains warp drive controls and a "warp" ship system.
Example: ship:setWarpDrive(true)
Returns the object it was called on. - SpaceShip SpaceShip:setWarpSpeed(number speed)
- Sets this SpaceShip's warp speed factor.
Valid values are any greater than 0. Ships don't tend to go faster than 24000 (1400U/min) due to engine limitations.
Unlike ShipTemplate:setWarpSpeed(), setting this value does NOT also grant this ship a warp drive.
Example: ship:setWarpSpeed(1000);
Returns the object it was called on. - number SpaceShip:getWarpSpeed()
- Returns this SpaceShip's warp speed factor.
Actual warp speed can be modified by "warp" system effectiveness.
Example: ship:getWarpSpeed(); - number SpaceShip:getBeamWeaponArc(number index)
- Returns the arc, in degrees, for the BeamWeapon with the given index on this SpaceShip.
Example: ship:getBeamWeaponArc(0); -- returns beam weapon 0's arc - number SpaceShip:getBeamWeaponDirection(number index)
- Returns the direction, in degrees relative to the ship's forward bearing, for the arc's center of the BeamWeapon with the given index on this SpaceShip.
Example: ship:getBeamWeaponDirection(0); -- returns beam weapon 0's direction - number SpaceShip:getBeamWeaponRange(number index)
- Returns the range for the BeamWeapon with the given index on this SpaceShip.
Example: ship:getBeamWeaponRange(0); -- returns beam weapon 0's range - number SpaceShip:getBeamWeaponTurretArc(number index)
- Returns the turret arc, in degrees, for the BeamWeapon with the given index on this SpaceShip.
Example: ship:getBeamWeaponTurretArc(0); -- returns beam weapon 0's turret arc - number SpaceShip:getBeamWeaponTurretDirection(number index)
- Returns the direction, in degrees relative to the ship's forward bearing, for the turret arc's center for the BeamWeapon with the given index on this SpaceShip.
Example: ship:getBeamWeaponTurretDirection(0); -- returns beam weapon 0's turret direction - number SpaceShip:getBeamWeaponTurretRotationRate(number index)
- number SpaceShip:getBeamWeaponCycleTime(number index)
- Returns the base firing delay, in seconds, for the BeamWeapon with the given index on this SpaceShip.
Actual cycle time can be modified by "beamweapon" system effectiveness.
Example: ship:getBeamWeaponCycleTime(0); -- returns beam weapon 0's cycle time - number SpaceShip:getBeamWeaponDamage(number index)
- Returns the base damage dealt by the BeamWeapon with the given index on this SpaceShip.
Actual damage can be modified by "beamweapon" system effectiveness.
Example: ship:getBeamWeaponDamage(0); -- returns beam weapon 0's damage - number SpaceShip:getBeamWeaponEnergyPerFire(number index)
- Returns how much of this SpaceShip's energy is drained each time the BeamWeapon with the given index is fired.
Actual drain can be modified by "beamweapon" system effectiveness.
Example: ship:getBeamWeaponEnergyPerFire(0); -- returns beam weapon 0's energy use per firing - number SpaceShip:getBeamWeaponHeatPerFire(number index)
- Returns the heat generated by each firing of the BeamWeapon with the given index on this SpaceShip.
Actual heat generation can be modified by "beamweapon" system effectiveness.
Example: ship:getBeamWeaponHeatPerFire(0); -- returns beam weapon 0's heat generation per firing - SpaceShip SpaceShip:setBeamWeapon(number index, number arc, number direction, number range, number cycle_time, number damage)
- Defines the traits of a BeamWeapon with the given index on this SpaceShip.
- index: Each beam weapon on this SpaceShip must have a unique index.
- arc: Sets the arc of its firing capability, in degrees.
- direction: Sets the default center angle of the arc, in degrees relative to the ship's forward bearing. Accepts 0, negative, and positive values.
- range: Sets how far away the beam can fire.
- cycle_time: Sets the base firing delay, in seconds. System effectiveness modifies the cycle time.
- damage: Sets the base damage done by the beam to the target. System effectiveness modifies the damage.
To create a turreted beam, also add SpaceShip:setBeamWeaponTurret(), and set the beam weapon's arc to be smaller than the turret's arc.
Example:
-- Creates a beam weapon with index 0, arc of 90 degrees, direction pointing backward, range of 1U, base cycle time of 1 second, and base damage of 1 point
ship:setBeamWeapon(0,90,180,1000,1,1)
Returns the object it was called on. - SpaceShip SpaceShip:setBeamWeaponTurret(number index, number arc, number direction, number rotation_rate)
- Converts a BeamWeapon with the given index on this SpaceShip into a turret and defines its traits.
A turreted beam weapon rotates within its turret arc toward the weapons target at the given rotation rate.
- index: Must match the index of an existing beam weapon on this SpaceShip.
- arc: Sets the turret's maximum targeting angles, in degrees. The turret arc must be larger than the associated beam weapon's arc.
- direction: Sets the default center angle of the turret arc, in degrees relative to the ship's forward bearing. Accepts 0, negative, and positive values.
- rotation_rate: Sets how many degrees per tick (unit?) that the associated beam weapon's direction can rotate toward the target within the turret arc. System effectiveness modifies the turret's rotation rate.
To create a turreted beam, also add SpaceShip:setBeamWeapon(), and set the beam weapon's arc to be smaller than the turret's arc.
Example:
-- Makes beam weapon 0 a turret with a 200-degree turret arc centered on 90 degrees from forward, rotating at 5 degrees per tick (unit?)
ship:setBeamWeaponTurret(0,200,90,5)
Returns the object it was called on. - SpaceShip SpaceShip:setBeamWeaponTexture(number index, string texture)
- Sets the BeamEffect texture, by filename, for the BeamWeapon with the given index on this SpaceShip.
See BeamEffect:setTexture().
Example: ship:setBeamWeaponTexture(0,"texture/beam_blue.png")
Returns the object it was called on. - SpaceShip SpaceShip:setBeamWeaponEnergyPerFire(number index, number energy)
- Sets how much energy is drained each time the BeamWeapon with the given index is fired on this SpaceShip.
Only PlayerSpaceships consume energy. Setting this for other ShipTemplateBasedObject types has no effect.
Example: ship:setBeamWeaponEnergyPerFire(0,1) -- sets beam 0 to use 1 energy per firing
Returns the object it was called on. - SpaceShip SpaceShip:setBeamWeaponHeatPerFire(number index, number heat)
- Sets how much "beamweapon" system heat is generated, in percentage of total system heat capacity, each time the BeamWeapon with the given index is fired on this SpaceShip.
Only PlayerSpaceships generate and manage heat. Setting this for other ShipTemplateBasedObject types has no effect.
Example: ship:setBeamWeaponHeatPerFire(0,0.02) -- sets beam 0 to generate 0.02 (2%) system heat per firing
Returns the object it was called on. - SpaceShip SpaceShip:setBeamWeaponArcColor(number index, number r, number g, number b, number fire_r, number fire_g, number fire_b)
- Sets the colors used to draw the radar arc for the BeamWeapon with the given index on this SpaceShip.
The first three-number value sets the RGB color for the arc when idle, and the second sets the color when firing.
Example: ship:setBeamWeaponArcColor(0,0,128,0,0,255,0) -- makes beam 0's arc green
Returns the object it was called on. - SpaceShip SpaceShip:setBeamWeaponDamageType(number index, EDamageType type)
- Sets the damage type dealt by the BeamWeapon with the given index on this SpaceShip.
Example: ship:setBeamWeaponDamageType(0,"emp") -- makes beam 0 deal EMP damage
Returns the object it was called on. - SpaceShip SpaceShip:setWeaponTubeCount(number amount)
- Sets the number of WeaponTubes for this SpaceShip.
Weapon tubes are 0-indexed. For example, 3 tubes would be indexed 0, 1, and 2.
Ships are limited to a maximum of 16 weapon tubes.
Example: ship:setWeaponTubeCount(4)
Returns the object it was called on. - number SpaceShip:getWeaponTubeCount()
- Returns the number of WeaponTube on this SpaceShip.
Example: ship:getWeaponTubeCount() - EMissileWeapons SpaceShip:getWeaponTubeLoadType(number index)
- Returns the weapon type loaded into the WeaponTube with the given index on this SpaceShip.
Returns no value if no weapon is loaded, which includes the tube being in a loading or unloading state.
Example: ship:getWeaponTubeLoadType(0) - SpaceShip SpaceShip:weaponTubeAllowMissle(number index, EMissileWeapons type)
- Sets which weapon types the WeaponTube with the given index on this SpaceShip can load.
Note the spelling of "missle".
Example: ship:weaponTubeAllowMissle(0,"Homing") -- allows Homing missiles to be loaded in WeaponTube 0
Returns the object it was called on. - SpaceShip SpaceShip:weaponTubeDisallowMissle(number index, EMissileWeapons type)
- Sets which weapon types the WeaponTube with the given index can't load on this SpaceShip.
Note the spelling of "missle".
Example: ship:weaponTubeDisallowMissle(0,"Homing") -- prevents Homing missiles from being loaded in tube 0
Returns the object it was called on. - SpaceShip SpaceShip:setWeaponTubeExclusiveFor(number index, EMissileWeapons type)
- Sets a weapon tube with the given index on this SpaceShip to allow loading only the given weapon type.
Example: ship:setWeaponTubeExclusiveFor(0,"Homing") -- allows only Homing missiles to be loaded in tube 0
Returns the object it was called on. - SpaceShip SpaceShip:setWeaponTubeDirection(number index, number direction)
- Sets the angle, relative to this SpaceShip's forward bearing, toward which the WeaponTube with the given index on this SpaceShip points.
Accepts 0, negative, and positive values.
Example:
-- Sets tube 0 to point 90 degrees right of forward, and tube 1 to point 90 degrees left of forward
ship:setWeaponTubeDirection(0,90):setWeaponTubeDirection(1,-90)
Returns the object it was called on. - SpaceShip SpaceShip:setTubeSize(number index, EMissileSizes size)
- Sets the weapon size launched from the WeaponTube with the given index on this SpaceShip.
Example: ship:setTubeSize(0,"large") -- sets tube 0 to fire large weapons
Returns the object it was called on. - EMissileSizes SpaceShip:getTubeSize(number index)
- Returns the size of the weapon tube with the given index on this SpaceShip.
Example: ship:getTubeSize(0) - number SpaceShip:getTubeLoadTime(number index)
- Returns the delay, in seconds, for loading and unloading the WeaponTube with the given index on this SpaceShip.
Example: ship:getTubeLoadTime(0) - SpaceShip SpaceShip:setTubeLoadTime(number index, number time)
- Sets the time, in seconds, required to load the weapon tube with the given index on this SpaceShip.
Example: ship:setTubeLoadTime(0,12) -- sets the loading time for tube 0 to 12 seconds
Returns the object it was called on. - SpaceShip SpaceShip:setRadarTrace(string trace)
- Sets the radar trace image for this SpaceShip.
Valid values are filenames to PNG images relative to the resources/radar/ directory.
Radar trace images should be white with a transparent background.
Only scanned SpaceShips use a specific radar trace image. Unscanned SpaceShips always display as an arrow.
Example: ship:setRadarTrace("blip.png") -- displays a dot for this ship on radar when scanned
Returns the object it was called on. - number SpaceShip:getDynamicRadarSignatureGravity()
- Returns the dynamic gravitational radar signature value emitted by this SpaceShip.
Ship functions can dynamically modify this SpaceShip's radar signature values.
Example: ship:getDynamicRadarSignatureGravity() - number SpaceShip:getDynamicRadarSignatureElectrical()
- Returns the dynamic electrical radar signature value emitted by this SpaceShip.
Ship functions can dynamically modify this SpaceShip's radar signature values.
Example: ship:getDynamicRadarSignatureElectrical() - number SpaceShip:getDynamicRadarSignatureBiological()
- Returns the dynamic biological radar signature value emitted by this SpaceShip.
Ship functions can dynamically modify this SpaceShip's radar signature values.
Example: ship:getDynamicRadarSignatureBiological() - SpaceShip SpaceShip:addBroadcast(number threshold, string message)
- Broadcasts a message from this SpaceShip to the comms of all other SpaceShips matching the threshold.
The threshold value can be an integer equivalent of EFactionVsFactionState:
0: Broadcast to all friendly SpaceShips
1: Broadcast to all friendly and neutral SpaceShips
2: Broadcast to all SpaceShips, including enemies
Providing an invalid threshold value defaults to broadcasting only to friendly SpaceShips.
Examples:
ship:addBroadcast(1, "Help!")
ship:addBroadcast(2, "We're taking over!")
Returns the object it was called on. - SpaceShip SpaceShip:setScanState(EScannedState scanned)
- Sets the scan state of this SpaceShip for every faction.
Example: ship:setScanState("fullscan") -- every faction treats this ship as fully scanned
Returns the object it was called on. - SpaceShip SpaceShip:setScanStateByFaction(string faction_name, EScannedState scanned)
- Sets the scan state of this SpaceShip for a given faction.
Example: ship:setScanStateByFaction("Kraylor","fullscan") -- Kraylor faction treats this ship as fully scanned
Returns the object it was called on.
CpuShip
A CpuShip is an AI-controlled SpaceShip.
The AI can be assigned an order (be idle, roam freely, defend location, etc.) and a combat behavior state (attack at close or long range, be evasive).
AI behaviors are defined in ai.cpp and other files in src/ai/.
CpuShip:order... functions also broadcast their orders over friendly comms.
Autonomous combat AI orders use the CpuShip's short- and long-range radar ranges to acquire targets, which can be affected by nebulae.
They also rank prospective targets by their type, distance, and capabilities.
Example:
-- Place a Fighter-class Human Navy CpuShip, order it to roam, and if it engages in combat it will fight evasively
ship = CpuShip():setTemplate("Fighter"):setPosition(10000,3000):setFaction("Human Navy"):orderRoaming():setAI("evasive"):setScanned(true)
Subclass of:
SpaceShip- CpuShip CpuShip:setAI(string new_ai)
- Sets the default combat AI state for this CpuShip.
Combat AI states determine the AI's combat tactics and responses.
They're distinct from orders, which determine the ship's active objectives and are defined by CpuShip:order...() functions.
Combat AI state can be set per CpuShip, defined in the ShipTemplate, or left to "default".
Valid combat AI states are:
- "default" directly pursues enemies at beam range while making opportunistic missile attacks
- "evasion" maintains distance from enemy weapons and evades attacks
- "fighter" prefers strafing maneuvers and attacks briefly at close range while passing
- "missilevolley" prefers lining up missile attacks from long range
Example: ship:setAI("fighter")
Returns the object it was called on. - CpuShip CpuShip:orderIdle()
- Orders this CpuShip to stay at its current position and do nothing.
Idle CpuShips don't target or attack nearby enemies.
Example: ship:orderIdle()
Returns the object it was called on. - CpuShip CpuShip:orderRoaming()
- Orders this CpuShip to roam and engage at will, without a specific target.
A Roaming ship can acquire hostile targets within its long-range radar range, and prefers the best hostile target within 2U of its short-range radar range.
If this ship has weapon tubes but lacks beam weapons and is out of weapons stock, it attempts to Retreat to a weapons restock target within long-range radar range.
Example: ship:orderRoaming()
Returns the object it was called on. - CpuShip CpuShip:orderRoamingAt(number position_x, number position_y)
- Returns the object it was called on.
- CpuShip CpuShip:orderRetreat(SpaceObject object)
- Orders this CpuShip to move toward the given SpaceObject and dock, restock weapons, and repair its hull.
If the SpaceObject is a dockable ShipTemplateBasedObject, this ship moves directly toward it and docks with it as soon as possible.
If not, this ship moves toward the best weapons restocking target within relay range (double its long-range radar range).
If this ship still can't find a restocking target, or it is fully repaired and re-stocked, this ship reverts to Roaming orders.
Example: ship:orderRetreat(base) -- retreat to the SpaceObject `base`
Returns the object it was called on. - CpuShip CpuShip:orderStandGround()
- Orders this CpuShip to stay at its current position and attack nearby hostiles.
This ship will rotate to face a target and fires missiles within 4.5U if it has any, but won't move, roam, or patrol.
Example: ship:orderStandGround()
Returns the object it was called on. - CpuShip CpuShip:orderDefendLocation(number position_x, number position_y)
- Orders this CpuShip to move to the given coordinates, patrol within a 1.5U radius, and attack any hostiles that move within 2U of its short-range radar range.
If a targeted hostile moves more than 3U out of this ship's short-range radar range, this ship drops the target and resumes defending its position.
Example: ship:orderDefendLocation(500, 1000) -- defend the space near these coordinates
Returns the object it was called on. - CpuShip CpuShip:orderDefendTarget(SpaceObject object)
- Orders this CpuShip to maintain a 2U escort distance from the given SpaceObject and attack nearby hostiles.
If a targeted hostile moves more than 3U out of this ship's short-range radar range, this ship drops the target and resumes escorting.
If the SpaceObject being defended is destroyed, this ship reverts to Roaming orders.
Example: ship:orderDefendTarget(base) -- defend the space near the SpaceObject `base`
Returns the object it was called on. - CpuShip CpuShip:orderFlyFormation(SpaceObject object, number offset_x, number offset_y)
- Orders this CpuShip to fly toward the given SpaceObject and follow it from the given offset distance.
This ship also targets anything its given SpaceObject targets.
If the SpaceObject being followed is destroyed, this ship reverts to Roaming orders.
Give multiple CpuShips the same SpaceObject and different offsets to create a formation.
Example: ship:orderFlyFormation(leader, 500, 250) -- fly 0.5U off the wing and 0.25U off the tail of the SpaceObject `leader`
Returns the object it was called on. - CpuShip CpuShip:orderFlyTowards(number target_x, number target_y)
- Orders this CpuShip to move toward the given coordinates, and to attack hostiles that approach within its short-range radar range during transit.
This ship uses any warp or jump drive capabilities to arrive near its destination.
This ship disengages from combat and continues toward its destination if its target moves more than 3U out of its short-range radar range.
Upon arrival, this ship reverts to the Defend Location orders with its destination as the target.
Example: ship:orderFlyTowards(500, 1000) -- move to these coordinates, attacking nearby hostiles on the way
Returns the object it was called on. - CpuShip CpuShip:orderFlyTowardsBlind(number target_x, number target_y)
- Orders this CpuShip to move toward the given coordinates, ignoring all hostiles on the way.
Upon arrival, this ship reverts to the Idle orders.
Example: ship:orderFlyTowardsBlind(500, 1000) -- move to these coordinates, ignoring hostiles
Returns the object it was called on. - CpuShip CpuShip:orderAttack(SpaceObject object)
- Orders this CpuShip to attack the given SpaceObject.
Example: ship:orderAttack(player)
Returns the object it was called on. - CpuShip CpuShip:orderDock(SpaceObject object)
- Orders this CpuShip to Fly Toward and dock with the given SpaceObject, if possible.
If its target doesn't exist, revert to Roaming orders.
Example: ship:orderDock(spaceStation)
Returns the object it was called on. - EAIOrder CpuShip:getOrder()
- Returns this CpuShip's current orders.
Example: ship_orders = ship:getOrder() - number x, number y CpuShip:getOrderTargetLocation()
- Returns the coordinates for this CpuShip's orders.
If the orders target a SpaceObject instead of coordinates, use CpuShip:getOrderTarget().
Some orders, such as Roaming, have no target.
Returns the order's x,y coordinates, or 0,0 if not defined.
Example: x,y = ship:getOrderTargetLocation() - SpaceObject CpuShip:getOrderTarget()
- Returns the target SpaceObject for this CpuShip's orders.
If the orders target coordinates instead of an object, use CpuShip:getOrderTargetLocation().
Some orders, such as Roaming, have no target.
Example: target = ship:getOrderTarget()
PlayerSpaceship
A PlayerSpaceship is a SpaceShip controlled by a player crew.
If a function name begins with "command", the function is equivalent to the crew taking a corresponding action.
Such commands can be limited by the ship's capabilities, including systems damage, lack of power, or insufficient weapons stocks.
Subclass of:
SpaceShip- number x, number y PlayerSpaceship:getWaypoint(number index)
- Returns the coordinates of a waypoint with the given index that's been set by this PlayerSpaceship.
Waypoints are 1-indexed.
Example: x,y = player:getWaypoint(1) - number PlayerSpaceship:getWaypointCount()
- Returns the total number of active waypoints owned by this PlayerSpaceship.
Example: player:getWaypointCount() - EAlertLevel PlayerSpaceship:getAlertLevel()
- Returns this PlayerSpaceship's EAlertLevel.
Returns "Normal", "YELLOW ALERT", "RED ALERT", which differ from the valid values for PlayerSpaceship:commandSetAlertLevel().
Example: player:getAlertLevel() - PlayerSpaceship PlayerSpaceship:setShieldsActive(boolean active)
- Defines whether this PlayerSpaceship's shields are raised (true) or lowered (false).
Compare to CpuShips, whose shields are always active.
Example: player:setShieldsActive(true)
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:addToShipLog(string message, Color color)
- Adds a message to this PlayerSpaceship's log.
Takes a string as the message and a color applied to the logged message.
Example: player:addToShipLog("Acknowledged","yellow") -- adds "Acknowledged" in yellow to the `player` ship's log
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:transferPlayersToShip(PlayerSpaceship other_ship)
- Moves all players connected to this ship to the same crew positions on another PlayerSpaceship.
If the target isn't a PlayerSpaceship, this function has no effect.
Use this in scenarios to change the crew's ship.
Example: player:transferPlayersToShip(player2) -- transfer all player crew to `player2`
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:transferPlayersAtPositionToShip(ECrewPosition position, PlayerSpaceship other_ship)
- Transfers only the crew members on a specific crew position to another PlayerSpaceship.
If a player is in multiple positions, this matches any of their positions and moves that player to all of the same positions on the destination ship.
Example: player:transferPlayersAtPositionToShip("helms",player2) -- transfer all crew on Helms to `player2`
Returns the object it was called on. - boolean PlayerSpaceship:hasPlayerAtPosition(ECrewPosition position)
- Returns whether a player occupies the given crew position on this PlayerSpaceship.
Example: player:hasPlayerAtPosition("helms") - boolean PlayerSpaceship:isCommsInactive()
- Returns whether this PlayerSpaceship's comms are not in use.
Use this to determine whether the player can accept an incoming hail or chat.
Example: player:isCommsInactive() - boolean PlayerSpaceship:isCommsOpening()
- Returns whether this PlayerSpaceship is opening comms with another SpaceObject.
Example: player:isCommsOpening() - boolean PlayerSpaceship:isCommsBeingHailed()
- Returns whether this PlayerSpaceship is being hailed by another SpaceObject.
Example: player:isCommsBeingHailed() - boolean PlayerSpaceship:isCommsBeingHailedByGM()
- Returns whether this PlayerSpaceship is being hailed by the GM.
Example: player:isCommsBeingHailedByGM() - boolean PlayerSpaceship:isCommsFailed()
- Returns whether comms to this PlayerSpaceship have failed to open.
Example: player:isCommsFailed() - boolean PlayerSpaceship:isCommsBroken()
- Returns whether comms to this PlayerSpaceship were broken off by the other SpaceObject.
Example: player:isCommsBroken() - boolean PlayerSpaceship:isCommsClosed()
- Returns whether comms between this PlayerSpaceship and a SpaceObject were intentionally closed.
Example: player:isCommsClosed() - boolean PlayerSpaceship:isCommsChatOpen()
- Returns whether this PlayerSpaceship is engaged in text chat with either the GM or another PlayerSpaceship.
Example: player:isCommsChatOpen() - boolean PlayerSpaceship:isCommsChatOpenToGM()
- Returns whether this PlayerSpaceship is engaged in text chat with the GM.
Example: player:isCommsChatOpenToGM() - boolean PlayerSpaceship:isCommsChatOpenToPlayer()
- Returns whether this PlayerSpaceship is engaged in text chat with another PlayerSpaceship.
Example: player:isCommsChatOpenToPlayer() - boolean PlayerSpaceship:isCommsScriptOpen()
- Returns whether this PlayerSpaceship is engaged in comms with a scripted SpaceObject.
Example: player:isCommsScriptOpen() - PlayerSpaceship PlayerSpaceship:setEnergyLevel(number amount)
- Sets this PlayerSpaceship's energy level.
Values are limited from 0 to the energy level max. Negative or excess values are capped to the limits.
Example: player:setEnergyLevel(1000) -- sets the ship's energy to either 1000 or the max limit, whichever is lower
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:setEnergyLevelMax(number amount)
- Sets this PlayerSpaceship's energy capacity.
Valid values are 0 or any positive number.
If the new limit is lower than the ship's current energy level, this also reduces the energy level.
Example: player:setEnergyLevelMax(1000) -- sets the ship's energy limit to 1000
Returns the object it was called on. - number PlayerSpaceship:getEnergyLevel()
- Returns this PlayerSpaceship's energy level.
Example: player:getEnergyLevel() - number PlayerSpaceship:getEnergyLevelMax()
- Returns this PlayerSpaceship's energy capacity.
Example: player:getEnergyLevelMax() - number PlayerSpaceship:getEnergyShieldUsePerSecond()
- Returns how much energy is consumed per second by this PlayerSpaceship's shields while active.
Example: player:getEnergyShieldUsePerSecond() - PlayerSpaceship PlayerSpaceship:setEnergyShieldUsePerSecond(number rate)
- Sets how much energy is consumed per second by this PlayerSpaceship's shields while active.
Example: player:setEnergyShieldUsePerSecond(1.5)
Returns the object it was called on. - number PlayerSpaceship:getEnergyWarpPerSecond()
- Returns how much energy is consumed per second by this PlayerSpaceship's warp drive while in use.
Example: player:getEnergyWarpPerSecond() - PlayerSpaceship PlayerSpaceship:setEnergyWarpPerSecond(number rate)
- Sets how much energy is consumed per second by this PlayerSpaceship's warp drive while in use.
Example: player:setEnergyWarpPerSecond(1.7)
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:setMaxCoolant(number coolant)
- Sets the maximum amount of coolant available to engineering on this PlayerSpaceship.
Defaults to 10, which by default allows engineering to set 100% coolant on one system.
Valid values are 0 or any positive number.
If the new limit is less than the coolant already distributed, this automatically reduces distribution percentages.
Example: player:setMaxCoolant(5) -- halves the amount of available coolant
Returns the object it was called on. - number PlayerSpaceship:getMaxCoolant()
- Returns the maximum amount of coolant available to engineering on this PlayerSpaceship.
Example: player:getMaxCoolant() - PlayerSpaceship PlayerSpaceship:setScanProbeCount(number amount)
- Sets the number of scan probes stocked by this PlayerSpaceship.
Values are limited from 0 to the scan probe count max. Negative or excess values are capped to the limits.
Example: player:setScanProbeCount(20) -- sets the ship's scan probes to either 20 or the max limit, whichever is fewer
Returns the object it was called on. - number PlayerSpaceship:getScanProbeCount()
- Returns the number of scan probes stocked by this PlayerSpaceship.
Example: player:getScanProbeCount() - PlayerSpaceship PlayerSpaceship:setMaxScanProbeCount(number amount)
- Sets this PlayerSpaceship's capacity for scan probes.
Valid values are 0 or any positive number.
If the new limit is less than the current scan probe stock, this automatically reduces the stock.
Example: player:setMaxScanProbeCount(30) -- sets the ship's scan probe capacity to 30
Returns the object it was called on. - number PlayerSpaceship:getMaxScanProbeCount()
- Returns this PlayerSpaceship's capacity for scan probes.
Example: player:getMaxScanProbeCount() - PlayerSpaceship PlayerSpaceship:addCustomButton(ECrewPosition position, string name, string caption, ScriptSimpleCallback callback, number order=nil)
- Adds a custom interactive button with the given reference name to the given crew position screen.
By default, custom buttons and info are stacked in order of creation. Use the order value to specify a priority, with lower values appearing higher in the list.
If the reference name is unique, this creates a new button. If the reference name exists, this modifies the existing button.
The caption sets the button's text label.
When clicked, the button calls the given function.
Example:
-- Add a custom button to Engineering, lower in the order relative to other items, that prints the player ship's coolant max to the console or logging file when clicked
player:addCustomButton("engineering","get_coolant_max","Get Coolant Max",function() print("Coolant: " .. player:getMaxCoolant()) end,10)
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:addCustomInfo(ECrewPosition position, string name, string caption, number order=nil)
- Adds a custom non-interactive info label with the given reference name to the given crew position screen.
By default, custom buttons and info are stacked in order of creation. Use the order value to specify a priority.
If the reference name is unique, this creates a new info. If the reference name exists, this modifies the existing info.
The caption sets the info's text value.
Example:
-- Displays the coolant max value on Engineering at or near the top of the custom button/info order
player:addCustomInfo("engineering","show_coolant_max","Coolant Max: " .. player:getMaxCoolant(),0)
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:addCustomMessage(ECrewPosition position, string name, string caption)
- Displays a dismissable message with the given reference name on the given crew position screen.
The caption sets the message's text.
Example:
-- Displays the coolant max value on Engineering as a dismissable message
player:addCustomMessage("engineering","message_coolant_max","Coolant max: " .. player:getMaxCoolant())
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:addCustomMessageWithCallback(ECrewPosition position, string name, string caption, ScriptSimpleCallback callback)
- As PlayerSpaceship:addCustomMessage(), but calls the given function when dismissed.
Example:
-- Displays the coolant max value on Engineering as a dismissable message, and prints "dismissed" to the console or logging file when dismissed
player:addCustomMessageWithCallback("engineering","message_coolant_max","Coolant max: " .. player:getMaxCoolant(),function() print("Dismissed!") end)
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:removeCustom(string name)
- Removes the custom function, info, or message with the given reference name.
Example: player:removeCustom("show_coolant_max") -- removes the custom item named "show_coolant_max"
Returns the object it was called on. - ESystem PlayerSpaceship:getBeamSystemTarget()
- Returns the index of the ESystem targeted by this PlayerSpaceship's weapons.
Returns -1 for the hull.
Example: player:getBeamSystemTarget() - string PlayerSpaceship:getBeamSystemTargetName()
- Returns the name of the ESystem targeted by this PlayerSpaceship's weapons.
Returns "UNKNOWN" for the hull.
Example: player:getBeamSystemTargetName() - PlayerSpaceship PlayerSpaceship:commandTargetRotation(number target)
- Commands this PlayerSpaceship to set a new target rotation.
A value of 0 is equivalent to a heading of 90 degrees ("east").
Accepts 0, positive, or negative values.
To objectively rotate the PlayerSpaceship as a SpaceObject, rather than commanding it to turn using its maneuverability, use SpaceObject:setRotation().
Examples:
player:commandTargetRotation(0) -- command the ship toward a heading of 90 degrees
heading = 180; player:commandTargetRotation(heading - 90) -- command the ship toward a heading of 180 degrees
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandImpulse(number target)
- Commands this PlayerSpaceship to request a new impulse speed.
Valid values are -1.0 (-100%; full reverse) to 1.0 (100%; full forward).
The ship's impulse value remains bound by its impulse acceleration rates.
Example: player:commandImpulse(0.5) -- command this ship to engage forward half impulse
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandWarp(number target)
- Commands this PlayerSpaceship to request a new warp level.
Valid values are any positive integer, or 0.
Warp controls on crew position screens are limited to 4.
Example: player:commandWarp(2) -- activate the warp drive at level 2
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandJump(number distance)
- Commands this PlayerSpaceship to request a jump of the given distance.
Valid values are any positive number, or 0, including values outside of the ship's minimum and maximum jump ranges.
A jump of a greater distance than the ship's maximum jump range results in a negative jump drive charge.
Example: player:commandJump(25000) -- initiate a 25U jump on the current heading
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandSetTarget(SpaceObject target)
- Commands this PlayerSpaceship to set its weapons target to the given SpaceObject.
Example: player:commandSetTarget(enemy)
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandLoadTube(number tubeNumber, EMissileWeapons missileType)
- Commands this PlayerSpaceship to load the WeaponTube with the given index with the given weapon type.
This command respects tube allow/disallow limits.
Example: player:commandLoadTube(0,"HVLI")
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandUnloadTube(number tubeNumber)
- Commands this PlayerSpaceship to unload the WeaponTube with the given index.
Example: player:commandUnloadTube(0)
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandFireTube(number tubeNumber, number missile_target_angle)
- Commands this PlayerSpaceship to fire the WeaponTube with the given index at the given missile target angle in degrees, without a weapons target.
The target angle behaves as if the Weapons crew had unlocked targeting and manually aimed its trajectory.
A target angle value of 0 is equivalent to a heading of 90 degrees ("east").
Accepts 0, positive, or negative values.
Examples:
player:commandFireTube(0,0) -- command firing tube 0 at a heading 90
target_heading = 180; player:commandFireTube(0,target_heading - 90) -- command firing tube 0 at a heading 180
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandFireTubeAtTarget(number tubeNumber, SpaceObject target)
- Commands this PlayerSpaceship to fire the given weapons tube with the given SpaceObject as its target.
Example: player:commandFireTubeAtTarget(0,enemy) -- command firing tube 0 at target `enemy`
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandSetShields(boolean enabled)
- Commands this PlayerSpaceship to raise (true) or lower (false) its shields.
Example: player:commandSetShields(true) -- command raising shields
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandMainScreenSetting(EMainScreenSetting mainScreen)
- Commands this PlayerSpaceship to change its Main Screen view to the given setting.
Example: player:commandMainScreenSetting("tactical") -- command setting the main screen view to tactical radar
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandMainScreenOverlay(EMainScreenOverlay mainScreen)
- Commands this PlayerSpaceship to change its Main Screen comms overlay to the given setting.
Example: player:commandMainScreenOverlay("hidecomms") -- command setting the main screen view to hide the comms overlay
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandScan(SpaceObject object)
- Commands this PlayerSpaceship to initiate a scan of the given SpaceObject.
If the scanning mini-game is enabled, this opens it on the relevant crew screens.
This command does NOT respect the player's ability to select the object for scanning, whether due to it being out of radar range or otherwise untargetable.
Example: player:commandScan(enemy)
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandSetSystemPowerRequest(ESystem system, number power_level)
- Commands this PlayerSpaceship to set the power level of the given system.
Valid values are 0 or greater, with 1.0 equivalent to 100 percent. Values greater than 1.0 are allowed.
Example: player:commandSetSystemPowerRequest("impulse",1.0) -- command setting the impulse drive power to 100%
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandSetSystemCoolantRequest(ESystem system, number coolant_level)
- Commands this PlayerSpaceship to set the coolant level of the given system.
Valid values are from 0 to 10.0, with 10.0 equivalent to 100 percent.
Values greater than 10.0 are allowed if the ship's coolant max is greater than 10.0, but controls on crew position screens are limited to 10.0 (100%).
Example: player:commandSetSystemCoolantRequest("impulse",10.0) -- command setting the impulse drive coolant to 100%
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandDock(SpaceObject station)
- Commands this PlayerSpaceship to initiate docking with the given SpaceObject.
This initiates docking only if the target is dockable and within docking range.
Example: player:commandDock(base)
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandUndock()
- Commands this PlayerSpaceship to undock from any SpaceObject it's docked with.
Example: player:commandUndock()
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandAbortDock()
- Commands this PlayerSpaceship to abort an in-progress docking operation.
Example: player:commandAbortDock()
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandOpenTextComm(SpaceObject obj)
- Commands this PlayerSpaceship to hail the given SpaceObject.
If the target object is a PlayerSpaceship or the GM is intercepting all comms, open text chat comms.
Example: player:commandOpenTextComm(base)
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandCloseTextComm()
- Commands this PlayerSpaceship to close comms.
Example: player:commandCloseTextComm()
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandAnswerCommHail(boolean awnser)
- Commands whether this PlayerSpaceship answers (true) or rejects (false) an incoming hail.
Example: player:commandAnswerCommHail(false) -- commands to reject an active incoming hail
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandSendComm(number index)
- Commands this PlayerSpaceship to select the reply with the given index during a comms dialogue.
Example: player:commandSendComm(0) -- commands to select the first option in a comms dialogue
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandSendCommPlayer(string message)
- Commands this PlayerSpaceship to send the given message to the active text comms chat.
This works whether the chat is with another PlayerSpaceship or the GM.
Example: player:commandSendCommPlayer("I will destroy you!") -- commands to send this message in the active text chat
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandSetAutoRepair(boolean enabled)
- Commands whether repair crews on this PlayerSpaceship automatically move to rooms of damaged systems.
Use this command to reduce the need for player interaction in Engineering, especially when combined with setAutoCoolant/auto_coolant_enabled.
Crews set to move automatically don't respect crew collisions, allowing multiple crew to occupy a single space.
Example: player:commandSetAutoRepair(true)
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandSetBeamFrequency(number frequency)
- Commands this PlayerSpaceship to set its beam frequency to the given value.
Valid values are 0 to 20, which map to 400THz to 800THz at 20THz increments. (spaceship.cpp frequencyToString())
Example: player:commandSetAutoRepair(true)
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandSetBeamSystemTarget(ESystem system)
- Commands this PlayerSpaceship to target the given ship system with its beam weapons.
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandSetShieldFrequency(number frequency)
- Sets this SpaceShip's shield frequency index.
To convert the index to the value used by players, multiply it by 20, then add 400.
Valid values are 0 (400THz) to 20 (800THz).
Unlike SpaceShip:setShieldsFrequency(), this initiates shield calibration to change the frequency, which disables shields for a period.
Example:
frequency = ship:setShieldsFrequency(10) -- frequency is 600THz
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandAddWaypoint(number position_x, number position_y)
- Commands this PlayerSpaceship to add a waypoint at the given coordinates.
This respects the 9-waypoint limit and won't add more waypoints if 9 already exist.
Example: player:commandAddWaypoint(1000,2000)
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandRemoveWaypoint(number index)
- Commands this PlayerSpaceship to remove the waypoint with the given index.
This uses a 0-index, while waypoints are numbered on player screens with a 1-index.
Example: player:commandRemoveWaypoint(0) -- removes waypoint 1
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandMoveWaypoint(number index, number position_x, number position_y)
- Commands this PlayerSpaceship to move the waypoint with the given index to the given coordinates.
This uses a 0-index, while waypoints are numbered on player screens with a 1-index.
Example: player:commandMoveWaypoint(0,-1000,-2000) -- moves waypoint 1 to -1000,-2000
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandActivateSelfDestruct()
- Commands this PlayerSpaceship to activate its self-destruct sequence.
Example: player:commandActivateSelfDestruct()
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandCancelSelfDestruct()
- Commands this PlayerSpaceship to cancel its self-destruct sequence.
Example: player:commandCancelSelfDestruct()
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandConfirmDestructCode(number index, number code)
- Commands this PlayerSpaceship to submit the given self-destruct authorization code for the code request with the given index.
Codes are 0-indexed. Index 0 corresponds to code A, 1 to B, etc.
Example: player:commandConfirmDestructCode(0,46223) -- commands submitting 46223 as self-destruct confirmation code A
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandCombatManeuverBoost(number amount)
- Commands this PlayerSpaceship to set its forward combat maneuver to the given value.
Valid values are any from -1.0 (full reverse) to 1.0 (full forward).
The maneuver continues until the ship's combat maneuver reserves are depleted.
Crew screens allow only forward combat maneuvers, and the combat maneuver controls do not reflect a boost set via this command.
Example: player:commandCombatManeuverBoost(0.5) -- commands boosting forward at half combat maneuver capacity
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandLaunchProbe(number target_position_x, number target_position_y)
- Commands this PlayerSpaceship to launch a ScanProbe to the given coordinates.
Example: player:commandLaunchProbe(1000,2000) -- commands launching a scan probe to 1000,2000
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandSetScienceLink(ScanProbe probe)
- Commands this PlayerSpaceship to link the science screen to the given ScanProbe.
This is equivalent to selecting a probe on Relay and clicking "Link to Science".
Unlike "Link to Science", this function can link science to any given probe, regardless of which ship launched it or what faction it belongs to.
Example: player:commandSetScienceLink(probe_object) -- link ScanProbe `probe` to this ship's science
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:commandClearScienceLink()
- Commands this PlayerSpaceship to unlink the science screen from any ScanProbe.
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 PlayerSpaceship:commandSetAlertLevel(EAlertLevel level)
- Commands this PlayerSpaceship to set the given alert level.
Valid values are "normal", "yellow", "red", which differ from the values returned by PlayerSpaceship:getAlertLevel().
Example: player:commandSetAlertLevel("red") -- commands red alert
Returns the object it was called on. - number PlayerSpaceship:getRepairCrewCount()
- Returns the number of repair crews on this PlayerSpaceship.
Example: player:getRepairCrewCount() - PlayerSpaceship PlayerSpaceship:setRepairCrewCount(number amount)
- Sets the total number of repair crews on this PlayerSpaceship.
If the value is less than the number of repair crews, this function removes repair crews.
If the value is greater, this function adds new repair crews into random rooms.
Example: player:setRepairCrewCount(5)
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:setAutoCoolant(boolean active)
- Defines whether automatic coolant distribution is enabled on this PlayerSpaceship.
If true, coolant is automatically distributed proportionally to the amount of heat in that system.
Use this command to reduce the need for player interaction in Engineering, especially when combined with commandSetAutoRepair/auto_repair_enabled.
Example: player:setAutoCoolant(true)
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:setControlCode(string code)
- Sets a control code password required for a player to join this PlayerSpaceship.
Control codes are case-insensitive.
Example: player:setControlCode("abcde") -- matches "abcde", "ABCDE", "aBcDe"
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:onProbeLaunch(ScriptSimpleCallback callback)
- Defines a function to call when this PlayerSpaceship launches a probe.
Passes the launching PlayerSpaceship and launched ScanProbe.
Example:
-- Prints probe launch details to the console output or logging file
player:onProbeLaunch(function (player, probe)
print("Probe " .. probe:getCallSign() .. " launched from ship " .. player:getCallSign())
end)
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:onProbeLink(ScriptSimpleCallback callback)
- Defines a function to call when this PlayerSpaceship links a probe to the science screen.
Passes the PlayerShip and linked ScanProbe.
Example:
-- Prints probe linking details to the console output or logging file
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 PlayerSpaceship:onProbeUnlink(ScriptSimpleCallback callback)
- Defines a function to call when this PlayerSpaceship unlinks a probe from the science screen.
Passes the PlayerShip and previously linked ScanProbe.
This function is not called when the probe is destroyed or expires.
See ScanProbe:onDestruction() and ScanProbe:onExpiration().
Example:
-- Prints probe unlinking details to the console output or logging file
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 PlayerSpaceship:getLongRangeRadarRange()
- Returns this PlayerSpaceship's long-range radar range.
Example: player:getLongRangeRadarRange() - number PlayerSpaceship:getShortRangeRadarRange()
- Returns this PlayerSpaceship's short-range radar range.
Example: player:getShortRangeRadarRange() - PlayerSpaceship PlayerSpaceship:setLongRangeRadarRange(number range)
- Sets this PlayerSpaceship's long-range radar range.
PlayerSpaceships use this range on the science and operations screens' radar.
Example: player:setLongRangeRadarRange(30000) -- sets the ship's long-range radar range to 30U
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:setShortRangeRadarRange(number range)
- Sets this PlayerSpaceship's short-range radar range.
PlayerSpaceships use this range on the helms, weapons, and single pilot screens' radar.
This also defines the shared radar radius on the relay screen for friendly ships and stations, and how far into nebulae that this SpaceShip can detect objects.
Example: player:setShortRangeRadarRange(5000) -- sets the ship's long-range radar range to 5U
Returns the object it was called on. - PlayerSpaceship PlayerSpaceship:setCanScan(boolean enabled)
- Defines whether scanning features appear on related crew screens in this PlayerSpaceship.
Example: player:setCanScan(true)
Returns the object it was called on. - boolean PlayerSpaceship:getCanScan()
- Returns whether scanning features appear on related crew screens in this PlayerSpaceship.
Example: player:getCanScan() - PlayerSpaceship PlayerSpaceship:setCanHack(boolean enabled)
- Defines whether hacking features appear on related crew screens in thisPlayerSpaceship.
Example: player:setCanHack(true)
Returns the object it was called on. - boolean PlayerSpaceship:getCanHack()
- Returns whether hacking features appear on related crew screens in this PlayerSpaceship.
Example: player:getCanHack() - PlayerSpaceship PlayerSpaceship:setCanDock(boolean enabled)
- Defines whether the "Request Docking" button appears on related crew screens in this PlayerSpaceship.
This doesn't override any docking class restrictions set on a target SpaceShip.
Example: player:setCanDock(true)
Returns the object it was called on. - boolean PlayerSpaceship:getCanDock()
- Returns whether the "Request Docking" button appears on related crew screens in this PlayerSpaceship.
Example: player:getCanDock() - PlayerSpaceship PlayerSpaceship:setCanCombatManeuver(boolean enabled)
- Defines whether combat maneuver controls appear on related crew screens in this PlayerSpaceship.
Example: player:setCanCombatManeuver(true)
Returns the object it was called on. - boolean PlayerSpaceship:getCanCombatManeuver()
- Returns whether combat maneuver controls appear on related crew screens in this PlayerSpaceship.
Example: player:getCanCombatManeuver() - PlayerSpaceship PlayerSpaceship:setCanLaunchProbe(boolean enabled)
- Defines whether ScanProbe-launching controls appear on related crew screens in this PlayerSpaceship.
Example: player:setCanLaunchProbe(true)
Returns the object it was called on. - boolean PlayerSpaceship:getCanLaunchProbe()
- Returns whether ScanProbe-launching controls appear on related crew screens in this PlayerSpaceship.
Example: player:getCanLaunchProbe() - PlayerSpaceship PlayerSpaceship:setCanSelfDestruct(boolean enabled)
- Defines whether self-destruct controls appear on related crew screens in this PlayerSpaceship.
Example: player:setCanSelfDestruct(true)
Returns the object it was called on. - boolean PlayerSpaceship:getCanSelfDestruct()
- Returns whether self-destruct controls appear on related crew screens in this PlayerSpaceship.
This returns false if this ship's self-destruct size and damage are both 0, even if you set setCanSelfDestruct(true).
Example: player:getCanSelfDestruct() - PlayerSpaceship PlayerSpaceship:setSelfDestructDamage(number amount)
- Sets the amount of damage done to nearby SpaceObjects when this PlayerSpaceship self-destructs.
Any given value is randomized +/- 33 percent upon self-destruction.
Example: player:setSelfDestructDamage(150)
Returns the object it was called on. - number PlayerSpaceship:getSelfDestructDamage()
- Returns the amount of base damage done to nearby SpaceObjects when this PlayerSpaceship self-destructs.
Example: player:getSelfDestructDamage() - PlayerSpaceship PlayerSpaceship:setSelfDestructSize(number size)
- Sets the radius of the explosion created when this PlayerSpaceship self-destructs.
All SpaceObjects within this radius are dealt damage upon self-destruction.
Example: player:setSelfDestructSize(1500) -- sets a 1.5U self-destruction explosion and damage radius
Returns the object it was called on. - number PlayerSpaceship:getSelfDestructSize()
- Returns the radius of the explosion created when this PlayerSpaceship self-destructs.
All SpaceObjects within this radius are dealt damage upon self-destruction.
Example: ship:getSelfDestructSize()
SpaceStation
A SpaceStation is an immobile ship-like object that repairs, resupplies, and recharges ships that dock with it.
It sets several ShipTemplateBasedObject properties upon creation:
- Its default callsign begins with "DS".
- It restocks scan probes and CpuShip weapons by default.
- It uses the scripts/comms_station.lua comms script by default.
- When destroyed by damage, it awards or deducts a number of reputation points relative to its total shield strength and segments.
- Any non-hostile SpaceShip can dock with it by default.
Subclass of:
ShipTemplateBasedObject
SupplyDrop
A SupplyDrop is a collectible item picked up on collision with a friendly SpaceShip.
On pickup, the SupplyDrop restocks one type of the colliding SpaceShip's weapons.
If the ship is a PlayerSpaceship, it can also recharge its energy.
A SupplyDrop can also trigger a scripting function upon pickup.
For a more generic object with similar collision properties, see Artifact.
Example: SupplyDrop():setEnergy(500):setWeaponStorage("Homing",6)
Subclass of:
SpaceObject- SupplyDrop SupplyDrop:setEnergy(number amount)
- Sets the amount of energy recharged upon pickup when a PlayerSpaceship collides with this SupplyDrop.
Example: supply_drop:setEnergy(500)
Returns the object it was called on. - SupplyDrop SupplyDrop:setWeaponStorage(EMissileWeapons weapon, number amount)
- Sets the weapon type and amount restocked upon pickup when a SpaceShip collides with this SupplyDrop.
Example: supply_drop:setWeaponStorage("Homing",6)
Returns the object it was called on. - SupplyDrop SupplyDrop:onPickUp(ScriptSimpleCallback callback)
- Defines a function to call when a SpaceShip collides with the supply drop.
Passes the supply drop and the colliding ship (if it's a PlayerSpaceship) to the function.
Example: supply_drop:onPickUp(function(drop,ship) print("Supply drop picked up") end)
Returns the object it was called on.
VisualAsteroid
A VisualAsteroid is an inert piece of space terrain positioned above or below the movement plane.
For an asteroid that ships might collide with, use an Asteroid.
Example: vasteroid = VisualAsteroid():setSize(150):setPosition(1000,2000)
Subclass of:
SpaceObject- VisualAsteroid VisualAsteroid:setSize(number size)
- Sets this VisualAsteroid's radius.
Defaults to a random value between 110 and 130.
Example: vasteroid:setSize(150)
Returns the object it was called on. - number VisualAsteroid:getSize()
- Returns this VisualAsteroid's radius.
Example: vasteroid():getSize()
WarpJammer
A WarpJammer restricts the ability of any SpaceShips to use warp or jump drives within its radius.
WarpJammers can be targeted, damaged, and destroyed.
Example: jammer = WarpJammer():setPosition(1000,1000):setRange(10000):setHull(20)
Subclass of:
SpaceObject- number WarpJammer:getRange()
- Returns this WarpJammer's jamming range, represented on radar as a circle with jammer in the middle.
No warp/jump travel is possible within this radius.
Example: jammer:getRange() - WarpJammer WarpJammer:setRange(number range)
- Sets this WarpJammer's jamming radius.
No warp/jump travel is possible within this radius.
Defaults to 7000.0.
Example: jammer:setRange(10000) -- sets a 10U jamming radius
Returns the object it was called on. - number WarpJammer:getHull()
- Returns this WarpJammer's hull points.
Example: jammer:getHull() - WarpJammer WarpJammer:setHull(number hull)
- Sets this WarpJammer's hull points.
Defaults to 50
Example: jammer:setHull(20)
Returns the object it was called on. - WarpJammer WarpJammer:onTakingDamage(ScriptSimpleCallback callback)
- Defines a function to call when this WarpJammer takes damage.
Passes the WarpJammer object and the damage instigator SpaceObject (or nil if none).
Example: jammer:onTakingDamage(function(this_jammer,instigator) print("Jammer damaged!") end)
Returns the object it was called on. - WarpJammer WarpJammer:onDestruction(ScriptSimpleCallback callback)
- Defines a function to call when the WarpJammer is destroyed by taking damage.
Passes the WarpJammer object and the damage instigator SpaceObject (or nil if none).
Example: jammer:onDestruction(function(this_jammer,instigator) print("Jammer destroyed!") end)
Returns the object it was called on.
WormHole
A WormHole is a piece of space terrain that pulls all nearby SpaceObjects within a 5U radius, including otherwise immobile objects like SpaceStations, toward its center.
Any SpaceObject that reaches its center is teleported to another point in space.
AI behaviors avoid WormHoles by a 2U margin.
Example: wormhole = WormHole():setPosition(1000,1000):setTargetPosition(10000,10000)
Subclass of:
SpaceObject- WormHole WormHole:setTargetPosition(number v_x, number v_y)
- Sets the target teleportation coordinates for SpaceObjects that pass through the center of this WormHole.
Example: wormhole:setTargetPosition(10000,10000)
Returns the object it was called on. - number x, number y WormHole:getTargetPosition()
- Returns the target teleportation coordinates for SpaceObjects that pass through the center of this WormHole.
Example: wormhole:getTargetPosition() - WormHole WormHole:onTeleportation(ScriptSimpleCallback callback)
- Defines a function to call when this WormHole teleports a SpaceObject.
Passes the WormHole object and the teleported SpaceObject.
Example:
-- Outputs teleportation details to the console window and logging file
wormhole:onTeleportation(function(this_wormhole,teleported_object) print(teleported_object:getCallSign() .. " teleported to " .. this_wormhole:getTargetPosition()) end)
Returns the object it was called on.
Zone
A Zone is a polygonal area of space defined by a series of coordinates.
Although a Zone is a SpaceObject, it isn't affected by physics and isn't rendered in 3D.
Zones are drawn on GM, comms, and long-range radar screens, can have a text label, and can return whether a SpaceObject is within their bounds.
New Zones can't be created via the exec.lua HTTP API.
Example:
-- Defines a blue rectangular 200sqU zone labeled "Home" around 0,0
zone = Zone():setColor(0,0,255):setPoints(-100000,100000, -100000,-100000, 100000,-100000, 100000,100000):setLabel("Home")
Subclass of:
SpaceObject- Zone Zone:setPoints(number points_x, number points_y...)
- Sets the corners of this Zone n-gon to x_1, y_1, x_2, y_2, ... x_n, y_n.
Positive x coordinates are right/"east" of the origin, and positive y coordinates are down/"south" of the origin in space.
Example: zone:setPoints(2000,0, 0,3000, -2000,0) -- defines a triangular zone
Returns the object it was called on. - Zone Zone:setColor(number r, number g, number b)
- Sets this Zone's color when drawn on radar.
Defaults to white (255,255,255).
Example: zone:setColor(255,140,0)
Returns the object it was called on. - Zone Zone:setLabel(string label)
- Sets this Zone's text label, rendered at the zone's center point.
Example: zone:setLabel("Hostile space")
Returns the object it was called on. - string Zone:getLabel()
- Returns this Zone's text label.
Example: zone:getLabel() - boolean Zone:isInside(SpaceObject obj)
- Returns whether the given SpaceObject is inside this Zone.
Example: zone:isInside(obj) -- returns true if `obj` is within the zone's bounds
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 TutorialGame:setPlayerShip(PlayerSpaceship ship)
- Returns the object it was called on.
- TutorialGame TutorialGame:switchViewToMainScreen()
- Returns the object it was called on.
- TutorialGame TutorialGame:switchViewToTactical()
- Returns the object it was called on.
- TutorialGame TutorialGame:switchViewToLongRange()
- Returns the object it was called on.
- TutorialGame TutorialGame:switchViewToScreen(number n)
- Returns the object it was called on.
- TutorialGame TutorialGame:showMessage(string message, boolean show_next)
- Returns the object it was called on.
- TutorialGame TutorialGame:setMessageToTopPosition()
- Returns the object it was called on.
- TutorialGame TutorialGame:setMessageToBottomPosition()
- Returns the object it was called on.
- TutorialGame TutorialGame:onNext(ScriptSimpleCallback callback)
- Returns the object it was called on.
- TutorialGame TutorialGame:finish()
- Returns the object it was called on.
- boolean TutorialGame:isValid()
- Returns whether this object is still valid. Returns false if this object was destroyed or doesn't exist.
- TutorialGame TutorialGame:destroy()
- Removes this object from the game.
Returns the object it was called on. - TutorialGame:typeName
- Returns the class name of this object. This is not a function, but a direct member. Example: if object.typeName == "Mine" then print("MINE!") end