AI War 2:Tutorial Step Conditions

Using A Conditional

Here's an example of some xml that has a tutorial step with a single condition in it:

    <tutorial_step text_to_show="Please switch your view over to look at the planet {c1.PlanetName}!">
     <condition type="PlayerViewIsOnSpecificPlanet" planet_by_index="0"/>
    </tutorial_step>

You can have up to 9 conditions per step (though goodness, more than 1-3 is excessive). The conditions can have data on them accessed based on their number, so for instance the planet that is referenced here is the 0th planet (the first one in the galaxy). The first condition is c1, so using c1.PlanetName in curly brackets in the text_to_show on the tutorial step will write out the name of the planet. If the first condition didn't exist, it would just write the curly bracketed text out. If the first condition didn't link to a planet, it would just write null.

The items below specify what extra data needs to be sent to the condition other than just the type, if any. And then they also specify what properties you can access for textual purposes, again if any. the first big bunch of conditions are not really specific to any special location or ship or whatever that might be unique, so they neither have parameters nor have any text you can get about them.

It's assumed that you'll write some flavor text in the text_to_show, so the actual conditions are invisible rather than trying to write out auto-generated junky sort of text about what your conditions are for the next step. A lot of the conditions in the game are things like "ship doesn't exist here for the enemy," and that could be because you captured it or hacked it or whatever else, and you can tell the players what you want them to do in your own words.

It's also worth noting that in a lot of cases you can refer to things like planets by one of two methods, but you don't need to do both. You can refer to them by index (starting at 0), or you can refer to them by name. If you've hand-designed a galaxy and know the names, then it's a lot easier to use the names to match. Much easier to follow. If you're letting it auto-generate the names of planets, then you probably want to use indexes instead.

Actual Conditions

Here's a full list of all the conditions that can be added to any tutorial step, and the data that goes with them, among some other things:

Player View

PlayerViewIsOnGalaxyMap

Is true if the player is looking at the galaxy map. There are no special parameters to this one.

PlayerViewIsOnAnyPlanet

Is true if the player is NOT looking at the galaxy map (aka is looking at some planet). There are no special parameters to this one.

PlayerViewIsOnSpecificPlanet

Is true if the player is in the planetary view (not galaxy map) looking at a specific planet.

• Parameters:
  • planet_by_index: starting at 0, references planets in the order they were added to the map. One way of saying which planet you mean.
  • planet_by_name: the name of the planet, instead. An easier way of saying which planet you mean, unless you're letting it name planets procedurally (in which case you have no idea what their name is).
  • Use only ONE of the two parameters above.

• Text properties available:
  • PlanetName: assuming that this is the first condition, you can use {c1.PlanetName} in your text to show the name of this planet. If it was the second condition you'd use c2, etc.

PlayerHasDoneAnyOnPlanetCameraAngling

Is true if the player has angled the camera (using Q or the fourth mouse button and then moving the mouse) since starting this tutorial step. Only works on the planetary view, not galaxy map.

PlayerHasDoneAnyOnPlanetCameraPanning

Is true if the player has panned the camera using the keyboard keys (not edge scrolling with the mouse) since starting this tutorial step. Only cares about the planetary view, not galaxy map.

PlayerHasDoneAnyOnPlanetCameraZooming

Is true if the player has zoomed the camera using the keyboard keys or mouse wheel since starting this tutorial step. Only cares about the planetary view, not galaxy map.

Game Status

GameIsPaused

Is true if the game is presently paused. There are no special parameters to this one.

GameIsUnpaused

Is true if the game is presently NOT paused. There are no special parameters to this one.

GameIsWon

Is true if the game has been won. There are no special parameters to this one.

GameIsLost

Is true if the game has been lost. There are no special parameters to this one.

Player Sidebar Status

PlayerHasSidebarMenuOpen_Local

Is true if the player has the Local tab open on the sidebar menu. There are no special parameters to this one.

PlayerHasSidebarMenuOpen_Build

Is true if the player has the Build tab open on the sidebar menu. There are no special parameters to this one.

PlayerHasSidebarMenuOpen_Tech

Is true if the player has the Tech tab open on the sidebar menu. There are no special parameters to this one.

PlayerHasSidebarMenuOpen_Hacking

Is true if the player has the Hacking tab open on the sidebar menu. There are no special parameters to this one.

PlayerHasSidebarMenuOpen_Merc

Is true if the player has the Mercenaries tab open on the sidebar menu. There are no special parameters to this one.

PlayerHasSidebarMenuOpen_Intel

Is true if the player has the Intel tab open on the sidebar menu. There are no special parameters to this one.

PlayerHasSidebarMenuOpen_Fleets

Is true if the player has the Fleets tab open on the sidebar menu. There are no special parameters to this one

Player Ship Counts Anywhere

PlayerHasCountOfSpecificShipAnywhere

Is true if the player has at least X ships of the specified type anywhere in the galaxy. DOES count ships inside transports, stacks, undeployed drones, etc.

• Parameters:
  • entity_type: one of the types of ship/structure, by the name property in the xml. "CombatEngineer" would be one example.
  • count: the number of this type of ship that are required.

• Text properties available:
  • EntityName: this is the display_name of the ship/structure that you asked it to find.
  • CountRequired: this is just equal to count, aka how many you said you want.
  • CountFound: this is how many it has actually found.
  • CountRemaining: this is how many fewer have been found than are required. Will not go less than 0.

PlayerHasCountOfSpecialEntityTypeAnywhere

Is true if the player has at least X ships of the specified SpecialEntityType anywhere in the galaxy. DOES count ships inside transports, stacks, undeployed drones, etc.

• Parameters:
  • special_entity_type: one of the SpecialEntityType enum values, such as "Frigate."
  • count: the number of this type of ship that are required.

• Text properties available:
  • CountRequired: this is just equal to count, aka how many you said you want.
  • CountFound: this is how many it has actually found.
  • CountRemaining: this is how many fewer have been found than are required. Will not go less than 0.

PlayerHasCountOfShipTagAnywhere

Is true if the player has at least X ships of the specified tag anywhere in the galaxy. DOES count ships inside transports, stacks, undeployed drones, etc.

• Parameters:
  • ship_tag: any arbitrary "tag" that is applied to a ship/structure via the "tags" xml attribute.
  • count: the number of this type of ship that are required.

• Text properties available:
  • CountRequired: this is just equal to count, aka how many you said you want.
  • CountFound: this is how many it has actually found.
  • CountRemaining: this is how many fewer have been found than are required. Will not go less than 0.

PlayerHasCountOfAnyShipAnywhere

Is true if the player has at least X ships of ANY type anywhere in the galaxy. DOES count ships inside transports, stacks, undeployed drones, etc.

• Parameters:
  • count: the number of ship that are required.

• Text properties available:
  • CountRequired: this is just equal to count, aka how many you said you want.
  • CountFound: this is how many it has actually found.
  • CountRemaining: this is how many fewer have been found than are required. Will not go less than 0.

Player Ship Counts On Specific Planets

PlayerHasCountOfSpecificShipOnPlanet

Is true if the player has at least X ships of the specified type on the specified planet. DOES count ships inside transports, stacks, undeployed drones, etc.

• Parameters:
  • planet_by_index: starting at 0, references planets in the order they were added to the map. One way of saying which planet you mean.
  • planet_by_name: the name of the planet, instead. An easier way of saying which planet you mean, unless you're letting it name planets procedurally (in which case you have no idea what their name is).
  • Use only ONE of the two parameters above.
  • entity_type: one of the types of ship/structure, by the name property in the xml. "CombatEngineer" would be one example.
  • count: the number of this type of ship that are required.

• Text properties available:
  • PlanetName: assuming that this is the first condition, you can use {c1.PlanetName} in your text to show the name of this planet. If it was the second condition you'd use c2, etc.
  • EntityName: this is the display_name of the ship/structure that you asked it to find.
  • CountRequired: this is just equal to count, aka how many you said you want.
  • CountFound: this is how many it has actually found.
  • CountRemaining: this is how many fewer have been found than are required. Will not go less than 0.

PlayerHasCountOfSpecialEntityTypeOnPlanet

Is true if the player has at least X ships of the specified SpecialEntityType on the specified planet. DOES count ships inside transports, stacks, undeployed drones, etc.

• Parameters:
  • planet_by_index: starting at 0, references planets in the order they were added to the map. One way of saying which planet you mean.
  • planet_by_name: the name of the planet, instead. An easier way of saying which planet you mean, unless you're letting it name planets procedurally (in which case you have no idea what their name is).
  • special_entity_type: one of the SpecialEntityType enum values, such as "Frigate."
  • count: the number of this type of ship that are required.

• Text properties available:
  • PlanetName: assuming that this is the first condition, you can use {c1.PlanetName} in your text to show the name of this planet. If it was the second condition you'd use c2, etc.
  • CountRequired: this is just equal to count, aka how many you said you want.
  • CountFound: this is how many it has actually found.
  • CountRemaining: this is how many fewer have been found than are required. Will not go less than 0.

PlayerHasCountOfShipTagOnPlanet

Is true if the player has at least X ships of the specified tag on the specified planet. DOES count ships inside transports, stacks, undeployed drones, etc.

• Parameters:
  • planet_by_index: starting at 0, references planets in the order they were added to the map. One way of saying which planet you mean.
  • planet_by_name: the name of the planet, instead. An easier way of saying which planet you mean, unless you're letting it name planets procedurally (in which case you have no idea what their name is).
  • ship_tag: any arbitrary "tag" that is applied to a ship/structure via the "tags" xml attribute.
  • count: the number of this type of ship that are required.

• Text properties available:
  • PlanetName: assuming that this is the first condition, you can use {c1.PlanetName} in your text to show the name of this planet. If it was the second condition you'd use c2, etc.
  • CountRequired: this is just equal to count, aka how many you said you want.
  • CountFound: this is how many it has actually found.
  • CountRemaining: this is how many fewer have been found than are required. Will not go less than 0.

PlayerHasCountOfAnyShipOnPlanet

Is true if the player has at least X ships of ANY type on the specified planet. DOES count ships inside transports, stacks, undeployed drones, etc.

• Parameters:
  • planet_by_index: starting at 0, references planets in the order they were added to the map. One way of saying which planet you mean.
  • planet_by_name: the name of the planet, instead. An easier way of saying which planet you mean, unless you're letting it name planets procedurally (in which case you have no idea what their name is).
  • count: the number of ship that are required.

• Text properties available:
  • PlanetName: assuming that this is the first condition, you can use {c1.PlanetName} in your text to show the name of this planet. If it was the second condition you'd use c2, etc.
  • CountRequired: this is just equal to count, aka how many you said you want.
  • CountFound: this is how many it has actually found.
  • CountRemaining: this is how many fewer have been found than are required. Will not go less than 0.

Player Faction Status

PlayerHasResearchedTechNumberOfTimes

Is true if the player has researched a specific tech X number of times.

• Parameters:
  • tech_upgrade: one of the types of tech, by the name property in the xml. "Technologist" would be one example.
  • count: the number of times this tech must have been updated.

• Text properties available:
  • TechName: this is the display_name of the tech that you asked it to find, with the pretty colorized category and everything.
  • CountRequired: this is just equal to count, aka how many you said you want.
  • CountFound: this is how many it has actually found.
  • CountRemaining: this is how many fewer have been found than are required. Will not go less than 0.

PlayerTotalEnergyAtLeast

Is true if the player is producing at least X amount of energy.

• Parameters:
  • count: the amount of energy that must be produced by the player.

• Text properties available:
  • CountRequired: this is just equal to count, aka how many you said you want.
  • CountFound: this is how many it has actually found.
  • CountRemaining: this is how many fewer have been found than are required. Will not go less than 0.

PlayerNetEnergyAtLeast

Is true if the player is has a surplus of at least X energy (production minus consumption).

• Parameters:
  • count: the amount of net energy that the player must have.

• Text properties available:
  • CountRequired: this is just equal to count, aka how many you said you want.
  • CountFound: this is how many it has actually found.
  • CountRemaining: this is how many fewer have been found than are required. Will not go less than 0.

PlayerControlsAtLeastXPlanets

Is true if the player has control of at least X planets.

• Parameters:
  • count: the number of planets the player must have command stations on.

• Text properties available:
  • CountRequired: this is just equal to count, aka how many you said you want.
  • CountFound: this is how many it has actually found.
  • CountRemaining: this is how many fewer have been found than are required. Will not go less than 0.

PlayerControlsSpecificPlanet

Is true if the player controls the specific planet (has a command station on it).

• Parameters:
  • planet_by_index: starting at 0, references planets in the order they were added to the map. One way of saying which planet you mean.
  • planet_by_name: the name of the planet, instead. An easier way of saying which planet you mean, unless you're letting it name planets procedurally (in which case you have no idea what their name is).
  • Only ONE of the two above parameters should be used.

• Text properties available:
  • PlanetName: assuming that this is the first condition, you can use {c1.PlanetName} in your text to show the name of this planet. If it was the second condition you'd use c2, etc.

Enemy Ship Counts On Specific Planets

EnemyCombatantsOnPlanetLessThanOrEqualTo

Is true if all hostile factions on the planet combined have less than or equal to X ships that are considered combatants (aka have guns). DOES count ships inside transports, stacks, undeployed drones, guard post reinforcements, etc.

• Parameters:
  • planet_by_index: starting at 0, references planets in the order they were added to the map. One way of saying which planet you mean.
  • planet_by_name: the name of the planet, instead. An easier way of saying which planet you mean, unless you're letting it name planets procedurally (in which case you have no idea what their name is).
  • Use only ONE of the two parameters above.
  • count: the max number of ships that are acceptable.

• Text properties available:
  • PlanetName: assuming that this is the first condition, you can use {c1.PlanetName} in your text to show the name of this planet. If it was the second condition you'd use c2, etc.
  • CountRequired: this is just equal to count, aka how many you said you want.
  • CountFound: this is how many it has actually found.
  • ReverseCountRemaining: this is how many more have been found than are allowed. Will not go less than 0.

EnemyShipsOfSpecificTypeOnPlanetLessThanOrEqualTo

Is true if all hostile factions on the planet combined have less than or equal to X ships of the specified type. DOES count ships inside transports, stacks, undeployed drones, guard post reinforcements, etc.

• Parameters:
  • planet_by_index: starting at 0, references planets in the order they were added to the map. One way of saying which planet you mean.
  • planet_by_name: the name of the planet, instead. An easier way of saying which planet you mean, unless you're letting it name planets procedurally (in which case you have no idea what their name is).
  • Use only ONE of the two parameters above.
  • entity_type: one of the types of ship/structure, by the name property in the xml. "CombatEngineer" would be one example.
  • count: the max number of ships that are acceptable.

• Text properties available:
  • PlanetName: assuming that this is the first condition, you can use {c1.PlanetName} in your text to show the name of this planet. If it was the second condition you'd use c2, etc.
  • EntityName: this is the display_name of the ship/structure that you asked it to find.
  • CountRequired: this is just equal to count, aka how many you said you want.
  • CountFound: this is how many it has actually found.
  • ReverseCountRemaining: this is how many more have been found than are allowed. Will not go less than 0.

EnemyShipsOfSpecialEntityOnPlanetLessThanOrEqualTo

Is true if all hostile factions on the planet combined have less than or equal to X ships of the specified SpecialEntityType. DOES count ships inside transports, stacks, undeployed drones, guard post reinforcements, etc.

• Parameters:
  • planet_by_index: starting at 0, references planets in the order they were added to the map. One way of saying which planet you mean.
  • planet_by_name: the name of the planet, instead. An easier way of saying which planet you mean, unless you're letting it name planets procedurally (in which case you have no idea what their name is).
  • Use only ONE of the two parameters above.
  • special_entity_type: one of the SpecialEntityType enum values, such as "Frigate."
  • count: the max number of ships that are acceptable.

• Text properties available:
  • PlanetName: assuming that this is the first condition, you can use {c1.PlanetName} in your text to show the name of this planet. If it was the second condition you'd use c2, etc.
  • CountRequired: this is just equal to count, aka how many you said you want.
  • CountFound: this is how many it has actually found.
  • ReverseCountRemaining: this is how many more have been found than are allowed. Will not go less than 0.

EnemyShipsOfShipTagOnPlanetLessThanOrEqualTo

Is true if all hostile factions on the planet combined have less than or equal to X ships of the specified tag. DOES count ships inside transports, stacks, undeployed drones, guard post reinforcements, etc.

• Parameters:
  • planet_by_index: starting at 0, references planets in the order they were added to the map. One way of saying which planet you mean.
  • planet_by_name: the name of the planet, instead. An easier way of saying which planet you mean, unless you're letting it name planets procedurally (in which case you have no idea what their name is).
  • Use only ONE of the two parameters above.
  • ship_tag: any arbitrary "tag" that is applied to a ship/structure via the "tags" xml attribute.
  • count: the max number of ships that are acceptable.

• Text properties available:
  • PlanetName: assuming that this is the first condition, you can use {c1.PlanetName} in your text to show the name of this planet. If it was the second condition you'd use c2, etc.
  • CountRequired: this is just equal to count, aka how many you said you want.
  • CountFound: this is how many it has actually found.
  • ReverseCountRemaining: this is how many more have been found than are allowed. Will not go less than 0.

Relative Strength Ratios On Specific Planets

HostileStrengthToSelfRatioOnSpecificPlanetIsAtLeast

Is true if all hostile factions on the planet combined have a strength of at least X compared to the player. 0.5 would mean the enemy forces must be at least half as strong as the player. DOES count ships inside transports, stacks, undeployed drones, guard post reinforcements, etc.

• Parameters:
  • planet_by_index: starting at 0, references planets in the order they were added to the map. One way of saying which planet you mean.
  • planet_by_name: the name of the planet, instead. An easier way of saying which planet you mean, unless you're letting it name planets procedurally (in which case you have no idea what their name is).
  • Use only ONE of the two parameters above.
  • ratio: a floating point number that indicates how much stronger the enemy must be compared to you.
    • 0.5 would mean that the enemy has to be at least half as strong as you. 1.5 would mean it needs to be 50% stronger than you.

• Text properties available:
  • PlanetName: assuming that this is the first condition, you can use {c1.PlanetName} in your text to show the name of this planet. If it was the second condition you'd use c2, etc.
  • RatioAsPercent: this is just equal to ratio you specified, but in a percentage form (so 0.5 becomes 50%).
  • RatioFoundAsPercent: this is the ratio it actually found, again expressed in a percentage form. So if the actual ratio is 0.234, it would write 25%.

HostileStrengthToSelfRatioOnSpecificPlanetIsLessThan

Same exact thing as HostileStrengthToSelfRatioOnSpecificPlanetIsAtLeast, except that it checks for enemy forces being LOWER, rather than greater-than-or-equal-to. So if your specified ratio is 0.5, then this condition returns true when the enemy forces are no more than 50% as strong as the player's forces.

HostileStrengthToSelfAndAlliedRatioOnSpecificPlanetIsAtLeast

Same exact thing as HostileStrengthToSelfRatioOnSpecificPlanetIsAtLeast, except that it not only includes your strength, but also your allies together. Those could be other factions or other players.

HostileStrengthToSelfAndAlliedRatioOnSpecificPlanetIsLessThan

Same exact thing as HostileStrengthToSelfRatioOnSpecificPlanetIsLessThan, except that it not only includes your strength, but also your allies together. Those could be other factions or other players.

Player Selected Ship Counts

PlayerHasSelectedCountOfSpecificShip

Is true if the player has at least X ships of the specified type selected. ONLY counts ships that are directly selected, but does include stacks. Doesn't include transported or otherwise-contained ships, though.

• Parameters:
  • entity_type: one of the types of ship/structure, by the name property in the xml. "CombatEngineer" would be one example.
  • count: the number of this type of ship that are required.

• Text properties available:
  • EntityName: this is the display_name of the ship/structure that you asked it to find.
  • CountRequired: this is just equal to count, aka how many you said you want.
  • CountFound: this is how many it has actually found.
  • CountRemaining: this is how many fewer have been found than are required. Will not go less than 0.

PlayerHasSelectedCountOfSpecialEntityType

Is true if the player has at least X ships of the specified SpecialEntityType selected. ONLY counts ships that are directly selected, but does include stacks. Doesn't include transported or otherwise-contained ships, though.

• Parameters:
  • special_entity_type: one of the SpecialEntityType enum values, such as "Frigate."
  • count: the number of this type of ship that are required.

• Text properties available:
  • CountRequired: this is just equal to count, aka how many you said you want.
  • CountFound: this is how many it has actually found.
  • CountRemaining: this is how many fewer have been found than are required. Will not go less than 0.

PlayerHasSelectedCountOfShipTag

Is true if the player has at least X ships of the specified tag selected. ONLY counts ships that are directly selected, but does include stacks. Doesn't include transported or otherwise-contained ships, though.

• Parameters:
  • ship_tag: any arbitrary "tag" that is applied to a ship/structure via the "tags" xml attribute.
  • count: the number of this type of ship that are required.

• Text properties available:
  • CountRequired: this is just equal to count, aka how many you said you want.
  • CountFound: this is how many it has actually found.
  • CountRemaining: this is how many fewer have been found than are required. Will not go less than 0.

Planet Vision

PlanetHasBeenExplored

Is true if the planet has been explored at all (status is greater than unexplored). Any means of exploration, hacking included, counts for this.

• Parameters:
  • planet_by_index: starting at 0, references planets in the order they were added to the map. One way of saying which planet you mean.
  • planet_by_name: the name of the planet, instead. An easier way of saying which planet you mean, unless you're letting it name planets procedurally (in which case you have no idea what their name is).
  • Use only ONE of the two parameters above.

• Text properties available:
  • PlanetName: assuming that this is the first condition, you can use {c1.PlanetName} in your text to show the name of this planet. If it was the second condition you'd use c2, etc.

PlanetIsWatched

Same exact thing as PlanetHasBeenExplored, except that it requires that the players have current vision on that planet. That might just mean that they have ships there now (granting temporary vision), or that they've hacked it to get permanent vision.

PlanetIsPermanentlyWatched

Same exact thing as PlanetIsWatched, except that it requires that the players have permanent vision of the planet, generally by hacking it.