# Avorion Script API Documentation

Home Functions Search
Search:

Galaxy [Server] Galaxy
Properties
Member Functions
addScript
addScriptOnce
aiFactionExists
allianceFactionExists
areAllies
areEnemies
callbacksRegistered
changeFactionRelations
createFaction
createRandomFaction
findFaction
findPlayer
getControllingFaction
getFactionRelations
getFactionRelationStatus
getLoadedSectors
getLocalFaction
getMapHomeSectors
getNearestFaction
getOnlinePlayerNames
getPirateFaction
getPlayerNames
getScripts
getSectorView
hasScript
invokeFunction
isCentralFactionArea
isFactionLoaded
isMapFaction
jumpRouteUnobstructed
keepOrGetSector
keepSector
loadSector
playerFactionExists
registerCallback
removeScript
resolveScriptPath
sectorExists
sectorInRift
sectorLoaded
sendCallback
setFactionRelations
setFactionRelationStatus
tryUnloadSector
unregisterCallback

# Galaxy [Server]

This object is only available on the server.

function Galaxy()

Returns

A new instance of Galaxy

function var addScript()

function var addScriptOnce()

function bool aiFactionExists(int index)

function bool allianceFactionExists(int index)

function bool areAllies(int factionA, int factionB)

function bool areEnemies(int factionA, int factionB)

function int callbacksRegistered(string callbackName, var functionName)

Check how many functions are registered to a callback from the current script VM.

Parameters

callbackName The name of the callback
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 changeFactionRelations(Faction a, Faction b, int delta, var notifyA, var notifyB)

Returns

nothing

function Faction createFaction(string name, int x, int y)

Creates a new faction with a specified name and home sector at the given coordinates. Turrets and styles will be generated automatically. If the faction name is already taken, returns the faction with the specified name.

Parameters

name The name of the new faction. Must be unique.
x The x coordinate of the faction's home sector
y The y coordinate of the faction's home sector

Returns

The new faction, or, if already existing, the existing faction

function Faction createRandomFaction(int x, int y)

Creates a new faction with home sector at the given coordinates. Name, turrets and styles will be generated automatically.

Parameters

x The x coordinate of the faction's home sector
y The y coordinate of the faction's home sector

Returns

The new faction

function UserObject findFaction(var identifier)

Looks for a faction with the given name or index. This will not trigger the creation of a new faction. Finding players by name with this method is not possible, since player names can change via Steam. This function returns the correct concrete type of the faction, ie. Faction, Player or Alliance.

Parameters

identifier A string or int, describing the name or index of the faction, respectively

Returns

The faction if found, or nil

function Player findPlayer(string identifier)

Looks for a player with the given name, index or steam ID. Finding players by name with this method is potentially problematic, since player names can change via Steam. It's also possible that 2 players have the same Steam name. Logged in players are preferred when searching by name.

Parameters

identifier A string or int, describing the name, index or Steam ID of the player, respectively. You can pass an int here, even though it says string.

Returns

The player if found, or nil

function Faction getControllingFaction(int x, int y)

Does a lookup on the faction map and retrieves the faction controlling the sector. The faction is determined by the influence of sectors around the sector to check. As sectors are generated while players are exploring, influence over sectors is also only generated while players are exploring. It's very possible that as long as not all sectors near the tested sector have been discovered, the influence is not yet determined nor final.

Parameters

x The x coordinate of the sector
y The y coordinate of the sector

Returns

The faction, or nil if the sector's controller is unknown

function int getFactionRelations(Faction a, Faction b)

function RelationStatus getFactionRelationStatus(Faction a, Faction b)

function table_t getLoadedSectors()

Returns a table containing all loaded sectors. Returned table has format {{x = 12, y = 3}, {x = 4, y = 56}, {x = 78, y = 9}, ...}

Returns

1 if the sector exists, 0 otherwise

function Faction getLocalFaction(int x, int y)

Does a lookup on the faction map and retrieves the faction controlling the given sector. This may trigger a creation of a faction that does not yet exist.

Parameters

x The x coordinate of the sector
y The y coordinate of the sector

Returns

The (new) faction, or nil if the sector is in no man's land

function table<int, vec2> getMapHomeSectors(int x, int y, float radius)

Does a lookup on the faction map and retrieves all factions whose home sectors are inside the radius. Note that only faction-map factions will be returned, factions that are not on the map by default won't be returned, as this is essentially a faction map look up.

Parameters

x The x coordinate of the circle center
y The y coordinate of the circle center
radius The radius of the circle

Returns

A table<int, vec2> containing faction indices and corresponding home sector

function Faction getNearestFaction(int x, int y)

Does a lookup on the faction map and retrieves the nearest faction to the given sector. Distance is calculated by the factions' home sector. This may trigger a creation of a faction that does not yet exist.

Parameters

x The x coordinate of the sector
y The y coordinate of the sector

Returns

The (new) faction, or nil if the sector is in no man's land

function string... getOnlinePlayerNames()

function Faction getPirateFaction(int level)

function string... getPlayerNames()

function table<int, string> getScripts()

function SectorView getSectorView(int x, int y)

function var hasScript(string name)

function var... invokeFunction(var scriptName, string functionName, var... arguments)

Invokes a function in a script of the galaxy. 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. Access to Galaxy scripts is synchronized, so only one thread can invoke functions at a time.

Parameters

scriptName The name or index of the script containing the function
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.
3 The call failed because the given script was not found
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 bool isCentralFactionArea(int x, int y, var factionIndex)

Returns whether the given sector is in the central part of the faction area of the given faction

Parameters

x The x coordinate of the sector
y The y coordinate of the sector
factionIndex The faction to check or nil to use the nearest faction

Returns

A bool indicating whether the given sector is in the central faction area

function bool isFactionLoaded(var identifier)

Checks if a faction is already loaded into memory.

Parameters

identifier A string or int, describing the name or index of the faction, respectively

Returns

A bool indicating the faction being in memory

function bool isMapFaction(int index)

function bool jumpRouteUnobstructed(int fromX, int fromY, int toX, int toY)

Checks if the jump between two sectors is unobstructed by rifts

Parameters

fromX The x coordinate of the first sector
fromY The y coordinate of the first sector
toX The x coordinate of the second sector
toY The y coordinate of the second sector

function bool keepOrGetSector(int x, int y, float time, var code, var... arguments)

Tells the galaxy load a sector or to keep an already loaded sector in memory for the next X seconds, where X is the value configured as [sectorUpdateTimeLimit] in the server.ini. The sector will stay loaded for at least the next 3 frames. Sectors that are loaded are simulated. Use this function with caution, sectors take a lot of memory and CPU performance while loaded. It is not possible to keep all sectors of a galaxy loaded at the same time.

Parameters

x The x coordinate of the sector
y The y coordinate of the sector
time The amount of time the sector is to be kept in memory. If 0, sector will be kept for at least 3 frames.
code Code that will be run immediately on creation of the sector, must have at least one 'init()' function defined that will be run
arguments The arguments that will be passed to the function

Returns

true if the sector is in memory, false otherwise

function bool keepSector(int x, int y, float time)

Tells the galaxy to keep an already loaded sector in memory for the next X seconds, where X is the value configured as [sectorUpdateTimeLimit] in the server.ini. The sector will stay loaded for at least the next 3 frames. This has no effect if the sector is not currently in memory. Sectors that are loaded are simulated. Use this function with caution, sectors take a lot of memory and CPU performance while loaded. It is not possible to keep all sectors of a galaxy loaded at the same time.

Parameters

x The x coordinate of the sector
y The y coordinate of the sector
time The amount of time the sector is to be kept in memory. If 0, sector will be kept for at least 3 frames.

Returns

true if the sector is in memory, false otherwise

function var loadSector(int x, int y)

Tells the galaxy to load an unloaded sector from disk to memory. If the sector is not existant on disk, the sector will be generated. The sector will also be written to disk when it is unloaded, and won't be affected by patches that change the procedural generation of sectors. The sector may not be loaded immediately (sectorLoaded() may not return true immediately), as it can take a few seconds to load or generate. The sector will be kept in memory for 15 seconds or at least 3 frames. Sectors that are loaded are simulated. Use this function with caution, sectors take a lot of memory and CPU performance while loaded. It is not possible to keep all sectors of a galaxy loaded at the same time.

Parameters

x The x coordinate of the sector
y The y coordinate of the sector

Returns

nothing

function bool playerFactionExists(int index)

function int registerCallback(string callbackName, string functionName)

Register a callback in the galaxy. The callback may arrive with a delay. 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.s

Parameters

callbackName The name of the callback
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 removeScript(var script)

Returns

nothing

function var resolveScriptPath(string path)

function bool sectorExists(int x, int y)

Checks if a sector exists. This function checks if the sector exists in the database. The loaded state will not affect the result of this function.

Parameters

x The x coordinate of the sector
y The y coordinate of the sector

Returns

1 if the sector exists, 0 otherwise

function bool sectorInRift(int x, int y)

function bool sectorLoaded(int x, int y)

Checks if a sector is currently loaded in memory. Sectors that are loaded are simulated.

Parameters

x The x coordinate of the sector
y The y coordinate of the sector

Returns

1 if the sector exists, 0 otherwise

function var sendCallback()

Returns

nothing

function var setFactionRelations(Faction a, Faction b, int level, var notifyA, var notifyB)

Returns

nothing

function var setFactionRelationStatus(Faction a, Faction b, RelationStatus status, var notifyA, var notifyB)

Returns

nothing

function bool tryUnloadSector(int x, int y)

Tells the galaxy to unload a loaded sector from memory as soon as possible. The sector will only be unloaded if it's not accessed or kept alive from somewhere else in the next 5 ticks. Sectors that are loaded are simulated.

Parameters

x The x coordinate of the sector
y The y coordinate of the sector

Returns

true if the sector is in memory, false otherwise

function int unregisterCallback(string callbackName, string functionName)

Overview
Home Functions Search
Search:
Callbacks
Callbacks Alliance [Client] Callbacks Alliance [Server] Callbacks Alliance [Server] Callbacks Entity Callbacks Galaxy Callbacks Player Callbacks Player [Client] Callbacks Sector Callbacks Server Callbacks
Predefined Functions & Example Scripts
Command Entity FactionDatabase PlanGenerator Player Sector Server UsableInventoryItem
Common Components
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
Common Objects
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
Client Components
EntityIcon EntityTooltip PlanMesh ReadOnlyIcon ReadOnlyPlanMesh ReadOnlyScriptUI ReadOnlyTooltip ScriptUI
Client Objects
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
Client UI Objects
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
Server Components
EntityTransferrer FighterController Loot ReadOnlyEntityTransferrer ReadOnlyFighterController ReadOnlyLoot ReadOnlyTurretController ReadOnlyWreckageCreator TurretController WreckageCreator
Server Objects
Alliance [Server] Faction [Server] Galaxy [Server] Player [Server] ReadOnlySector Sector [Server] Server ShipDatabaseEntry [Server]
Enums
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 PlanTypeFilter 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.8 a0d3f0b5b065