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"

 <Parameter\_Category> </Parameter\_Category> GameObjectCategoryType or AIGoalCategoryType restriction

 <Parameter\_Attenuator> </Parameter\_Attenuator> Scales returned value of final literal?

 <Parameter\_Type> </Parameter\_Type> GameObjectType e.g. actual unit or planet name

 <Parameter\_Hard\_Point\_Type> </Parameter\_Hard\_Point\_Type> HardPointType e.g. Shield\_Generator

 <Parameter\_Faction> </Parameter\_Faction> Faction e.g. "Empire"

 <Parameter\_Level> </Parameter\_Level> For "leveled" objects (starbases)

 <Parameter\_Count> </Parameter\_Count> Number of objects

 <Parameter\_Name> </Parameter\_Name> 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)

<Timeline> </Timeline> 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.