AI Python API

From FreeOrionWiki

FreeOrion provides an embedded Python interface for writing AI scripts to determine AI behaviours. Python scripts can be easily modified and used without need to recompile the AI executable. This page provides (or will provide) an overview of FreeOrion AI Python scripting and a reference for the FreeOrion AI Python interface.

FreeOrion AI scripts work by acting like a player: examining the gamestate, deciding on strategies, and issuing orders... essentially playing the game just like a player, except without a GUI. The AI script can't directly modify the game universe by creating buildings or planets or ships from nothing, as these are not powers available to any player. If the AI wants a new ship, it needs to order its production and wait for it to complete, just like a player. Similarly, the AI client is given the same information that any player, human or AI, receives about the gamestate, based on what ships, planets, system, etc. that the player's empire knows about. AIs play by the same rules as human players.

The FreeOrion AI interface provides functions and classes to access the known game Universe and its contents, Empires and player information, as well as functions to issue orders and for logging or debug purposes. (Essentially) all these functions and classes are exposed to Python in the freeOrionAIInterface module, which can be imported into Python scripts executed by the FreeOrion AI executable.

Contents 1 Scripting Structure 2 freeOrionAIInterface 3 Logging 4 Free Functions 5 Classes 5.1 Universe 5.1.1 Properties 5.1.2 Functions 5.2 UniverseObject 5.2.1 Properties 5.2.2 Functions 5.3 Fleet 5.3.1 Properties 5.4 Ship 5.4.1 Properties 5.5 ShipDesign 5.5.1 Properties 5.5.2 Functions 5.6 PartType 5.6.1 Properties 5.6.2 Functions 5.7 HullType 5.7.1 Properties 5.7.1.1 Functions 5.8 Building 5.8.1 Properties 5.9 BuildingType 5.9.1 Properties 5.9.2 Functions 5.10 ResourceCenter 5.10.1 Properties 5.11 PopCenter 5.11.1 Properties 5.12 Planet 5.12.1 Properties 5.13 System 5.13.1 Properties 5.13.2 Functions 5.14 Special 5.14.1 Properties 5.15 Species 5.15.1 Properties 5.16 Empire 5.16.1 Properties 5.16.2 Functions 5.17 ResearchQueue 5.18 ResearchQueueElement 5.19 ProductionQueue 5.20 ProductionQueueElement 5.20.1 Properties 5.21 Tech 6 Enumerations 6.1 starType 6.2 planetSize 6.3 planetType 6.4 planetEnvironment 6.5 techType 6.6 techStatus 6.7 buildType 6.8 resourceType 6.9 meterType 6.10 captureResult 6.11 shipSlotType 6.12 shipPartClass 7 STL Containers 7.1 IntSet and StringSet 7.2 IntVec and StringVec

Scripting Structure

The FreeOrion AI executable looks for an AI script file:

/default/AI/FreeOrionAI.py

This main AI script file must contain the following Python functions for the FreeOrion AI client to execute properly:

• initFreeOrionAI() - Called when the AI client is first started. Doesn't need to do anything.

• startNewGame() - Called when a new game is started (but not when a game is loaded). Should clear any pre-existing AI state and set up whatever the AI script needs to generate orders.

• resumeLoadedGame(savedStateString) - Called when a saved game is loaded. The savedStateString (string) parameter will contain AI state information from when the game was saved, and this information should be extracted now so that the AI script can resume from where it was when the game was saved. If a script does not need to restore state information, resumeLoadedGame() can do nothing.

• prepareForSave() - Called when the game is about to be saved. The AI script should compact any state information it wishes to retain when a game is later loaded into a single string (This can be done using Python's pickle library). The setSaveStateString() function is used to set the save state string, and should be called within prepareForSave(). If a script does not need to save state information, prepareForSave() can do nothing.

• handleChatMessage(senderID, messageText) - Called when this player receives a text message. The AI script can reply using the sendChatMessage() function, or can ignore the message. senderID (int) is the player ID of the player who send the message, and messageText (string) is the text of the sent message.

• generateOrders() - Called once per turn to tell the AI script that it should generate and issue orders for the current turn. Within this function the doneTurn() function should be called to indicate that the script is done issuing orders for this turn. Not calling doneTurn() within generateOrders() or within another function called by generateOrders() will cause the FreeOrion server to wait indefinitely for the AI's turn to complete.

freeOrionAIInterface

Within FreeOrionAI.py and within any other script files called by it, the freeOrionAIInterface module should be imported:

import freeOrionAIInterface as fo

This module provides all the functions and classes used to access the gamestate that the AI player knows about and all the functions used to issue orders, interact with other players, save game state or to end the AI player's turn. The following functions and classes are all contained within freeOrionAIInterface.

Logging

FreeOrion AI Python scripts are run by the AI executable, which does not have any display or user interface. In order to see error messages or debug output from scripts, the AI executable redirects standard output and error to the AI log file. Any error output that is produced during execution of a script will appear in the FreeOrion AI log file automatically. To generate debug output, simply use the built-in python print command:

print "this will generate debug output"

The printed text will appear in the FreeOrion AI log file. The log files are located in the directory discussed here. The AI log files are name AI_#.log where # is a number such as 1, 2, 3, etc. Each AI player in a game generates a separate log file.

Free Functions

The following functions are exposed to Python in the freeOrionAIInterface module:

• playerName() - Returns the name (string) of this AI player.
• playerName(playerID) - Returns the name (string) of the player with the indicated playerID (int).

• playerID() - Returns the integer id of this AI player.
• empirePlayerID(empireID) - Returns the player ID (int) of the player who is controlling the empire with the indicated empireID (int).
• allPlayerIDs() - Returns an object (intVec) that contains the player IDs of all players in the game.

• playerIsAI(playerID) - Returns true (boolean) if the player with the indicated playerID (int) is controlled by an AI and false (boolean) otherwise.
• playerIsHost(playerID) - Returns true (booean) if the player with the indicated playerID (int) is the host player for the game and false (boolean) otherwise.

• empireID() - Returns the empire ID (int) of this AI player's empire.
• playerEmpireID(playerID) - Returns the empire ID (int) of the player with the specified player ID (int).
• allEmpireIDs() - Returns an object (intVec) that contains the empire IDs of all empires in the game.
• getEmpire() - Returns the empire object (Empire) of this AI player
• getEmpire(empireID) - Returns the empire object (Empire) with the specified empire ID (int)

• getUniverse() - Returns the universe object (Universe)
• validShipDesign(hull, parts) - Returns true (boolean) if the passed hull (string) and parts (StringVec) make up a valid ship design, and false (boolean) otherwise. Valid ship designs don't have any parts in slots that can't accept that type of part, and contain only hulls and parts that exist (and may also need to contain the correct number of parts - this needs to be verified).
• validShipDesign(shipDesign) - Returns true (boolean) if the passed ship design (ShipDesign) is valid, and false otherwise.
• getShipDesign(id) - Returns the ship design (ShipDesign) with the indicated id number (int).
• getPartType(name) - Returns the ship part (PartType) with the indicated name (string).
• getHullType(name) - Returns the ship hull (HullType) with the indicated name (string).
• getBuildingType(name) - Returns the building type (BuildingType) with the indicated name (string).
• getSpecial(name) - Returns the special (Special) with the indicated name (string).
• getSpecies(name) - Returns the species (Species) with the indicated name (string).
• getTech(name) - Returns the tech (Tech) with the indicated name (string).
• getTechCategories() - Returns the names of all tech categories (StringVec).
• techs() - Returns the names of all techs (StringVec).
• techsInCategory(name) - Returns the names of all techs (StringVec) in the indicated tech category name (string).

• currentTurn() - Returns the current game turn (int).

• issueFleetMoveOrder(fleetID, destinationID) - Orders the fleet with indicated fleetID (int) to move to the system with the indicated destinationID (int). Returns 1 (int) on success or 0 (int) on failure due to not finding the indicated fleet or system.
• issueRenameOrder(objectID, name) - Orders the renaming of the object with indicated objectID (int) to the new indicated name (string). Returns 1 (int) on success or 0 (int) on failure due to this AI player not being able to rename the indicated object (which this player must fully own, and which must be a fleet, ship or planet).
• issueScrapOrder(objectID) - Orders the ship or building with the indicated objectID (int) to be scrapped. Returns 1 (int) on success or 0 (int) on failure due to not finding a ship or building with the indicated ID, or if the indicated ship or building is not owned by this AI client's empire.
• issueNewFleetOrder(name, shipIDs) - Orders a new fleet to be created with the indicated name (string) and containing the indicated shipIDs (IntVec). The ships must be located in the same system and must all be owned by this player. Returns 1 (int) on success or 0 (int) on failure due to one of the noted conditions not being met.
• issueFleetTransferOrder(shipID, newFleetID) - Orders the ship with ID shipID (int) to be transferred to the fleet with ID newFleetID. Returns 1 (int) on success, or 0 (int) on failure due to not finding the fleet or ship, or the client's empire not owning either, or the two not being in the same system (or either not being in a system) or the ship already being in the fleet.
• issueColonizeOrder(shipID, planetID) - Orders the ship with ID shipID (int) to colonize the planet with ID planetID (int). Returns 1 (int) on success or 0 (int) on failure due to not finding the indicated ship or planet, this client's player not owning the indicated ship, the planet already being colonized, or the planet and ship not being in the same system.
• issueChangeFocusOrder(planetID, focus) - Orders the planet with ID planetID (int) to use focus setting focus (string). Returns 1 (int) on success or 0 (int) on failure if the planet can't be found or isn't owned by this player, or if the specified focus is not valid on the planet.
• issueEnqueueTechOrder(techName, position) - Orders the tech with name techName (string) to be added to the tech queue at position (int) on the queue. Returns 1 (int) on success or 0 (int) on failure if the indicated tech can't be found. Will return 1 (int) but do nothing if the indicated tech can't be enqueued by this player's empire.
• issueDequeueTechOrder(techName) - Orders the tech with name techName (string) to be removed from the queue. Returns 1 (int) on success or 0 (int) on failure if the indicated tech can't be found. Will return 1 (int) but do nothing if the indicated tech isn't on this player's empire's tech queue.
• issueEnqueueBuildingProductionOrder(buildingName, locationID) - Orders the building with name (string) to be added to the production queue at the location of the planet with id locationID. Returns 1 (int) on success or 0 (int) on failure if there is no such building or it is not available to this player's empire, or if the building can't be produced at the specified location.
• issueEnqueueShipProductionOrder(designID, locationID) - Orders the ship design with ID designID (int) to be added to the production queue at the location of the planet with id locationID (int). Returns 1 (int) on success or 0 (int) on failure there is no such ship design or it not available to this player's empire, or if the design can't be produced at the specified location.
• issueRequeueProductionOrder(oldQueueIndex, newQueueIndex) - Orders the item on the production queue at index oldQueueIndex (int) to be moved to index newQueueIndex (int). Returns 1 (int) on success or 0 (int) on failure if the old and new queue indices are equal, if either queue index is less than 0 or greater than the largest indexed item on the queue.
• issueDequeueProductionOrder(queueIndex) - Orders the item on the production queue at index queueIndex (int) to be removed form the production queue. Returns 1 (int) on success or 0 (int) on failure if the queue index is less than 0 or greater than the largest indexed item on the queue.
• IssueCreateShipDesignOrder(name, description, hull, partsVec, graphic, model) - Orders the creation of a new ship design with the name (string), description (string), hull (string), parts vector partsVec (StringVec), graphic (string) and model (string). model should be left as an empty string as of this writing. There is currently no easy way to find the id of the new design, though the client's empire should have the new design after this order is issued successfully. Returns 1 (int) on success or 0 (int) on failure if any of the name, description, hull or graphic are empty strings, if the design is invalid (due to not following number and type of slot requirements for the hull) or if creating the design fails for some reason.

• sendChatMessage(recipientID, message) - Sends the indicated message (string) to the player with the indicated recieipientID (int) or to all players if recipientID is -1.

• setSaveStateString(saveStateString) - Sets the save state string (string). This is a persistant storage space for the AI script to retain state information when the game is saved and reloaded. Any AI state information to be saved should be stored in a single string (likely using Python's pickle module) and stored using this function when the prepareForSave() Python function is called.
• getSaveStateString() - Returns the previously-saved state string (string). Can be used to retreive the last-set save state string at any time, although this string is also passed to the resumeLoadedGame(savedStateString) Python function when a game is loaded, so this function isn't necessary to use if resumeLoadedGame stores the passed string.

• doneTurn() - Ends the AI player's turn, indicating to the server that all orders have been issued and turn processing may commence.

Classes

Universe

SubClasses:
SubClass Of:

The Universe class contains the majority of FreeOrion gamestate: All the UniverseObjects in the game, and all ShipDesigns in the game. (Other gamestate is contained in the Empire class.) The Universe class provides functions with which to access objects in it and information about connections and paths between systems.

Properties

• allObjectIDs - An IntVec containing ids of all objects in the universe.
• fleetIDs - An IntVec containing ids of all Fleets in the universe.
• systemIDs - An IntVec containing ids of all Systems in the universe.
• planetIDs - An IntVec containing ids of all Planets in the universe.
• shipIDs - An IntVec containing ids of all Ships in the universe.
• buildingIDs - An IntVec containing ids of all Buildings in the universe.

Functions

• getObject(id) - Returns the UniverseObject in the universe with the indicated id (int), or None if no object exists with that id.
• getFleet(id) - Returns the Fleet in the universe with the indicated id (int), or None if no fleet exists with that id.
• getShip(id) - Returns the Ship in the universe with the indicated id (int), or None if no ship exists with that id.
• getPlanet(id) - Returns the Planet in the universe with the indicated id (int), or None if no planet exists with that id.
• getSystem(id) - Returns the System in the universe with the indicated id (int), or None if no system exists with that id.
• getBuilding(id) - Returns the Building in the universe with the indicated id (int), or None if no building exists with that id.
• systemHasStarlane(systemID, empireID) - Returns true if the system with ID systemID (int) has at least one starlane to any other system that is known of by the empire with id empireID (int). Returns false otherwise.
• systemsConnected(systemID1, SystemID2, empireID) - Returns true (bool) if the systems with ids systemID1 (int) and systemID2 (int) have a series of starlanes connecting them directly or indirectly via other systems, that is known of by the empire with id empireID (int). Returns false (bool) otherwise.
• updateMeterEstimates() - Recalculates the estimated next-turn meter values of all objects in the universe, taking into account any orders that this player has issued since the start of the current turn. To have object meters updated, this function must be called after issuing any meter-altering orders, including issueChangeFocusOrder.
• leastJumpsPath(systemID1, systemID2, empireID) - Returns a list of system IDs (IntVec) that is the series of starlane jumps between systems with ids systemID1 (int) and systemID2 (int) that takes the fewest jumps (but not necessarily the shortest travel distance / time), as far as the empire with ID empireID (int) knowns. Empires generally don't know what other systems are visible to other empires, so specifying any empireID other than this client's empire's ID probably won't return an accurate result. May return an empty list if no path between the systems exists.
• shortestPath(systemID1, systemID2, empireID) -- Returns a list of system IDs (IntVec) that is the series of starlane jumps between systems with ids systemID1 (int) and systemID2 (int) that is the shortest route (not the same as fewest jumps) as far as the empire with ID empireID (int) knowns. Empires generally don't know what other systems are visible to other empires, so specifying any empireID other than this client's empire's ID probably won't return an accurate result. May return an empty list if no path between the systems exists.
• dump() - Returns a text representation of the objects (string) contained in the Universe. Probably only useful for debugging purposes if output to the log file.

UniverseObject

SubClasses: Fleet, Ship, Building, Planet, System
SubClass Of:

UniverseObject is the base class for all in-game objects, and has all the common properties and functions shared by such objects.

Properties

• id - An internal unique identification number (int) for each object.
• name - The name of an object (string).
• x - The x-coordinate of the object's location in the universe (double).
• y - The y-coordinate of the object's location in the universe (double).
• systemID - The id (int) of the system in which the object is located. May be -1 to indicate the object is not in a system.
• unowned - True (bool) if the object has no owners, false (bool) otherwise.
• owners - The list of empire IDs (IntSet) of empires that own this object. Generally will be only a single empire or no empires, except for systems that may contain multiple empires' planets.
• creationTurn - The turn number (int) on which this object was created. If an object was created before the start of the game, this should be a large negative number.
• ageInTurns - The age in turns (int) of this object. If an object was created before the start of the game, this should be a large negative number.
• specials - A list of names (StringSet) of specials attached to this object.

Functions

• ownedBy(empireID) - Returns true (bool) if this object is owned by the empire with id empireID (int), or false (bool) otherwise.
• whollyOwnedBy(empireID) - Returns true (bool) if this object is owned only by the empire with id empireID (int), or false (bool) otherwise. An object may be owned by more than one empire in cases such as a system that contains planets colonized by more than one empire. In most other situations, objects should have one or zero owners.
• contains(objectID) - Returns true (bool) if this object contains an object with id objectID (int), or false otherwise. Systems can contain planets, ships, fleets, and buildings. Fleets can contain ships. Planets can contain buildings.
• containedBy(objectID) - Returns true (bool) if this object is contained within an object with id objectID (int), or false otherwise.
• currentMeterValue(meterType) - Returns the current value (double) of the meter of this object with type metertype (meterType). This value may change whenever something in the gamestate changes, and then meter estimates are recalculated using the Universe object's updateMeterEstimates() function.
• initialMeterValue - Returns the initial value (double) of the meter of this object with type metertype (meterType). The initial value of a meter is set at the start of a game turn, and won't change until the next turn. The initial value is used for most calculations of changes to other meters or when determining what conditions match objects, so that the order of execution of effects doesn't matter.
• nextTurnCurrentMeterValue -

Fleet

SubClasses:
SubClass Of: UniverseObject

Properties

• fuel - The current fuel (double) available to this fleet, which is the smallest of the fuels on ships in the fleet.
• maxFuel - The maximum fuel (double) capacity of this fleet, which is the smallest of the fuel capacities of ships in the fleet.
• finalDestinationID - The id (int) of the system to which this fleet has been ordered to move. May be -1 to indicate there is no destination.
• previousSystemID - The id (int) of the system from which the fleet most recently departed. May be -1 to indicate there is no previous system.
• nextSystemID - The id (int) of the system to which the fleet is moving next. May return -1 to indicate there is no next system.
• speed - The speed (double) of movement along starlanes for this fleet, which is the smallest of the starlane movement speeds of ships in the fleet. Will be the same value regardless of whether the fleet is currently moving or is stationary.
• canChangeDirectionEnRoute - True (bool) if this fleet can change directions while in the middle of a starlane, or false (bool) otherwise.
• hasArmedShips - True (bool) if this fleet contains one or more ships with weapons, or false (bool) otherwise.
• hasColonyShips - True (bool) if this fleet contains one or more ships with colonists on board that can colonize a planet, or false (bool) otherwise.
• numShips - The number (int) of ships in this fleet.
• empty - True (bool) if this fleet contains no ships, or false (bool) if the fleet contains at least one ship. This might happen in the middle of a turn after ordering a ship transfer between fleets.
• shipIDs - The ids (IntVec) of ships in this fleet.

Ship

SubClasses:
SubClass Of: UniverseObject

Properties

• design - Returns the ShipDesign object (ShipDesign) of this ship.
• designID - The unique (per ShipDesign) ID (int) of this ship's design.
• fleetID - The ID (int) of the fleet (Fleet) containing this ship.
• isArmed - True (bool) if this ship has weapons, false (bool) otherwise.
• canColonize - True (bool) if this ship can colonize planets, false (bool) otherwise.
• speed - The speed (double) that this ship can move along starlanes.

ShipDesign

SubClasses:
SubClass Of:

Properties

• id - A unique ID number (int) for this ShipDesign.
• description - A human-readable text description (string) of this design.
• designedByEmpireID - The ID (int) of the empire that created this ShipDesign.
• designedOnTurn - The turn number (int) when this design was created.
• starlaneSpeed - The distance (double) at which ships of this design can move along starlanes, per turn (unless modified by external effects).
• battleSpeed - The speed (double) at which ships of this design can move during battles (unless modified by external effects).
• defense - The sum (double) of the strengths of the armour and shield parts of this design. Not a particularly useful number, and something that may be removed in future.
• attack - The sum (double) of the strengths of all attack parts on this design.
• canColonize - True (bool) if this design contains a colonization part.
• canInvade" - True (bool) if this designs contains a troop pod part.
• isArmed" - True (bool) if this design has weapon parts.
• isMonster" - True (bool) if this design is a space monster.
• productionCost - The total cost (double) in PP of producing a ship of this design.
• productionTime - The minimum time (int) in turns to produce a ship of this design.
• perTurnCost -
• hull - The name (string) of the hull in this design.
• parts - The names (StringVec) of the parts in this design. Some may be empty strings, to indicate empty slots in the design.

Functions

• name() - Returns the name (string) of this ShipDesign.
• partsInSlotType(slotType) - Returns a list of parts (StringVec) that are placed in slots of the indicated slot type (shipSlotType).
• productionLocationForEmpire() -

Note that there are Free Functions available related to ShipDesign as well: validShipDesign and getShipDesign.

PartType

SubClasses:
SubClass Of:

Properties

• name -
• class -
• productionCost -
• productionTime -

Functions

• canMountInSlotType() -

HullType

SubClasses:
SubClass Of:

Properties

• name -
• numSlots -
• productionCost -
• productionTime -
• slots -

Functions

• numSlotsOfSlotType() -

Building

SubClasses:
SubClass Of: UniverseObject

Properties

• buildingType - Returns the building type object (BuildingType) of this building.
• buildingTypeName - The building type name (string) of this building.
• planetID - The id (int) of the planet on which this buidling is located.

BuildingType

SubClasses:
SubClass Of:

Properties

• name - The name (string) of this building type.
• description - A human-readable text (string) description of this building type.
• productionCost - The total cost (double) in PP to produce a building of this type.
• productionTime - The minimum turns (int) required to produce a building of this type.
• maintenanceCost - The cost (double) per turn in trade to an empire that controls a building of this type.
• perTurnCost -

Functions

• captureResult() -

ResourceCenter

SubClasses: Planet
SubClass Of:

Properties

• Focus - Returns the focus setting (string) to which the resource center is set.
• AvailableFoci - Returns a list (StringVec) of names of focus settings that are available for this resource center.

PopCenter

SubClasses: Planet
SubClass Of:

Properties

• allocatedFood - The amount of food (double) that has been allocated to this PopCenter.
• speciesName - The name (string) of the species on this PopCenter. May be an empty string if no species is on this PopCenter.

Planet

SubClasses:
SubClass Of: UniverseObject, ResourceCenter, PopCenter

Properties

• size - Planet size (planetSize) of planet.
• type - Planet type (planetType) of planet.
• buildingIDs - Ids (IntVec) of IDs of buildings on planet.

System

SubClasses:
SubClass Of: UniverseObject

Properties

• starType - Returns the star type (StarType) of this system.
• numOrbits - Returns the number of orbits (int) in which planets could be located in the system.
• numStarlanes - Returns the number (int) of known starlanes connected to this system.
• numWormholes - Returns the number (int) of known wormholes connected to this system.
• allObjectIDs - IntVec of IDs of objects in this system.
• planetIDs - IntVec of IDs of planets in this system.
• fleetIDs - IntVec of IDs fleets in this system.

Functions

• HasStarlaneToSystemID(systemID) - Returns true (bool) if this system has a known direct starlane connection to the system with the indicated ID, and false (bool) otherwise.
• HasWormholeToSystemID(systemID) - Returns true (bool) if this system has a known direct wormhole connection to the system with the indicated ID, and false (bool) otherwise.

Note that Universe also has the SystemHasStarlane function, which indicates whether a particular system has any starlanes visible to a particular empire.

Special

SubClasses:
SubClass Of:

Properties

• name - Name (string) of this special.
• description - Description (string) of this special.

Species

SubClasses:
SubClass Of:

Properties

• name - Name (string) of this species.
• description - Description (string) of this species.
• homeworlds - The ids (IntSet) of the homeworld planets of this species.

Empire

Subclasses:
Subclass Of:

Properties

• name - The name (string) of this empire.
• playerName - The name (string) of the player controlling this empire.
• empireID - The unique ID number (int) of this empire.
• capitolID - The object ID number (int) of the capitol object (most likely a planet) of this empire.
• availableBuildingTypes - A StringVec of names of building types that are available to this empire.
• availableShipDesigns - An IntVec of design ID numbers of ship designs that are available to this empire.
• productionQueue - Returns the production queue object (ProductionQueue) of this empire.
• availableTechs - A StringVec of names of techs that have been researched by this empire.
• researchQueue - Returns the ResearchQueue object for this empire.
• exploredSystemIDs - An IntSet of ids of systems that this empire has explored.
• productionPoints - The number of production points (double) available to the empire. This is this is the minimum of available industry and available minerals throughout the empire, and may not represent the production points available at any given system.
• fleetSupplyableSystemIDs - An IntSet of ids of systems where this empire can resupply fleets.
• supplyUnobstructedSystems - An IntSet of ids of systems through which this empire cannot propegate resource or fleet supplies. Ships and planets in these systems can't receive or sent fleet supply, and can't exchange resources with other planets. Planets also can't sent supplies through these systems, and must propegate supply lines through other systems.

Functions

• buildingTypeAvailable() -
• shipDesignAvailable() -
• techResearched() -
• getTechStatus() -
• researchStatus() -

• canBuild(buildingTypeName, locationID) - Returns true or false (bool) to indicate whether this empire can produce the building type with the indicated name (string) at the object (most generally a planet) with the indicated locationID (int).
• canBuild(shipDesignID, locationID) - Returns true or false (bool) to indicate whether this empire can produce the ship design with the indicated design ID (int) at the object (most generally a planet) with the indicated locationID (int).

• hasExploredSystem(systemID) - Returns true of false (bool) to indicate whether this empire has explored th system with ID systemID. Returns false if there no such known system.

• resourceStockpile(resouceType) - Returns the amount of the resource of type resourceType that is stockpiled by this empire.
• resourceProduction(resouceType) - Returns the per-turn output of resource of type resouceType by objects owned by this empire.
• resourceAvailable(resouceType) - Returns the amount of the resource of the type resouceType available on this turn to this empire. This is the total per-turn output by the empire added to the stockpiled amount. This may not actually be available at any given planet owned by the empire, due to limits on resource sharing between planets or systems.

• population() - The total population (double) of objects (mostly planets) controlled by this empire. (No particular reason this is not a property.)

ResearchQueue

Subclasses:
Subclass Of:

• researchQueue() -
• __iter__() -
• __getitem__() -
• __len__() -
• size() -
• empty() -
• inQueue() -
• inQueue() -
• __contains__() -
• totalSpent() -

ResearchQueueElement

Subclasses:
Subclass Of:

• tech() -
• spending() -
• turnsLeft() -

ProductionQueue

Subclasses:
Subclass Of:

• productionQueue() -
• __iter__() -
• __getitem__() -
• __len__() -
• size() -
• empty() -
• totalSpent() -

ProductionQueueElement

Subclasses:
Subclass Of:

Properties

• name - The name (string) of the building type being produced as this queue element. May be an emptry string to indicate that no valid building type is being produced, such as when this element actually represents a ship being produced.
• designID - The ID (int) of the ship design being produced as this queue element. May be -1 to indicate no valid ship design is being produced, such as when this element actually represents a building being produced.
• buildType - buildType of item on queue.

• locationID - The ID number (int) where this production queue element is being produced.
• spending - The number of production points (double) allocated to this queue element this turn.
• turnsLeft - The estimated number of turns (int) left until this producion queue element is completed and is produced.

Tech

Subclasses:
Subclass Of:

• tech() -
• name() -
• description() -
• shortDescription() -
• type() -
• category() -
• researchCost() -
• researchTime() -
• prerequisites() -
• unlockedTechs() -

Enumerations

starType

• blue -
• white -
• yellow -
• orange -
• red -
• neutron -
• blackHole -

planetSize

• tiny -
• small -
• medium -
• large -
• huge -
• asteroids -
• gasGiant -

planetType

• swamp -
• radiated -
• toxic -
• inferno -
• barren -
• tundra -
• desert -
• terran -
• ocean -
• asteroids -
• gasGiant -

planetEnvironment

• uninhabitable -
• hostile -
• poor -
• adequate -
• good -

techType

• theory -
• application -
• refinement -

techStatus

• unresearchable -
• researchable -
• complete -

buildType

• building -
• ship -

resourceType

• food -
• minerals -
• industry -
• trade -
• research -

meterType

• population - Population of a planet. Usually used to influence resource output.
• targetPopulation - Stable population of a planet. When less, population will generally increase towards target population. When more, population will generally decrease.
• health - Health of a planet. Generally determines the rate of increase or decrease of population. When below 20, population will always decrease.
• targetHealth - Stable health of a planet. Like population and target population, health moves towards target health.
• farming - Food output per turn of a planet.
• targetFarming - Value towards which food meter moves each turn.
• industry - Industry output per turn of a planet.
• targetIndustry - Industry moves towards this value.
• research - Research output per turn of a planet.
• targetResearch - Research moves towards this value.
• trade - Trade output per turn of a planet.
• targetTrade - Trade moves towards this value.
• mining - Minerals output of a planet.
• targetMining - Mining moves towards this value.
• construction - Determines distance away planets can share / pool resource output of minearals, food and insdustry.
• targetConstruction - Construction moves towards this value.
• fuel - Number of starlane jumps a ship can make. Always refilled each turn when within fleet supply distance of a planet.
• maxFuel - Maximum value fuel meter can have.
• shield - Used in combat to absorb damage.
• maxShield - Maximum value of shield meter.
• structure - Tracks damage to ships. Structure of 0 destroys a ship.
• maxStructure - Max value structure meter can have.
• defense - Used to determine planets' combat strength.
• maxDefense - Max value of defense meter.
• foodConsumption - Determines how much food a planet needs each turn to maintain its population.
• supply - How many starlane jumps away a planet can resupply ships' fuel and ammunition.
• stealth - Reduces the distance away that detection of an object is possible. Interacts with detection meter.
• detection - The distance away that another object of stealth (just above) 0 can be detected by an object owned by an empire. Stealth 0 objects can always be seen, but anything with nonzero stealth needs to be within the detection range of an object to be seen by an empire that does not own the detected object.
• battleSpeed - How fast per combat turn a ship moves.
• starlaneSpeed - How far per game turn a ship moves along starlanes.

captureResult

• capture -
• destroy -
• retain -
• share -

shipSlotType

• external -
• internal -

shipPartClass

• shortRange -
• missiles -
• fighters -
• pointDefense -
• shields -
• armour -
• detection -
• stealth -
• fuel -
• colony -
• battleSpeed -
• starlaneSpeed -

STL Containers

Two types of C++ Standard Template Library (STL) containers are returned by FreeOrion Python AI interface functions: set and vector. Both set and vector may be returned containing integers or strings. All four combinations (integer set, integer vector, string set, string vector) are treated as separate classes in Python. All have been exposed to Python, and may be iterated over and treated like normal Python containers: C++ sets act similarly to Python frozenset and C++ vectors act similarly to Python lists.

IntSet and StringSet

Both specializations of C++ set act similarly to a Python frozenset containing a single type of object (int or string, respectively). The following functions are defined:

• __str__() - Returns a string representation of the set. Usage: "str(setObject)"
• __len__() - Returns the length (int) of the set. Usage: "len(setObject)"
• size() - Returns the length (int) of the set. Usage: "setObject.size()"
• empty() - Returns true (boolean) if the set is empty, or false (boolean) if the set contains at least one int or string. Usage: "setObject.empty()"
• __contains__(item) - Returns true (boolean) if the set contains item (int or string). Usage: "item in SetObject"

• count(item) - Returns the number (int) of item (int or string) held in the set.
• __iter__ - Returns a Python iterator object for the set, pointing to the first element in the set. Allows iteration over the contents of the set in Python: "for item in setObject: ..."

IntVec and StringVec

Both specializations of C++ vector act similarly to a Python list containing a single type of object (int or string, respectively). The following functions are defined:

• __len__() - Returns the length (int) of the vector. Usage: "len(vectorObject)"
• __getitem__(key) - Returns the item (int or string) with index key (int) in the vector. Indices range from 0 to len(vectorObject) - 1. Indices can also be specified as a negative integer, which counts backwards from the end of the vector. Usage: "vectorObject[5]" or "vectorObject[-8:-2]"
• __iter__() - Returns a Python iterator object for the vector, pointing to the first element in the vector. Allows iteration over the contents of the vector in Python: "for item in vectorObject: ..."
• __contains__(item) - Returns true if the indicated item (int or string) is contained in the vector, and false otherwise. Usage: "23 in intVecObject"
• __setitem__(key, item) - Sets the item with indicated key (int) equal to the indicated item (int or string). Usage: "intVecObject[23] = 52" or "stringVecObject[2] = 'example string'" or "intVecObject[:] = [1, 2, 4, 10, 8]"
• __delitem__(key) - Removes the item with indicated key (int) from the vector, shifting higher-keyed items back to compensate. Usage: "del intVecObject[2]" or "del intVecObject[-4:-1]"
• IntVec and StringVec may also be created as new objects in Python, which is useful when a function requires one as input. Usage: "vecObject = IntVec()"