Perceptual Tokens Reference

Parameters
Parameter tokens go inside { } after the main token to limit the scope of the token further.

Used to limit scope of "final literals"

		GameObjectCategoryType or AIGoalCategoryType restriction

		Scales returned value of final literal?

		GameObjectType e.g. actual unit or planet name

		HardPointType e.g. Shield_Generator

		Faction e.g. "Empire"

		For "leveled" objects (starbases)

		Number of objects

		Name of story trigger event

<Parameter_Queue_Type>	</Parameter_Queue_Type>	Unused, presumably limits scope of build queue perceptions

<Parameter_Script_String>	</Parameter_Script_String>	Sends a string variable to the Evaluate function in an Evaluator script

<Parameter_Script_Number>	</Parameter_Script_Number>	Same as above, except can be float

<Parameter_Range>	</Parameter_Range>	Unused. Possibly weapon/unit attack range?

<Parameter_Only_Consider_Complete></Parameter_Only_Consider_Complete>	When counting GameObjectTypes, this can be used to only count completed objects

<Parameter_Time>	</Parameter_Time>	A maximum amount of time within which a perception has fired? Used with HasTakenDamage

<Parameter_Difficulty_Level_Type></Parameter_Difficulty_Level_Type>	DifficultyLevelType restriction e.g. Easy

Literals
"Literals" are tokens that control other tokens, similar to that of Variables.

<Game>	</Game>	Game-level perceptions e.g. Age, PlanetsCorrupted

<Type>	</Type>	Used with IsType to find specific individual GameObjectType, or Token to find a specific token

<FriendlyForce> </FriendlyForce>	Limits to friendly forces

<EnemyForce>	</EnemyForce>	Limits to enemy forces

<Hints>	</Hints>	Pulls from GC hint XML

<Evaluate>	</Evaluate>	Returns the value from a perception (Function_Perception_Name.Evaluate) or a script (Script_Script_Name.Evaluate)

<Token>	</Token>	Returns the token value of a GameObject (only used for home planet detection)

Here and down are Game literals. This one should return the "Timeline" measure but the functionality was probably cut

<Markup>	</Markup>	This one isn't Game, but reads from a Lua Markup table giving planets bonuses (PathToDistantTarget)

<Age>	</Age>	Time in seconds since game start

<IsCampaignGame>	</IsCampaignGame>	Returns 1 if the game is a GC

<InterventionsEnabled>	</InterventionsEnabled>	Returns 1 if Intervention missions are enabled

<TimeSinceStoryPopup>	</TimeSinceStoryPopup>	Time in seconds since last time the story box was opened

<ActiveStoryGoalCount>	</ActiveStoryGoalCount>	Total number of goals player has in mission holocron

<IsStoryCampaign>	</IsStoryCampaign>	Returns 1 if the game type is the main story campaign (not a basic GC)

<PlanetsCorrupted>	</PlanetsCorrupted>	Total number of planets corrupted normalized by total planets (so 0-1 range)

<PlanetsCorruptedUnnormalized>	</PlanetsCorruptedUnnormalized>	Total number of planets corrupted

Planets
Used for GC-based planet evaluation. Must be called after Variable_Target when Target is a planet.

<TargetPoliticalControl>	</TargetPoliticalControl>	Unclear- should return 1 if evaluating PlayerObject owns the planet

<StarbaseLevel>	</StarbaseLevel>	Returns level of starbase at planet normalized to a max of 5

<GroundbaseLevel>	</GroundbaseLevel>	Returns "level" of groundbase on planet (can be more than 0-5), normalized to max of 5

<DistanceToNearestFriendly> </DistanceToNearestFriendly>	Distance in game map units to the nearest friendly GameObject NOT PLANET BASED!

<OpenStructureSlots>	</OpenStructureSlots>	TOTAL special structure slots available at a planet, normalized by ground + space total

<IsConnectedTo>	</IsConnectedTo>	Returns based on connected planet parameters (probably always returns 1 if there is any connection at all)

<FriendlyInternalConnectivity>	</FriendlyInternalConnectivity>	Possibly the level of internal cohesion of friendly planets

<FriendlyExternalConnectivity>	</FriendlyExternalConnectivity>	Possibly the number of external connections of friendly planets

<EnemyInternalConnectivity>	</EnemyInternalConnectivity>	Same as above but enemy

<EnemyExternalConnectivity>	</EnemyExternalConnectivity>	Same as above but enemy

<Income>	</Income>	Unused. Probably total planet income normalized to highest earning planet

<IncomeNBPTM>	</IncomeNBPTM>	Same as above but normalized by "per target max" where the target is probably a planet?

<IncomeNBTP>	</IncomeNBTP>	Income normalized by target planet OR total planets (probably target)

<IncomeNBTD>	</IncomeNBTD>	Income normalized by target disposition i.e. by allied targets only

<BaseIncome>	</BaseIncome>	Same as above but the raw income unmodified by mining facilities etc

<BaseIncomeNBTP>	</BaseIncomeNBTP>	See above

<BaseIncomeNBTD>	</BaseIncomeNBTD>	See above

<TradeRoutes>	</TradeRoutes>	Number of trade routes connected to a planet normalized by something?

<ActiveTradeRoutes>	</ActiveTradeRoutes>	Number of trade routes connected to a planet that provide income (i.e. friendly) normalized to the total number of connections to that planet

<IsSurfaceAccessible>	</IsSurfaceAccessible>	Are there ground company slots (i.e. not an asteroid field)

<RetainsResidualInfluence>	</RetainsResidualInfluence>	Old political control system

<IsCorrupted>	</IsCorrupted>	Is the planet corrupted? 1 if true

<IsCorruptionTransitionActive>	</IsCorruptionTransitionActive>	Is the planet being corrupted? 1 if true

<IsConnectedToCorruption>	</IsConnectedToCorruption>	Is the planet connected to another corrupted planet? 1 if true

<BlackMarketAbilitiesAvailable>	</BlackMarketAbilitiesAvailable>	Returns 1 if there are black market upgrades to buy at a location

<BlackMarketMinimumAbilityPrice>	</BlackMarketMinimumAbilityPrice>	Returns the minimum price in credits of a black market purchase at a location

<BlackMarketPriceModifier>	</BlackMarketPriceModifier>	The multiplier to black market prices at a specific planet

<TimeSinceCorruptionChange>	</TimeSinceCorruptionChange>	Time in seconds since a planet gained or lost corruption

<MaxStarbaseLevel>	</MaxStarbaseLevel>	Max starbase level at a planet normalized to a max of 5

<MaxGroundbaseLevel>	</MaxGroundbaseLevel>	Max groundbase level at a planet (equal to special structure slots), normalized to a max of 5

<ForceAlignment>	</ForceAlignment>	Unused, presumably returns dark or light force alignment of a planet

<MaxStructureSlots>	</MaxStructureSlots>	Max number of special structures space + ground, normalized to something

<IsType>	</IsType>	Compares to parameter_type string and returns 1 if true

<IsFaction>	</IsFaction>	Compares to parameter_faction string and returns 1 if true

<IsNamedHero>	</IsNamedHero>	Checks to see if a unit is a Named Hero

<ConnectsIsolatedPlanetsByLength>	</ConnectsIsolatedPlanetsByLength>	Unused. Presumably returns 1 if the target planet connects two groups of PlayerObject planets that are furthest away

<ConnectsIsolatedPlanetsByForce>	</ConnectsIsolatedPlanetsByForce>	Returns 1 if the target planet connects two groups of PlayerObject planets with high combat power amount

<ConnectsLargestIslands>	</ConnectsLargestIslands>	Returns 1 if the target planet connects two groups of PlayerObject planets that are the largest groups (i.e. most number of planets)

<HasCreditSiphon>	</HasCreditSiphon>	Returns 1 if the target planet has a smuggler is present siphoning credits

<HasStructure>	</HasStructure>	Returns 1 if the target planet has a structure (usually scoped using Parameter_Type)

<HasIndigenousUnits>	</HasIndigenousUnits>	Returns 1 if the target planet has indigenous units specified

<IsHumanControlled>	</IsHumanControlled>	Returns 1 if the human player controls the planet

Force, Misc
Here, Force refers to the AI Combat Power of a TaskForce of units.

As in, EnemyForce or FriendlyForce

<GroundTotal>	</GroundTotal>	Total ground forces at target planet (summed AI combat power) normalized to largest total ground force.

<SpaceTotal>	</SpaceTotal>	Same as above but for space

<NearbyGroundTotal>	</NearbyGroundTotal>	Same as above but returns values for systems one connection away

<NearbySpaceTotal>	</NearbySpaceTotal>	Same as above

<AntiStealthEffectiveness>	</AntiStealthEffectiveness>	Returns 1 if the enemy force can detect stealth units

<HasNearbyGroundForce>	</HasNearbyGroundForce>	Unused. Presumably returns 1 if an enemy or friendly force has any nearby ground force at all.

<HasNearbySpaceForce>	</HasNearbySpaceForce>	Same as above

Normalized relative to allied targets

<GroundTotalNBTD>	</GroundTotalNBTD>	See above section, with different normalizations

<SpaceTotalNBTD>	</SpaceTotalNBTD>

Normalized by max for the entire galaxy

<GroundTotalNBPTM>	</GroundTotalNBPTM>

<SpaceTotalNBPTM>	</SpaceTotalNBPTM>

Normalized by the total at the target

<GroundTotalNBTT>	</GroundTotalNBTT>

<SpaceTotalNBTT>	</SpaceTotalNBTT>

<HasSpaceForce>	</HasSpaceForce>

<HasGroundForce>	</HasGroundForce>

<Maintenance>	</Maintenance>

<TechLevel>	</TechLevel>	Called from Variable_Self or Variable_Human. Returns unnormalized tech level value

<GrossIncomeNBPTM>	</GrossIncomeNBPTM>

<NetIncomeNBPTM>	</NetIncomeNBPTM>

<GrossIncomeNBTF>	</GrossIncomeNBTF>

<NetIncomeNBTF>	</NetIncomeNBTF>

<BuildQueueDepth>	</BuildQueueDepth>

<BuildQueueTime>	</BuildQueueTime>

<BuildPercentRemaining>	</BuildPercentRemaining>

<IsBuilding>	</IsBuilding>	This one definitely works

<OpenGroundCompanySlots>	</OpenGroundCompanySlots>	Returns number of open ground company slots, possibly normalized to 10

<StoryTrigger>	</StoryTrigger>	Returns 1 if story trigger given by parameter_name has fired

Player
Evaluated on player variables.

<BudgetAllocation>	</BudgetAllocation> Perception for the proportion of income devoted to a particular goal category. REQUIRES the goal category as a parameter

<PlanetsControlled>	</PlanetsControlled>	Planets controlled normalized by total in GC

<AverageBuildQueueDepth>	</AverageBuildQueueDepth>	Build perceptions averaged across all planets

<AverageBuildTime>	</AverageBuildTime>

<AverageStarbase>	</AverageStarbase>	Starbase level average across all planets, normalized to a max of 5

<AverageGroundbase>	</AverageGroundbase>	Groundbase level average across all planets, normalized to a max of 5

<SpaceDefendedPlanets>	</SpaceDefendedPlanets>	Planets with space units normalized by total planets

<GroundDefendedPlanets>	</GroundDefendedPlanets>	Same as above but ground units

<AverageAgeOfGroundIntelligence></AverageAgeOfGroundIntelligence>	Average age of scouting data in seconds

<AverageAgeOfSpaceIntelligence>	</AverageAgeOfSpaceIntelligence>

<HasStarbaseOfLevel>	</HasStarbaseOfLevel>	Returns 1 if player owns a starbase of Parameter_Level. Can be further controlled with Parameter_Count (to require a minimum count)

<HasGroundbaseOfLevel>	</HasGroundbaseOfLevel>	Same as above but ground

<NumStructure></NumStructure>	Unused. Presumably total number of special structures (space and ground)

<NumStarbaseOfLevel></NumStarbaseOfLevel>	Counts the number of starbases owned by a player with a given Parameter_Level

<NumGroundbaseOfLevel></NumGroundbaseOfLevel>	Same as above but ground bases

<HomePlanet>	</HomePlanet>	Home Planet token as determined by GC XML

<BudgetFractionToBuild>	</BudgetFractionToBuild>	Fraction of a budget required to build a particular GameObjectType e.g. research facility

<CanAdvanceTech>	</CanAdvanceTech>	Returns 1 if the PlayerObject can tech up (Empire style tech)

<HasBeenAttackedInSpace>	</HasBeenAttackedInSpace>	Unused. Presumably returns 1 if a planet or player has been attacked in space

<HasBeenAttackedOnGround>	</HasBeenAttackedOnGround>	Same as above but ground

<TimeSinceSpaceDefender>	</TimeSinceSpaceDefender>	Unused. Presumably time in seconds since player/planet has been defended in space

<TimeSinceSpaceAttacker>	</TimeSinceSpaceAttacker>	Unused. Presumably time in seconds since player has attacked in space

<TimeSinceGroundDefender>	</TimeSinceGroundDefender>	Same as above but ground

<TimeSinceGroundAttacker>	</TimeSinceGroundAttacker>	Same as above

<WorstIslandFractionOfLargest>	</WorstIslandFractionOfLargest>	Of the two largest blocks of controlled planets that are not connected to each other, does the smaller have at least X% of the number of planets the larger has? This perception returns the % as a float between 0 and 1

<HasUnit>	</HasUnit>	Returns 1 if the PlayerObject has a unit of Parameter_Type

<StructureCount>	</StructureCount>	Returns count of structures for a PlayerObject or target planet. Can be limited by Parameter_Type and Parameter_Only_Consider_Complete

<IsDifficulty>	</IsDifficulty>	Returns 1 if the difficulty level matches the Parameter_Difficulty_Level_Type

<HasTechToProduce>	</HasTechToProduce>	Returns 1 if the player is at sufficient tech level to produce a given GameObjectType

<ActiveGoals>	</ActiveGoals>	Returns 1 if the AI player has goals active in a given Parameter_Category = AIGoalCategoryType

<AnyCurrentThreats>	</AnyCurrentThreats>	Returns 1 if the PlayerObject is adjacent to a human player

Normalized to total owned planets

<MaxedGroundbases>	</MaxedGroundbases>

<MaxedStarbases>	</MaxedStarbases>

e.g. force literals

<TimeLastSeen>	</TimeLastSeen>	Normalized to game age!

<TimeSinceSpaceConflict>	</TimeSinceSpaceConflict>	Time in seconds since a planet last had space combat

<TimeSinceGroundConflict>	</TimeSinceGroundConflict>	Same as above but ground

<TimeSinceConversion>	</TimeSinceConversion>	Time in seconds since planet changed owner

Tactical
Used in space/land battles. Will not apply to GC mode

<Owner>	</Owner>	Returns the faction owner of a GameObject. Usually used with IsFaction to check owner

<Location>	</Location>	Area "near" a given GameObjectType target. No details on what "near" is in terms of range

<Health>	</Health>	Health percent value of a GameObjectType target

<Shield>	</Shield>	Shield percent

<Energy>	</Energy>	Energy percent

<HardPointHealth>	</HardPointHealth>	Health percent of a given hardpoint connected to the target

<Force>	</Force>	AI combat power of player (total forces) or target

<ForceNBTP>	</ForceNBTP>	Same as above, but normalized by target something or total something

<ForceNBTD>	</ForceNBTD>	Force normalized to allied units

<FriendlyForceNBTD>	</FriendlyForceNBTD>	Friendly force normalized to allies

<EnemyForceNBTD>	</EnemyForceNBTD>	Same as above but enemy

<IsDefender>	</IsDefender>	Returns 1 if the playerObject is the defender in a battle (in GC mode only?)

<ForceVisibility>	</ForceVisibility> % of the enemies forces that are visible; always 1 with FOW off

<IsEnemyStartLocation>	</IsEnemyStartLocation>	Returns 1 if the target region (maps are divided into grids) is the enemy start location <CanRetreat>	</CanRetreat>	Returns 1 if retreating is allowed

<EnemyUnitConcentration>	</EnemyUnitConcentration>	Returns 1 if the location target has enemy units

<FriendlyUnitConcentration>	</FriendlyUnitConcentration>	Same as above but friendly

<EnemyUnitConcentrationNBTD>	</EnemyUnitConcentrationNBTD>	Same as above but normalized to allied units

<FriendlyUnitConcentrationNBTD>	</FriendlyUnitConcentrationNBTD>

<IsBombingRunAvailable>	</IsBombingRunAvailable>	Returns 1 if a bombing run is available to call in

<CashPointValue>	</CashPointValue>	Unused. Presumably returns the value of a credit dump

<IsCashPoint>	</IsCashPoint>	Unused. Presumably returns 1 for cash points

<ContainsHero>	</ContainsHero>	Returns 1 if the target has a hero in it somehow

<AreEnginesOnline>	</AreEnginesOnline>	Returns 1 if the target's engines are operable

<IsSetupPhase>	</IsSetupPhase>	Game literal, presumably returns 1 if there is a setup phase ongoing

<IsBuildPad>	</IsBuildPad>	Returns 1 if the target is a build pad of some type

<HasBuiltObject>	</HasBuiltObject>	Returns 1 if the target has a build pad object on it, can be controlled with Parameter_Type

<NearbyOpenBuildPadCount>	</NearbyOpenBuildPadCount>	Unused. Presumably returns the count of nearby build pads with no structure

<OpenBuildPadCount>	</OpenBuildPadCount>	Returns count of owned open build pads

<TacticalBuiltStructureCount>	</TacticalBuiltStructureCount>	Returns count of structure built on pads, controlled by Parameter_Type

<IsFriendlyStartLocation>	</IsFriendlyStartLocation>	Returns 1 if the target location is in the friendly start location

<HasTakenDamage>	</HasTakenDamage>	Returns 1 if the target has ever taken damage

<BaseLevel>	</BaseLevel>	Returns value of starbase or grounsbase level in tactical mode

<IsRetreating>	</IsRetreating>	Returns 1 if the target player is retreating

<IsInsideFriendlyShield>	</IsInsideFriendlyShield>	Unused, presumably returns 1 if the location is within the friendly shield generator radius

<IsInsideEnemyShield>	</IsInsideEnemyShield>	Same as above but enemy

<IsContestable>	</IsContestable>	Returns 1 if the target can be captured

<ReinforcementsUnnormalized>	</ReinforcementsUnnormalized>	Total AI Combat power of reinforcements waiting to enter battle

<UnitSpaceAvailable>	</UnitSpaceAvailable>	Unit cap available in tactical combat

<IsValidBombingTarget>	</IsValidBombingTarget>	Returns 1 if the target location can be bombed (i.e. not under shields)

<IsLandControlGame>	</IsLandControlGame>	Returns 1 if the game is land control style

<GarrisonSlotsAvailable>	</GarrisonSlotsAvailable>	Unused, presumably returns the number of garrison slots left in a given GameObjectType

<IsOrbitalBombardmentAvailable>	</IsOrbitalBombardmentAvailable>	Unused. Presumably returns 1 if the orbital bombardment is ready

<AdditionalPopulationCapacity>	</AdditionalPopulationCapacity>	Returns the population capacity provided by a given landing zone

Unnormalized
Regardless of the commented warning, Petro used these anyway. These can be very useful in specific situations.

Lies. Petro used these all the time

<GroundTotalUnnormalized>	</GroundTotalUnnormalized>

<SpaceTotalUnnormalized>	</SpaceTotalUnnormalized>

<IncomeUnnormalized>	</IncomeUnnormalized>

<IncomePotentialUnnormalized>	</IncomePotentialUnnormalized>

<BaseIncomeUnnormalized>	</BaseIncomeUnnormalized>

<GrossIncomeUnnormalized>	</GrossIncomeUnnormalized>

<NetIncomeUnnormalized>	</NetIncomeUnnormalized>

<MaxAllPlanetsIncomeUnnormalized>	</MaxAllPlanetsIncomeUnnormalized>

<MaxOwnedPlanetsIncomeUnnormalized>	</MaxOwnedPlanetsIncomeUnnormalized>

<MaintenanceUnnormalized>	</MaintenanceUnnormalized>

<PerTargetMaxGroundForce>	</PerTargetMaxGroundForce>

<PerTargetMaxSpaceForce>	</PerTargetMaxSpaceForce>

<PerTargetMaxIncome>	</PerTargetMaxIncome>

<PerTargetMaxBaseIncome>	</PerTargetMaxBaseIncome>

<MaxBuildQueueDepth>	</MaxBuildQueueDepth>

<MaxBuildQueueTime>	</MaxBuildQueueTime>

<HasSpaceUnitsBitfield>	</HasSpaceUnitsBitfield>	Searches the enemy fleet at a target for a given GameObjectType

<HasGroundUnitsBitfield>	</HasGroundUnitsBitfield>	Same as above but ground

<TargetPlayerID>	</TargetPlayerID>	Unused and unknown

<ForceUnnormalized>	</ForceUnnormalized>

<FriendlyForceUnnormalized>	</FriendlyForceUnnormalized> <EnemyForceUnnormalized>	</EnemyForceUnnormalized>

<CreditsUnnormalized>	</CreditsUnnormalized>	Total credits owned by PlayerObject

<EnemyUnitConcentrationUnnormalized>	</EnemyUnitConcentrationUnnormalized>

<FriendlyUnitConcentrationUnnormalized>	</FriendlyUnitConcentrationUnnormalized>

<TimeLastSeenUnnormalized>	</TimeLastSeenUnnormalized>

<GroundbaseTotalUnnormalized>	</GroundbaseTotalUnnormalized>	Total AI combat power provided by a target's groundbase

<StarbaseTotalUnnormalized>	</StarbaseTotalUnnormalized>

<StarbaseLevelUnnormalized>	</StarbaseLevelUnnormalized>

<GroundbaseLevelUnnormalized>	</GroundbaseLevelUnnormalized>

<MaxStarbaseLevelUnnormalized>	</MaxStarbaseLevelUnnormalized>	Maximum starbase level on a planet

<MaxGroundbaseLevelUnnormalized></MaxGroundbaseLevelUnnormalized>	Same as above but ground

<OpenStructureSlotsUnnormalized></OpenStructureSlotsUnnormalized>

<MaxStructureSlotsUnnormalized>	</MaxStructureSlotsUnnormalized>

<PlanetsControlledUnnormalized>	</PlanetsControlledUnnormalized>

<FriendlyUnitsBitfield>	</FriendlyUnitsBitfield>

<EnemyUnitsBitfield>	</EnemyUnitsBitfield>

<LandedForceUnnormalized>	</LandedForceUnnormalized>	Total force landed in a ground battle

<DistanceToNearestEnemy>	</DistanceToNearestEnemy>	Distance in Alamo units to nearest enemy.