Script reference

Classes

Following classes are exposed to the script. vec3 is a simple 3D vector available in script as "value" type. All others are "reference" types and new instances cannot be created inside script. All except EngineInterface can be stored as global variables. Following are class hierarchies shown as class inheritance Base class > Derived class.

  • Targetable > Fighter
  • Targetable > Object
  • Object > Ship
  • Object > Subsystem
  • Object > Hardpoint
  • Object > Turret
  • Object > ResourceContainer
  • ResourceContainer > Debris

There is implicit casting from derived classes to base classes. That means that if you have reference to class, you can access properties and methods of its base classes. Remember that inheritance is transitive, so you can access methods of Targetable through reference to Debris

If you have reference to base class and want to access methods of derived class you must perform explicit cast. To determine what class object is, you use Targetable's method getObjectType(). Example:
You have Targetable@ thing; and calling thing.getObjectType() returns TYPE_SHIP. Now you can cast to Ship like this: Ship@ thing_as_ship = cast<Ship>(thing);. In this case, you could also cast to Object@. It is completely vital that you always check if you can perform cast before doing so. If possible, avoid at all.

vec3

PropertyDescription
float x
float y
float z
MethodDescriptionParameters
void setInvalid() Sets vector to invalid position.
bool isInvalid() Returns true if position is invalid.
OperatorsDescriptionParameters
vec3 + vec3 Component wise add
vec3 + float Returns vec3 with added float to each component
vec3 - vec3 Component wise subtract
vec3 + float Returns vec3 with subtracted float from each component
vec3 * vec3 Component wise multiplication
vec3 * float Returns vec3 with each component multiplied by float
vec3 / vec3 Component wise division
vec3 / float Returns vec3 with each component divided by float
Globals (included here for convenience)DescriptionParameters
float length2(vec3) Returns squared length of this vector. Useful for performance when lot of lengths are needed for comparisons (though script overhead might be bigger than sqrt would be, this may apply to fast versions as well)
float fastLength(vec3) Returns length of vector, sacrificing some precision for speed (only useful when there are many, many calculations needed)
float length(vec3) Returns length of vector
vec3 fastNormalize(vec3) Returns normalized vector, sacrificing some precision for speed (only useful when there are many, many calculations needed)
vec3 fastNormalize(vec3) Returns normalized vector
float dot(vec3,vec3) Returns dot product of two vectors
vec3 cross(vec3,vec3) Returns cross product of two vectors

EngineInterface

- bool. Indicates if this should be treated as voice - vec3. Color of icon
PropertyDescription
uint stepNumber Number of game steps that have passed since the start of game. First step is 0. Use STEPS_PER_SECOND to determine number of steps executed per second. (at the time of writing, 20, but use constant so script doesn't break if this changes)
int screenWidth WARNING: do not use this for anything game changing! Will cause desyncs. For GUI only!
int screenHeight WARNING: do not use this for anything game changing! Will cause desyncs. For GUI only!
bool lastManStanding is true if multiplayer match is set to "last man standing" win condition, if false "most damage" is set.
MethodDescriptionParameters
uint getNum[Objects,ResourceContainers,Debris,Ships,Fighters]() Returns number of [one of those things] that are currently in game.
[Object@,ResourceContainer@,Debris@,Ship@,Fighter@] get[Object,ResourceContainer,Debris,Ship,Fighter](uint) Get [one of those things] (e.g. Object@ getObject(uint) at specified index. Index must be lower than value returned by corresponding getNum[X] function. Returned value is never null. If you need to store returned object in global variable, store it as reference, not as index. Index might change from step to step. - uint. Index of [one of those things] to be retrieved.
Object@ getAll(uint) Same as above, but all object types are in one array. getNumAll() gets you number of all objects in this list - Object, ResourceContainer, Debris, Ship (does not include fighters) - uint. Index.
Player@ getPlayerNeutral() Returns neutral player. Guaranteed to not be null. This is not one of regular players returned by following functions.
uint getNumPlayers() Return number of regular players.
Player@ getPlayer(uint) Gets player by index. If index is equal or higher than value returned by getNumPlayers(), neutral player is returned. - uint. Index of player to be retrieved.
Player@ getPlayer(string) Gets player by name. Searching by name is not case-sensitive. If no player matches queried name, neutral player is returned. - string. Name of player to be retrieved.
vec3 getPointOfInterest(string) Gets point of interest by name. Search is not case-sensitive. If no such point is found, returned vec3 will be marked as invalid (test by isInvalid() method)
void issueOrder(Ship@,OrderType,Object@,vec3,bool,string) Issue order to a ship. Orders will be applied at the beggining of next game step in order as they were issued from script. Target object may be null if order does not require it. Order might be issued even to ships owned by human players, use with caution. Allowed types for target object are: Object, ResourceContainer, Debris, Ship, Subsystem, Hardpoint. - Ship@. Ship which receives order.
- OrderType. Type of order for ship.
- Object@. Target object. Can be null.
- vec3. Target position if target object is not specified. Can by any position if order does not require position.
- bool. Specifies if order should be put in order queue (as when holding 'shift' key)
- string. Additional info, if needed. Such as ship or fighter stat name for building orders. Pass empty string otherwise.
void activateAbility(Ship@,AbilityType) - Ship@. Ship which receives order.
- AbilityType. Ability to be activated.
void deactivateAbility(Ship@,AbilityType) - Ship@. Ship which receives order.
- AbilityType. Ability to be deactivated.
void castAbility(Ship@,AbilityType,Object@) - Ship@. Ship which receives order.
- AbilityType. Ability to be cast.
- Object@. Target.
void spawnShip(string,uint,Player@,vec3,vec3) Creates ship in an empty space near a given position. If owner is not specified, no ship will be created. Ships will be created with full energy, shields and missile banks. Ships will have empty cargoholds, fighterbays and crewquarters. - string. Stat name of ship to be created.
- uint. Number of ships to be spawned. Capped at 100 per function call.
- Player@. Owner of created ships. If null, no ships will be created.
- vec3. Position where ships are created.
- vec3. Position which ships will face when created.
void respawnFromPoolByID(string,string,Player@,vec3,vec3) Respawns a ship from saved pool at an empty space near a given position. If owner is not specified, no ship will be respawn. Ship will respawn in a state in which it entered a pool. If ship entered a pool by warping out, it will respawn by warping in. - string. Name of a pool from which to take ship.
- string. Identifier of a ship with which it was inserted into pool.
- Player@. Owner of respawned ship. If null, no ship will respawn.
- vec3. Position where ship will respawn.
- vec3. Position which ship will face when respawned.
void respawnFromPoolLast(string,Player@,vec3,vec3) Respawns a ship from saved pool at an empty space near a given position. If owner is not specified, no ship will be respawned. Ship will respawn in a state in which it entered a pool. If ship entered a pool by warping out, it will respawn by warping in. - string. Name of a pool from which to take ship.
- Player@. Owner of respawned ship. If null, no ship will respawn.
- vec3. Position where ship will respawn.
- vec3. Position which ship will face when respawned.
void respawnFromPoolAll(string,Player@,vec3,vec3) Respawns ships from saved pool at an empty space near a given position. If owner is not specified, no ship will respawn. Ships will respawn in a state in which they entered a pool, trying to maintain formation at which they entered a pool. If ship entered pool by warping out, it will respawn by warping in. - string. Name of a pool from which to take ship.
- Player@. Owner of respawned ship. If null, no ship will respawn.
- vec3. Position where ship will respawn.
- vec3. Position which ship will face when respawned.
void storeObjectToPool(Object@,string,string) Stores any object to pool at the end of mission, so they can be restored in another mission without warping. Useful e.g. to return to previous area in state as it was left in some previous mission, or preserving ships with their kill counts, etc.
If the same object is stored more than once, it will be added only to first pool, all other will be ignored.
Note: this will only work when called from onMissionEnd(). Calls made elsewhere will be ignored
- Object@. Object to be stored.
- string. Name of pool.
- string. Identifier of object, which can be used respawn this specific object.
void endMission() Ends this mission.
void createMessagebox(string,string) Create a simple message box. - string. Title
- string. Message. Message may contain \n newlines.
void drawText(string,int,int,vec3,float,string) Draws a text on screen, starting at specified coordinates. - string. Text to be drawn.
- int. x screen coordinate in pixels. 0 is left.
- int. y screen coordinate in pixels. 0 is bottom.
- vec3. RGB color in range <0,1>.
- float. Alpha of text. 0 is fully transparent, 1 fully opaque.
- string. Font to be used. If font is not found, default will be used.
uint getTextWidth(string,string) Gets width of text in pixels. - string. Queried text.
- string. Font to be used. If font is not found, default will be used.
string createColorTag(vec3,float) creates a string that will be interpreted as a command to change color by renderer (does not add any visible characters). You can add this anywhere to your text - vec3. RGB Color in range 0.0-1.0
- float. Alpha (opacity)
void insertTextMessage(string,float) displays a text message to player - string. Text to be presented to player
- float. (Optional) number of seconds this message is displayed before being removed. If not specified, default is used
void playSound(string,float,bool) Plays sound - string. name of sound (do not include extension)
- float. Gain/volume multiplied by user settings, used only for non-voices
void drawSensorIcon(SensorIconType,vec3,vec3) Draws icon in sensor view at specified position - SensorIconType. Icon to be drawn
- vec3. Position at which icon appears
void setCameraCenter(vec3) Sets camera look at point to given position - vec3. Position.
void giveResearch(string, Player@) Gives specified research to player. - string. Stat name of research.
- Player@. Player to receive research.
void giveAllResearch(Player@) Gives all research to player, even for factions he doesn't own - Player@. Player to receive research.
void disallowAllResearch(Player@) Disallows all research for player, even for factions he doesn't own - Player@. Player to disallow research.
void setPersistentData(string,string) Assigns string value to a given key to persistent data - string. Key to which value will be assigned.
- string. Value to be assigned to key.
string getPersistentData(string) Returns string value assigned to given key. If there is no value assigned to given key, empty string is returned - vec3. Key.
void logPersistentData() Logs all current persistent data to script log as "key -> value" lines
void logObjectPools() Logs all current object pools to script log as "key -> number of items" lines

Player

MethodDescriptionParameters
bool isDefeated() Returns true if player is defeated.
void setDefeated() Sets player as defeated if he is not already victorious. Effect is instantaneous.
bool isVictorious() Returns true if player is victorious.
void setVictorious() Sets player victorious if he is not already defeated. Effect is instantaneous.
vec3 getColor() Returns RGB player color in range <0,1>.
string getName()
int getPlayerIndex() Returns player index. Index does not change throughout the game.
bool isAlly(Player@) Returns true if players are mutual allies. - Player@. Other player to be tested.
bool isEnemy(Player@) Returns true if player is enemy. This is a one way relation. - Player@. Other player to be tested.
bool isFriendly(Player@) Returns true if player is friendly. This is a one way relation. Compare to isAlly(Player@). - Player@. Other player to be tested.
bool isNeutral() Returns true if this player is neutral player.
void setAlliance(Player@) Sets mutual alliance between players. - Player@. Other player.
void cancelAlliance(Player@) Cancels alliance. Both players will be enemies. - Player@. Other player.
void disallowVision(Player@) Disables sensor vision sharing between players. Both ways. Sharing is enabled by default if players are mutual allies. - Player@. Other player.
void allowVision(Player@) Enables sensor vision sharing between players. Both ways. Sharing is enabled by default if players are mutual allies. - Player@. Other player.
bool isPlayerLocal() Returns true if player is controlled by human at this computer. WARNING: do not use this value for anything game changing! Will cause desyncs. For GUI only!
bool isPlayerNetwork() Returns true if player is controlled over network. WARNING: do not use this value for anything game changing! Will cause desyncs. For GUI only!
float getStatsDamageDealt()
float getStatsResourcesHarvested()
void disallowResearch(string) Disallows this research to be researched by player. If player already researched this, he can continue to use it. - string. Research stat name.
void allowResearch(string) Allows this research if it is disallowed. - string. Research stat name.
bool isResearchDisallowed(string) Returns true if research is disallowed. Already researched research can still be disallowed and used. - string. Research stat name.

Targetable

Method Description Parameters
bool isTargetable() Returns true if object can be targeted. If not targetable, object is being destroyed or warping out.
ObjectType getObjectType() Returns enum describing what type of object this really is.
Player@ getOwner() Returns player to whom this object belongs. Returned player is never null.
float getArmour() Returns current armour value for this object.
void setOwner(Player@) Gives this object to specified player. If this is ship with fighters, owner of fighters is also changed - Player@. New owner. Must not by null.
uint getNumAttackers() Returns number of ships that are attacking this object. If attackers are fighters, only their base ship is counted.
vec3 getPosition() Returns (x,y,z) position of object. Z is up axis. Units are meters.
vec3 getFrontDirection() Returns direction object is facing. This has potential to be useful for ships.
float getDistance2(const Targetable@) Returns squared distance to another object. (note: distance is measured between object centers) - object to which distance is measured. Must not be null
bool isSensorVisible(const Player@) Returns true if specified player can see this object on sensors at least as unknown. - const Player@. Player whose sensor info is being checked
bool isSensorFull(const Player@) Returns true if specified player has full info about this object on sensors. - const Player@. Player whose sensor info is being checked

Object

MethodDescriptionParameters
DamageLevel getDamageLevel() Returns damage level of this object.
string getDesignation() Returns name given to this object in map editor or by player.
bool hasTag(string) Tags can be useful for scripting purposes (e.g. tag some ships as "attack_wave_2"), can be changed by script or in editor. Number of tags is unlimited
void addTag(string)
void removeTag(string)
string getStatName() Returns identifier of object type. This is same as .stat file name.
float getHitpoints() Returns current amount of hit points object has. Shields are included.
float getMaxHitpoints() Returns maximum amount of hit points object can have. Shields are included.
bool damage(Object&, float) Damages this object. Returns true if this function destroyed this object. Armour does not matter here. - Object&. Should be ship that is attacking this targetable. Can be null.
- float. Amount of damage that should be dealt.
void damageEMP(Object&, float) Damages subsystem hitpoints. It only makes sense if this is subsystem... Resistance to EMP damage does not matter here. - Object&. Should be ship that is attacking this targetable. Can be null.
- float. Amount of damage that should be dealt.
+ all from Targetable

ResourceContainer

MethodDescriptionParameters
int getResourcesLeft() Returns resources left that can be mined
int getCrystalsLeft() Returns crystals left that can be mined
bool isMineable() Returns true if there are any resources or crystals left
+ all from Object

Debris

MethodDescriptionParameters
+ all from Resource container

Ship

MethodDescriptionParameters
ShipType getShipType() Returns ship type enum.
string getFullDisplayName() Get display name composed of class name, ship type and sub-type.
OrderType getOrder() Returns ship's current order.
Object@ getTarget() Returns ship's current target or null if ship doesn't have target.
vec3 getDestination() Returns ship's current destination. It is guaranteed that ship will try to get to this position only if ship's order is SHIP_ORDER_MOVE.
float getFiringDistance() Ship will get at least this close to it's target.
bool canPerformOrder(OrderType,const Object@) Returns true if this ship is able to perform given order. If object is null, only ability to perform order type is checked. If object is not null, function returns true only if ship can perform order on that object (e.g. SHIP_ORDER_ATTACK will result in false, if object is friendly) - OrderType which is being tested
- Object@ to be tested
bool isInoperable() Returns true if ship cannot do anything due to reasons as being constructed or scrapped.
bool isScaffolded() Returns true if ship is under scaffold.
bool isUnderConstruction()
bool isBeingScrapped()
bool hasEmptyConstructionQueue()
ShipStatus getShipStatus()
float getCargoCapacity() Returns cargo capacity. Both resources and crystals use same space.
float getCargoResources()
float getCargoCrystals()
int getMaxPassengers() Returns maximum number of passengers this ship will try to maintain. If current number of passengers exceed this limit, ship will not accept more escape pods.
int getPassengers() Returns current number of passengers/crew that can be used to build ships.
uint getNumSubsystems() Returns number of subsystems this ship have.
Subsystem@ getSubsystem(uint) Returns subsystem. Specified index must be lower than value returned by getNumSubsystems(). Returned subsystem is never null. - uint. Index of subsystem to be retrieved
bool canCastAbilityOn(AbilityType,Object@,vec3) Returns true if this ship can cast ability on given target. For activate/deactivate abilities, use this ship as target. - AbilityType being tested
- Object@ target (can be null).
- vec3 position, if applicable, e.g. for microwarp
bool hasActiveAbility(AbilityType) Returns true if this ship has activated ability. - AbilityType being tested
float getShipAutoTargetScore(const Object@) Returns targeting priority of this ship for given object based on this ships and targets class, if object is ship. Bigger score means higher target preference. - Object@ being tested
float getBaseExperienceOffensive() Returns base offensive experience of this ship. Offensive experience is gained by doing damage, or repairing by repair beam (repairing gains experience at half rate). Experience is equal to 1 if amount of damage done is equal to total hitpoints of this ship. Experience has no upper limit, but has applied log function to it, and multiplied by settings in dataset config. Offensive experience improves weapon reload and accuracy.
float getBaseExperienceDefensive() Returns base defensive experience of this ship. Defensive experience is gained by receiving damage. Defensive experience increases passive self-repair speed when not under attack.
void setBaseExperienceOffensive(float)
void setBaseExperienceDefensive(float)
Cheat methods - useful for initUsing them makes stuff magically appear/disappearThink twice about how player will feel ---E
bool loadCargo(float,float) Cargo magically appears in cargoholds. Returns true if there was enough space for all cargo. Returns false otherwise, but as much cargo was added as possible. - uint. Resources
- uint. Crystals
bool unloadCargo(float,float) Cargo magically disappears from cargoholds. If there isn't enough resources OR crystals on ship, nothing is removed and function returns false. - uint. Resources
- uint. Crystals
bool loadPassengers(int) Passengers magically appear in crew quarters. Returns true if there was enough space for all. Returns false otherwise, but as many were loaded as possible. - uint. num of passengers
bool unloadPassengers(int) Passengers magically disappear from crew quarters. If ship doesn't have that many passengers, none are removed and function returns false. - uint. num of passengers
void cheatRestoreShield() Remember kids, cheating is bad...
void cheatRestoreEnergy() Remember kids, cheating is baad...
void cheatFillCrewquarters() Remember kids, cheating is baaad...
void cheatFillCargoholds() Remember kids, cheating is baaaad...
void cheatReloadMissiles() Remember kids, cheating is baaaaad...
void cheatServiceFighters() Remember kids, cheating is baaaaaad...
+ all from Object

Subsystem

Method Description Parameters
SubsystemType getSubsystemType() Returns enum describing subsystem type.
float getSubsystemHealth() Returns value between 0.0 - 1.0, indicating condition of subsystem (not hitpoints).
uint getNumHardpoints() Returns number of hardpoints on this subsystem.
Hardpoint@ getHardpoint(uint) Returns hardpoint. Specified index must be lower than value returned by getNumHardpoints(). Returned hardpoint is never null.
Ship@ getParentShip()
+ all from Object

Hardpoint

MethodDescriptionParameters
uint getNumTurrets() Returns number of turrets on this subsystem.
Turret@ getTurret(uint) Returns turret. Specified index must be lower than value returned by getNumTurrets(). Returned turret is never null.
Ship@ getParentShip()
Subsystem@ getParentSubsystem()
+ all from Object

Turret

MethodDescriptionParameters
TurretType getTurretType()
TurretRole getTurretRole()
float getTargetingRange() Returns maximum targeting range for this turret.

ShipStatus

PropertyDescription
float damagePerMinute
float damagePerMinuteAlphaWeighted
float hitpoints
float hitpointsArmourWeighted
float energyPerSecond
float energyPerSecondMax
float energyLeft
float energyCapacity
MethodDescriptionParameters