Avorion Script API Documentation
Entity
This represents an interface to an entity in the scene. Creating an object of this type will not create a new entity in the scene, but will rather enable access to an existing entity. Use the Sector class to create new entities.
Avorion uses an entity component system (See entity component system on Wikipedia). Thus, some properties and functions are only available if the entity has the corresponding component. The list of components can be found here: Enum ComponentType
Note: The id property of an Entity can be changed, but won't change the actual id of the underlying entity. Instead, the entity interface will be pointing to another entity with the new id. Use this for performance tuning to avoid creating lots of entity interfaces.
Note 2: This class is considered to have too many members and functions. Over time these will be phased out into their respective component classes. Only a few frequently used properties and functions will remain for coding comfort.
function Entity(var id)
Parameters
Returns
A new instance of Entity
| property bool aiOwned | [read-only] |
| property bool allianceOwned | [read-only] |
| property bool canPassRifts | [read-only] |
| property int controlActions |
| property Crew crew |
| property var crewSize | [read-only] |
| property float damageMultiplier |
| property float desiredVelocity |
| property bool dockable |
| property Uuid dockingParent | [read-only] |
| property double durability |
| property int excludedPlayer |
| property int exclusionTime |
| property int factionIndex |
| property bool fighterCargoPickup | [read-only] |
| property double firePower | [read-only] |
| property var freeCargoSpace | [read-only] |
| property bool hasPilot | [read-only] |
| property float hyperspaceCooldown |
| property float hyperspaceJumpReach |
| property Uuid id | [read-only] |
| property Crew idealCrew | [read-only] |
| property Uuid index | [read-only] |
| property bool invincible |
| property bool isAnomaly | [read-only] |
| property var isArmedTurret | [read-only] |
| property bool isAsteroid | [read-only] |
| property bool isContainer | [read-only] |
| property bool isDrone | [read-only] |
| property bool isFighter | [read-only] |
| property bool isFlyable | [read-only] |
| property bool isLoot | [read-only] |
| property bool isObviouslyMineable |
| property bool isOther | [read-only] |
| property var isShieldActive | [read-only] |
| property bool isShip | [read-only] |
| property bool isStation | [read-only] |
| property var isTurning | [read-only] |
| property bool isTurret | [read-only] |
| property var isUnarmedTurret | [read-only] |
| property bool isUnknown | [read-only] |
| property bool isWormHole | [read-only] |
| property bool isWreckage | [read-only] |
| property vec3 look | [read-only] |
| property var mass | [read-only] |
| property var maxCargoSpace | [read-only] |
| property var maxCrewSize | [read-only] |
| property var maxDurability | [read-only] |
| property Crew minCrew | [read-only] |
| property Entity mothership |
| property string name |
| property int numCargos | [read-only] |
| property int numDefenseWeapons | [read-only] |
| property int numDefenseWeaponsCurrentAttack | [read-only] |
| property var numDockingPositions | [read-only] |
| property var numTurrets | [read-only] |
| property var occupiedCargoSpace | [read-only] |
| property Matrix orientation |
| property bool playerOrAllianceOwned | [read-only] |
| property bool playerOwned | [read-only] |
| property Matrix position |
| property var radius | [read-only] |
| property float reservationTime |
| property int reservedPlayer |
| property vec3 right | [read-only] |
| property var selectedObject |
| property double shieldDurability |
| property double shieldMaxDurability |
| property float shieldMeshIntensity | [read-only] |
| property vec3 size | [read-only] |
| property var timeAlive | [read-only] |
| property string title |
| property var translatedTitle | [read-only] |
| property dvec3 translation |
| property vec3 translationf | [read-only] |
| property double transporterRange | [read-only] |
| property int type |
| property string typename | [read-only] |
| property vec3 up | [read-only] |
| property var volume | [read-only] |
function var addAbsoluteBias(int type, float value)
Adds a flat bias for stat of type type. This bias will be added to stat after multipliers are considered.
Parameters
value Bias added to base stats.
Returns
key that can be used to access the multiplier
function var addBaseMultiplier(int type, float factor)
Adds a multiplyer for stat of type type. This is to increase a stat, so a factor of 0.3 will become 1.3.
Parameters
factor Factor that is used as Multiplier
Returns
key that can be used to access the multiplier
function unsigned int addCargo(TradingGood good, int amount)
Adds cargo to the entity. If the amount specified exceeds the maximum capacity of the cargo bay, as much cargo as still fits in will be added.
Parameters
amount The amount of cargo that should be added.
Returns
How much was actually added (can be less than amount when cargo bay is full)
function var addCrew(int number, CrewMan crewman)
Returns
nothing
function var addKeyedAbsoluteBias(int type, int key, float value)
Exchanges flat bias at key with new value
Parameters
key Location of the bonus that will be changed
value New value
Returns
key that can be used to access the multiplier
function var addKeyedBaseMultiplier(int type, int key, float value)
Exchanges multiplier at key with new value
Parameters
key Location of the bonus that will be changed
value New value
Returns
key that can be used to access the multiplier
function var addKeyedMultiplier(int type, int key, float value)
Exchanges multiplier at key with new value
Parameters
key Location of the bonus that will be changed
value New value
Returns
key that can be used to access the multiplier
function var addKeyedMultiplyableBias(int type, int key, float value)
Exchanges bias at key with new value
Parameters
key Location of the bonus that will be changed
value New value
Returns
key that can be used to access the multiplier
function var addMultiplier(int type, float factor)
Adds a multiplyer for stat of type type. The factor will be used unchanged.
Parameters
factor Factor that is used as Multiplier
Returns
key that can be used to access the multiplier
function var addMultiplyableBias(int type, float value)
Adds a bias for stat of type type. This bias will be added to stat before multipliers are considered.
Parameters
value Bias added to base stats.
Returns
key that can be used to access the multiplier
function var addScript(string scriptPath, var... arguments)
Adds a new script to an entity
Parameters
arguments An arbitrary number of arguments that will be given to the 'initialize' function of the added script
Returns
0 on success, 1 if the entity could not be found
function var addScriptOnce()
function Uuid addTurret(TurretTemplate turret, Matrix position, int part)
function var blockHyperspace(float time)
Returns
nothing
function int callbacksRegistered(string callbackName, var functionName)
Check how many functions are registered to a callback from the current script VM.
Parameters
functionName The name of the function for which to check. If nil, will count all functions that are registered to this callback.
Returns
The amount of functions registered to the callback
function var, var, table<int, string> canAddCrew(int number, int profession, bool change)
function var changeCrew(int number, int profession)
Returns
nothing
function var changeShield(double delta)
Adds delta to shield durability
Parameters
Returns
nothing
function var clearCargoBay()
Returns
nothing
function var clearValues()
Removes all custom values of the object
Returns
nothing
function var damageShield(double amount, vec3 location, Uuid inflictorId, var damageSource, var damageType)
Damages shield by delta amount, location and inflictorId are not necessary, but can be added if it is needed, e.g. you want to do effects on hitpoint.
Parameters
location
inflictorId
Returns
nothing
function var destroy(Uuid inflictorId, var damageSource, var damageType)
Destroy entity by inflicting more damage than durability of entity
Parameters
damageSource Source of damage. Can be Weaponry, Collision, Decay, Torpedo or Arbitrary. *
damageType Type of damage received. Damage can be of type Physical, Energy, Electric, Plasma, AntiMatter or Fragments.
Returns
nothing
function var destroyBlock(int index, Uuid inflictorId, var damageSource)
Destroy one block
Parameters
inflictorId Index of the entity that destroys the block
damageSource Source of damage. Can be Weaponry, Collision, Decay, Torpedo or Arbitrary.
Returns
nothing
function var destroyCargo(float volume)
Destroys cargo. The destruction distribution is generally equal over all goods.
Parameters
Returns
nothing
function var disableFlightAssistFor(float time)
Returns
nothing
function var distortHyperspace(float time)
Returns
nothing
function table<TradingGood, int> findCargos(string name)
Finds all cargos with the given name.
Parameters
Returns
A map containing all matching goods, with the good as key and amount as value.
function vec3 getAimedPositionBySeat(int seat)
function vec3... getAimedPositions()
function var getAllowedArbitraryTurrets()
function var getAllowedArmedTurrets()
function var getAllowedUnarmedTurrets()
function var getAttachedBlockIndex()
Returns the Index of the block that the turret is build on
function var getBoostedValue(int type, float value)
Returns value with included bonus, in case a bonus exists. Returns Nil if no bonuses at all, returns value if no bonuses for this stat exist.
Parameters
value the value, that might be changed by bonuses
function Box getBoundingBox()
Returns Bounding Box for entity, use this if you need exact Bounding Box, e.g. for collision detection when entities are close to each other.
function Sphere getBoundingSphere()
Returns Bounding Sphere for entity. Much faster than Bounding Box, but not as accurate. Use this if you need to check often.
function Captain getCaptain()
function TradingGood, int... getCargo(unsigned int n)
function int getCargoAmount(var name)
Counts all goods of the given type. When given a string, it will match the 'name' property of the goods. When given a TradingGood it will match the exact good.
Parameters
Returns
The number of goods
function table<TradingGood, int> getCargos()
function var getCrewMembers(int profession)
function int... getDamageContributorPlayerFactions()
Lists all players and alliances that contributed damage to the entity
Returns
Indices of all players and alliances that contributed damage to the entity
function int... getDamageContributorPlayers()
Lists all players that contributed damage to the entity
Returns
Indices of all players that contributed damage to the entity
function int... getDamageContributors()
Lists all factions that contributed damage to the entity
Returns
Indices of all factions that contributed damage to the entity
function Box getDockedGroupBoundingBox()
Returns Bounding Box for entity, but enlarged to also fit around all docked objects. Use this if you need exact Bounding Box, e.g. for collision detection when entities are close to each other.
function Sphere getDockedGroupBoundingSphere()
Returns Bounding Box for entity, but enlarged to also fit around all docked objects. Use this if you need exact Bounding Box, e.g. for collision detection when entities are close to each other.
function var getDockingPositions()
Lists all docking positions that the entity has
Returns
A table that contains a key-value pair (id, table) for each dock:
function var getFreeArbitraryTurrets()
function var getFreeArmedTurrets()
function var getFreeUnarmedTurrets()
function BlockPlan getFullPlanCopy()
Returns the plan of the entity. This copies the entire plan, keep that in mind when using plans with large block counts.
Returns
A copy of the plan of the entity
function Material getLowestMineableMaterial()
function var, var getMalusFactor()
function Material getMineableMaterial()
function int... getMineableResources()
function int getMoneyLootAmount()
function BlockPlan getMovePlan()
Returns the plan of the entity. This function will move the plan out of the entity, and replace the entity's plan with a single block. This operation is independent of the size of the plan, use it when you have to get large plans with lots of blocks.
Returns
The plan of the entity
function var getNearestDistance(Entity other)
function var getNumArmedTurrets()
function var getNumMiningTurrets()
function var getNumSalvagingTurrets()
function var getNumUnarmedTurrets()
function int... getPilotIndices()
Returns Indices of piloting players
Returns
multiple return values: indices of players
function var getPlanMoneyValue()
function double... getPlanResourceValue()
function int getResourceLootAmount()
function table<int, string> getScripts()
function table<string, string> getTitleArguments()
Retrieves the arguments to a title
function NamedFormat getTitleFormat()
Retrieves the title as NamedFormat
function Entity getTurret(int index)
function Matrix, int... getTurretPositions(TurretTemplate turret, int number)
function Matrix, int... getTurretPositionsLineOfSight(TurretTemplate turret, int number)
function Entity... getTurrets()
function var getTurretSize()
function var getTurretTemplateSize()
function var getTurretTurningSpeed()
function var getUndamagedPlanMoneyValue()
function double... getUndamagedPlanResourceValue()
function var getValue(string key)
Retrieves a custom value saved in the entity with the given key
Parameters
Returns
The value if the key exists, otherwise nil
function table<string, var> getValues()
Retrieves all key-value pairs of custom values of the entity
Returns
A table containing all custom key-value pairs
function bool hasComponent(int type)
function var hasScript(string name)
function var heal(float damage, int index, vec3 location, Uuid inflictorID)
Increases durability of the plan of the Entity
Parameters
index Index of the block that will be restored
location vector containing the hit point, if unknown/unnecessary use empty vector
inflictorID Index of the entity that heals
Returns
nothing
function var healShield(double delta)
Increases shield durability by delta
Parameters
Returns
nothing
function var hyperspaceBlocked()
function var inflictDamage(float damage, var damageSource, var damageType, int index, vec3 location, Uuid inflictorId)
Inflicts damage to the plan of the Entity
Parameters
damageSource The source of the damage. Can be Weaponry, Collision, Decay, Torpedo or Arbitrary.
damageType Type of damage received. Damage can be of type Physical, Energy, Electric, Plasma, AntiMatter or Fragments
index Index of the block that will receive the damage
location vector containing the hit point, if unknown / unnecessary use empty vector
inflictorId Index of the entity that caused the damage
Returns
nothing
function var... invokeFunction(var scriptName, string functionName, var... arguments)
Invokes a function in a script of the entity. Use this function to invoke functions from one script in another script. The first return value of the function is an integer indicating whether or not the call was successful. When it was, this integer is followed by the return values of the invoked function.
Parameters
functionName The name of the function that will be executed
arguments An arbitrary list of arguments that will be given to the invoked function
Returns
Returns at least 1 value indicating if the call succeeded:
0 The call was successful. In this case, the return values of the script are returned in addition to the call result, following the call result
1 The call failed because the entity with the specified index does not exist or has no Scripts component
2 The call failed because it came from another sector than the entity is in
3 The call failed because the given script was not found in the entity
4 The call failed because the given function was not found in the script
5 The call failed because the script's state has errors and is invalid
function var isCollectable(Entity entity)
function bool isInDockingArea(Entity other)
function var isInsideShield(vec3 point)
function bool, var isJumpRouteValid(int fromX, int fromY, int toX, int toY)
function var isManned()
function var isTurretAllowed(TurretTemplate ScriptTurretTemplate)
Tests if the maximum number of turrets of this kind is not reached
Parameters
function int jumpPossible(int x, int y)
Tests if the entity can jump to the specified coordinates
Parameters
y The y-coordinates of the target sector
Returns
Returns an error code:
-1 The entity doesn't have a hyperspace drive.
0 The entity can jump.
1 The hyperspace drive needs to recharge.
2 The target sector is too far away.
3 The entity is facing the wrong direction.
4 The hyperspace drive is being jammed.
function var moveBy(vec3 delta)
Teleports entity by vector
Returns
nothing
function int registerCallback(string callbackName, string functionName)
Register a callback in the entity. The callback receiver has to be inside the same sector for the registration to succeed. The callback will be removed if either the entity or the receiver leaves the sector or gets destroyed. Double registration of callbacks doesn't work. When the same callback to the same callback of the same script instance is registered twice, it will still only be called once.
Parameters
functionName The name of the function that will be executed in the script when the callback happens
Returns
0 on success, 1 if the registration failed
function var registerDamage(Uuid shooterId, double damage, DamageSource DamageSource)
Registers artificial damage as if the entity was damaged by the shooter
Parameters
damage The amount of damage inflicted
DamageSource The kind of source for the damage
Returns
nothing
function var removeBonus(int key)
Deletes bonus
Parameters
Returns
nothing
function var removeCargo(var good, int amount)
Removes cargo from the entity. When given a TradingGood, an exact check for that good will be performed. When given a string, only a name check will be performed, and which cargo will be removed first is undefined if there are multiple goods with the same name. An example would be Energy Cells vs. Stolen Energy Cells. The 'name' property is the same, but the 'stolen' property is different.
Parameters
amount The amount of cargo that should be removed. If this is more than there is on the ship, all specified cargo will be removed.
Returns
nothing
function var removeCrew(int number, CrewMan crewman)
function var removeScript(var script)
Returns
nothing
function var removeScriptBonuses()
Deletes all bonuses added by the current script
Returns
nothing
function var resolveScriptPath(string path)
function bool sendCallback()
function var setAccumulatingBlockHealth(bool bool)
If AccumulatingBlockHealth is true, a block needs to take as much damage as would be necessary to destroy all its children before it itself is destroyed. If it is set to false, the entity's blocks will have only their own durability. Set it to false if you want your entity to easily break apart, e.g. for wreckages.
Parameters
Returns
nothing
function var setAimedPosition(int seat, vec3 in)
Returns
nothing
function var setAttachedBlockIndex(int in)
Returns
nothing
function var setCaptain(Captain [or nil] captain)
Returns
nothing
function var setDamageTypeMultiplier(DamageType type, float factor)
Returns
nothing
function var setDropsAttachedTurrets(bool bool)
Sets the entities' ability to drop its attached turrets. If set to true (default) the ship has a chance to drop a turret that's attached to it when it's destroyed. This is only enabled for NPC entities.
Parameters
Returns
nothing
function var setDropsLoot(bool bool)
Sets the entities' ability to drop normal loot. Affects dropping of money, resources, cargo, turrets and upgrades. 'Loot' component is not affected by this.
Parameters
Returns
nothing
function var setMalusFactor(float in, int reason)
Returns
nothing
function var setManned(bool in)
Returns
nothing
function var setMovePlan(BlockPlan plan)
Set the new plan of the entity. The entity will get deleted if the plan is empty. This moves all the data out of the plan that is used as the first argument. The content of the plan given as argument is then undefined, but still valid. It might be empty, it might contain the previous plan. This operation is independent of the size of the plan, use it when you have to set large plans with lots of blocks.
Parameters
Returns
nothing
function var setPlan(BlockPlan plan)
Set the new plan of the entity. The entity will get deleted if the plan is empty. This copies the entire plan that is given as argument, keep that in mind when setting plans with large block counts.
Parameters
Returns
nothing
function var setTitle(string title, string_pair... arguments)
Sets the title that can be used as title in menus
Parameters
arguments Set the string arguments (if format string is used) as vector of string_pair.
Returns
nothing
function var setTitleArguments(string_pair... arguments)
Sets the arguments to a title
Parameters
Returns
nothing
function var setTurretSize(float in)
Returns
nothing
function var setTurretTurningSpeed(float in)
Returns
nothing
function var setValue(string key, var value)
Sets a custom value
Parameters
value The value to save. Must be bool, number, string or nil. If nil is given, the value will be deleted.
function var singleFlyToLocationTick(vec3 location)
Tells the ship to fly to given location, directly and without pathfinding.
Parameters
Returns
nothing
function int unregisterCallback(string callbackName, string functionName)
function var updateProductionCatchingUp(float float)
Simulates production catching up. This is used when ships return from the background simulation. Updates fighter production, academy and cloning.
Parameters
Returns
nothing
function var waitUntilAsyncWorkFinished(var time)
Returns
nothing
Callbacks Alliance [Client] Callbacks Alliance [Server] Callbacks Alliance [Server] Callbacks Entity Callbacks Galaxy Callbacks Player Callbacks Player [Client] Callbacks Sector Callbacks Server Callbacks
Command Entity FactionDatabase PlanGenerator Player Sector Server UsableInventoryItem
Boarding BspTree CargoBay CargoLoot ControlUnit CrewComponent DeletionTimer DirectFlightPhysics DockingClamps DockingParent DockingPositions Durability EnergySystem Engine FighterAI Hangar HyperspaceEngine InteractionText InventoryItemLoot Owner Physics Plan ReadOnlyBoarding ReadOnlyBspTree ReadOnlyCargoBay ReadOnlyControlUnit ReadOnlyCrew ReadOnlyDeletionTimer ReadOnlyEnergySystem ReadOnlyEngine ReadOnlyFighterAI ReadOnlyHangar ReadOnlyHyperspaceEngine ReadOnlyInteractionText ReadOnlyOwner ReadOnlyPhysics ReadOnlyPlan ReadOnlyShipAI ReadOnlyShipSystem ReadOnlyTorpedoAI [Server] [Client] [Server] [Client] ReadOnlyTorpedoAI [Server] [Client] [Server] [Client] ReadOnlyTorpedoLauncher ReadOnlyTurretBases ReadOnlyVelocity ReadOnlyWeapons ReadOnlyWormHole Shield ShipAI ShipSystem StructuralIntegrity SystemUpgradeLoot Thrusters Torpedo TorpedoAI TorpedoLauncher Turret TurretAI TurretBases Velocity Weapons WormHole
AllianceMember AllianceRank BlockPlan BlockPlanBlock BlockStatistics Box Captain Color ControlUnitSeat CraftDesign CraftStatsOverview Crew CrewMan CrewProfession DebugInfo dvec2 dvec3 dvec4 Entity EntityDescriptor FighterTemplate Format GameSettings Group HighResolutionTimer Inventory InventoryTurret ivec2 ivec3 ivec4 Language Mail Material Matrix ModManager NamedFormat PlanBspTree PlanetSpecifics PlanGenerationStage PlanPart PlanStyle PlayerId PluralForm Profiler QuadTree Random Rarity Ray ReadOnlyEntity Rect Relation Scenario SectorView Seed Sphere Squad SystemUpgradeTemplate Timer Tooltip TooltipLine TorpedoShaft TorpedoTemplate TradingGood TurretDesign TurretDesignPart TurretTemplate UsableInventoryItem Uuid VanillaInventoryItem vec2 vec3 vec4 Version Weapon
EntityIcon EntityTooltip PlanMesh ReadOnlyIcon ReadOnlyPlanMesh ReadOnlyScriptUI ReadOnlyTooltip ScriptUI
Achievements Alliance [Client] CameraKeyFrame CaptainSelectionItem Client ClientSettings ColorSelectionItem CraftDesignSelectionItem Faction [Client] Galaxy [Client] GalaxyMap GameInput GlowFX IconSelectionItem InputWindow InventoryReferenceSelectionItem InventorySelectionItem Keyboard LaserFX Mouse Music PixelIconSelectionItem Planet Player [Client] PlayerWindow RefractionFX Sector [Client] SelectionItem ShipDatabaseEntry [Client] SoundSource StrategyState TargetIndicator TooltipRenderer TurretDesignSelectionItem
AllianceEmblem AllianceTab ArrowLine Button [Client] [Client] Button [Client] [Client] CaptainIcon CaptainProfile CheckBox ComboBox ContextMenu CraftPortrait CrewBar Frame Hud InventorySelection Label Line ListBox ListBoxEx MapArrowLine MapIcon MultiLineTextBox NumbersBar Picture PlanDisplayer ProgressBar SavedDesignsSelection ScrollFrame Selection ShipWindow Slider StatisticsBar Tab TabbedWindow TextBox TextField TooltipDisplayer Tree UIArbitraryHorizontalSplitter UIArbitraryVerticalSplitter UIContainer UIElement UIGridSplitter UIHorizontalLister UIHorizontalMultiSplitter UIHorizontalSplitter UIOrganizer UIRect UIRenderer UIVerticalLister UIVerticalMultiSplitter UIVerticalSplitter ValueComboBox Window
EntityTransferrer FighterController Loot ReadOnlyEntityTransferrer ReadOnlyFighterController ReadOnlyLoot ReadOnlyTurretController ReadOnlyWreckageCreator TurretController WreckageCreator
Alliance [Server] Faction [Server] Galaxy [Server] Player [Server] ReadOnlySector Sector [Server] Server ShipDatabaseEntry [Server]
AIState AlliancePrivilege BeamShape BlockShading BlockStructure BlockType BlockType2 BoxType BuildError CaptainGenderId ChatChannel ChatMessageType ComponentType ControlAction ControlActionBit ControlStyle CoolingType CraftStatsOverviewStat CrewProfessionType CrewRank DamageSource DamageType DeletionType Difficulty EntityArrivalType EntityType FighterOrders FighterStartError FighterType FontType ImpactParticles InventoryItemType JumpError KeyboardKey ListBoxEntryType MalusReason MaterialType MoonType MouseButton PlanetType PlayerStateType ProjectileShape RarityType RelationStatus SavedDesignType ScenarioType SectorChangeType ShipAvailability SoundType StatsBonuses TargetIndicatorVisuals TransformationFeature TurretAutoFireMode TurretSlotType WeaponAppearance WeaponCategory
This is the official documentation for the scripting API of Avorion. This documentation is automatically generated and not necessarily complete. Depending on the context in which functions exist, some documentation such as descriptions, return values or variable names or types may be missing.
Work in Progress. Documentation of Avorion Version: 2.5.7 c8e4beec84f7