AoE2 Scenario Parser

https://ksneijders.github.io/AoE2ScenarioParser
Admin
A tool for editing Age of Empires 2 Definitive Edition scenario files outside the in-game editor,...
Tokens:917,723
Snippets:3,356
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Python Example: Setting up Python, PyCharm and the Parser

Source: https://ksneijders.github.io/AoE2ScenarioParser/community/resources

A guide on how to set up your development environment with Python and PyCharm, and install the AoE2 Scenario Parser.

```bash
# Install the parser using pip:
pip install AoE2ScenarioParser
```

```python
# Example usage after installation:
from AoE2ScenarioParser.parser import AoE2Scenario

scenario = AoE2Scenario('path/to/your/scenario.aoe2scenario')
print(f"Scenario loaded: {scenario.filename}")

# Access map data
map_manager = scenario.map_manager
terrain = map_manager.get_terrain(10, 20)
print(f"Terrain at (10, 20): {terrain}")

# Save changes
# scenario.save_scenario('path/to/output/scenario.aoe2scenario')
```

--------------------------------

### Hello World Example: Step-by-Step Guide

Source: https://ksneijders.github.io/AoE2ScenarioParser/hello_world

This section details the process of creating a 'Hello World' scenario using the AoE2 Scenario Parser. It covers the essential steps from scenario creation to testing the implementation, including adding game elements like triggers and units.

```English
1. Create the scenario
2. Setup the project
3. Getting the scenario path
4. Test if it works
5. Adding a trigger
6. Adding units
7. Changing the map
```

--------------------------------

### AoE2ScenarioParser Examples

Source: https://ksneijders.github.io/AoE2ScenarioParser/examples/examples

This section provides examples and answers to frequently asked questions to help users understand and utilize the AoE2ScenarioParser library more effectively. It includes a 'Hello World' example with a complete code block.

```APIDOC
Examples:
  - Purpose: To demonstrate usage and answer common questions.
  - Content: Includes a 'Hello World' example with a complete code block.
  - Source: https://ksneijders.github.io/AoE2ScenarioParser/examples/examples/
  - Hello World Example: https://ksneijders.github.io/AoE2ScenarioParser/hello_world/
```

--------------------------------

### Install AoE2ScenarioParser

Source: https://ksneijders.github.io/AoE2ScenarioParser/installation

Installs the AoE2ScenarioParser library using pip. This is the recommended method for installing the library and its dependencies.

```Python
pip install AoE2ScenarioParser
```

--------------------------------

### Clone AoE2ScenarioParser Repository

Source: https://ksneijders.github.io/AoE2ScenarioParser/installation

Manually installs the AoE2ScenarioParser library by cloning the Git repository. This method requires manual installation of dependencies and updates.

```Git
git clone https://github.com/KSneijders/AoE2ScenarioParser.git
```

--------------------------------

### Starting Age Dataset

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/units

API documentation for StartingAge, defining the initial age a player begins the game in.

```APIDOC
StartingAge:
  __init__(self, age_id: int)
    Initializes a StartingAge object.
    age_id: An integer representing the starting age (e.g., Dark Age, Feudal Age).
```

--------------------------------

### Community Examples for AoE2ScenarioParser

Source: https://ksneijders.github.io/AoE2ScenarioParser/community/resources

Community-contributed examples demonstrating various functionalities of the AoE2ScenarioParser. Includes a GitHub repository with detailed documentation, conventions, and guidelines for Python and PyCharm usage.

```APIDOC
Resource: GitHub Repo (By duyhung2h)
URL: https://github.com/duyhung2h/AoE2ScenarioParserTutorial
Description: A GitHub repository with multiple examples showcasing all sorts of things you can do with the parser. It also includes useful conventions and guidelines for using Python and Pycharm. Every example and guide is nicely documented with its own README file.
```

--------------------------------

### XS Check Example

Source: https://ksneijders.github.io/AoE2ScenarioParser/cheatsheets/xs_check

Provides a practical example demonstrating how to use the XS Check functionality.

```APIDOC
XS Check Example:
  - Usage: Demonstrates the practical application of XS Check, likely showing input and expected output or behavior.
```

--------------------------------

### Install Specific AoE2ScenarioParser Version

Source: https://ksneijders.github.io/AoE2ScenarioParser/installation

This command allows you to install a specific version of the AoE2ScenarioParser library. Replace `<VERSION>` with the desired version number (e.g., '0.1.47'). The `--force-reinstall` flag ensures a clean installation.

```bash
pip install "AoE2ScenarioParser==<VERSION>" --force-reinstall
```

--------------------------------

### XS Script Introduction

Source: https://ksneijders.github.io/AoE2ScenarioParser/cheatsheets/xs

An introduction to the XS scripting language for Age of Empires II, with a link to the UGC Guide for beginners.

```APIDOC
XS Script Introduction: For an introduction to the XS scripting language itself, you can check out the [UGC Guide](https://divy1211.github.io/AoE2DE_UGC_Guide/general/xs/beginner/).
```

--------------------------------

### Get Tree Objects

Source: https://ksneijders.github.io/AoE2ScenarioParser/cheatsheets/datasets

Retrieves all tree objects available in the game, such as OAK_TREE, PINE_TREE, and BAMBOO. Provides an example of how to get all tree objects.

```Python
# Get all tree objects (e.g. OAK_TREE, PINE_TREE, BAMBOO etc.)
# Example:
all_trees = OtherInfo.trees()
```

--------------------------------

### Setting up Python, PyCharm, and AoE2ScenarioParser

Source: https://ksneijders.github.io/AoE2ScenarioParser/community/resources

Community-provided resources for setting up the development environment, including Python, PyCharm IDE, and the AoE2ScenarioParser. Resources include textual explanations with images and video tutorials.

```APIDOC
Resource: Age of Kings Heaven Post (By Bassefrom)
URL: https://aok.heavengames.com/cgi-bin/forums/display.cgi?action=ct&f=4,44777,,30
Description: A textual explanation including images and examples to showcase the installation process.

Resource: Youtube video (By duyhung2h)
URL: https://www.youtube.com/watch?v=6dP-pDbFCNw&feature=youtu.be
Description: A thorough video explaining and showcasing the installation process.
```

--------------------------------

### AoE2ScenarioParser Player Management Example

Source: https://ksneijders.github.io/AoE2ScenarioParser/cheatsheets/players

Demonstrates how to use the player manager to edit player attributes such as starting civilization, architecture, and resources. This example provides a practical code snippet for modifying player data within an Age of Empires II scenario.

```Python
from AoE2ScenarioParser.scenarios.aoe2_de_scenario import AoE2DEScenario
from AoE2ScenarioParser.datasets.object_support import Civilization
from AoE2ScenarioParser.datasets.players import PlayerId

# File & Folder setup
# Define paths to the scenario folder.

```

--------------------------------

### Get New Reference ID

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/units/unit_manager

Generates and returns a new, unique reference ID for units. It uses a generator that starts from the current highest ID.

```Python
def get_new_reference_id(self) -> int:
    """
    Get a new ID each time the function is called. Starting from the current highest ID.

    Returns:
        The newly generated ID
    """
    return next(self.reference_id_generator)
```

--------------------------------

### Get Square of Tiles and Modify Terrain

Source: https://ksneijders.github.io/AoE2ScenarioParser/cheatsheets/map

Demonstrates how to retrieve a rectangular area of tiles using `get_square_1d()` or `get_square_2d()` and modify their terrain type. The example changes a square of tiles to roads.

```Python
from AoE2ScenarioParser.datasets.terrains import TerrainId

# Using: get_square_1d
for tile in map_manager.get_square_1d(x1=4, y1=4, x2=8, y2=8):
    tile.terrain_id = TerrainId.ROAD

# Using: get_square_2d
for tile_row in map_manager.get_square_2d(x1=4, y1=4, x2=8, y2=8):
    for tile in tile_row:
        tile.terrain_id = TerrainId.ROAD
```

--------------------------------

### Settings API Documentation

Source: https://ksneijders.github.io/AoE2ScenarioParser/examples/examples

API documentation for managing scenario settings.

```APIDOC
Settings:
  __init__(scenario_data: dict)
    Initializes the Settings object with scenario data.
    Parameters:
      scenario_data: The dictionary containing scenario data.

  get_setting(key: str)
    Retrieves a specific setting by its key.
    Parameters:
      key: The key of the setting to retrieve.
    Returns: The value of the setting.

  set_setting(key: str, value: any)
    Sets a specific setting.
    Parameters:
      key: The key of the setting to set.
      value: The new value for the setting.
```

--------------------------------

### Helper to Get Square Rows

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/map/map_manager

Internal helper method to iterate through and yield rows of tiles within a specified rectangular area. It calculates the 1D indices for the start and end of each row.

```Python
def _get_square_rows(self, x1, y1, x2, y2):
        row_nums = range(y1, y2 + 1)
        for row in row_nums:
            i1 = xy_to_i(x1, row, self.map_size)
            i2 = xy_to_i(x2, row, self.map_size)
            tiles = self.terrain[i1:i2 + 1]
            yield tiles
```

--------------------------------

### Unit Management API

Source: https://ksneijders.github.io/AoE2ScenarioParser/hello_world

API documentation for UnitManager, UnitManagerDE, and Unit classes for managing units in scenarios.

```APIDOC
UnitManager:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/units/unit_manager/)

UnitManagerDE:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/units/unit_manager_de/)

Unit:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/units/unit/)
```

--------------------------------

### Get and Modify Terrain Tile Properties

Source: https://ksneijders.github.io/AoE2ScenarioParser/cheatsheets/map

Demonstrates how to retrieve a specific terrain tile and access its properties such as terrain_id, elevation, and layer. It also shows how to modify the terrain_id, for example, changing a tile to shallow water.

```Python
tile = map_manager.get_tile(0, 0)
tile.terrain_id
tile.elevation
tile.layer
```

```Python
from AoE2ScenarioParser.datasets.terrains import TerrainId

tile = map_manager.get_tile(i=19)  # (0 based, 0 is the 1st tile, 1 is the second tile etc.)
tile.terrain_id = TerrainId.WATER_SHALLOW
```

--------------------------------

### Find Unit Projectiles

Source: https://ksneijders.github.io/AoE2ScenarioParser/cheatsheets/datasets

Provides a method to find specific unit projectiles, including options to specify if the projectile has chemistry and if it's a secondary projectile. Example shows getting the second projectile of a Chu Ko Nu.

```Python
# Get the second projectile that a CHU KO NU shoots. (Pre-chemistry arrows)
ProjectileInfo.get_unit_projectile(UnitInfo.CHU_KO_NU.ID, has_chemistry=False, secondary=True)
```

--------------------------------

### API Docs: Player Module

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/starting_age

API documentation for the Player module, covering classes for managing player data and configurations.

```APIDOC
PlayerManager:
  Description: Manages player-related data and configurations in AoE2 scenarios.

PlayerData:
  Description: Represents the data associated with a specific player in an AoE2 scenario.
```

--------------------------------

### Support Utilities API

Source: https://ksneijders.github.io/AoE2ScenarioParser/hello_world

API documentation for Area, AreaAttr, and AreaState classes, providing support utilities.

```APIDOC
Area:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/support/area/)

AreaAttr:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/support/area_attr/)

AreaState:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/support/area_state/)
```

--------------------------------

### API Docs: Options Module

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/starting_age

API documentation for the Options module, detailing the OptionManager class for scenario settings.

```APIDOC
OptionManager:
  Description: Manages various settings and options for AoE2 scenarios.
```

--------------------------------

### Dataset APIs

Source: https://ksneijders.github.io/AoE2ScenarioParser/hello_world

API documentation for various datasets used in AoE2ScenarioParser, including trigger lists, buildings, heroes, and more.

```APIDOC
ActionType:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/action_type/)

Age:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/age/)

AttackStance:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/attack_stance/)

Attribute:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/attribute/)

BlastLevel:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/blast_level/)

BlockageClass:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/blockage_class/)

BuildingInfo:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/buildings/)

ButtonLocation:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/button_location/)

ChargeEvent:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/charge_event/)

ChargeType:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/charge_type/)

Civilization:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/civilization/)

ColorId:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/color_id/)

ColorMood:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/color_mood/)

CombatAbility:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/combat_ability/)

Comparison:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/comparison/)

ConditionId:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/conditions/)

DamageClass:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/damage_class/)

DifficultyLevel:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/difficulty_level/)

DiplomacyState:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/diplomacy_state/)

EffectId:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/effects/)

FogVisibility:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/fog_visibility/)

GarrisonType:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/garrison_type/)

HeroInfo:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/heroes/)
```

--------------------------------

### AoE2ScenarioParser Datasets - Starting Age

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/damage_class

Defines the starting age for players in a scenario.

```APIDOC
StartingAge:
  Description: Represents the starting age.
```

--------------------------------

### Starting Age Dataset

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/button_location

Information about the starting age in Age of Empires II scenarios.

```APIDOC
StartingAge:
  Description: Defines the starting age for a scenario.
  URL: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/starting_age/
```

--------------------------------

### Settings API Documentation

Source: https://ksneijders.github.io/AoE2ScenarioParser/installation

Documentation for the Settings class, which likely handles configuration and settings for the parser.

```APIDOC
Settings:
  __init__(settings_path: str)
    settings_path: Path to the settings file.
  
  get_setting(key: str) -> Any
    Retrieves a specific setting by its key.
    key: The key of the setting to retrieve.
  
  set_setting(key: str, value: Any)
    Sets a specific setting.
    key: The key of the setting to set.
    value: The value to assign to the setting.
```

--------------------------------

### OptionManager API

Source: https://ksneijders.github.io/AoE2ScenarioParser/hello_world

API documentation for the OptionManager class, which likely handles scenario options.

```APIDOC
OptionManager:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/options/option_manager/)
```

--------------------------------

### AoE2ScenarioParser Starting Ages

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/combat_ability

Lists the available starting ages for civilizations in Age of Empires II scenarios.

```python
from AoE2ScenarioParser.datasets.starting_age import StartingAge

# Example usage:
# print(StartingAge.DARK_AGE)
```

--------------------------------

### Player Management API

Source: https://ksneijders.github.io/AoE2ScenarioParser/hello_world

API documentation for PlayerManager and PlayerData classes, related to player information in scenarios.

```APIDOC
PlayerManager:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/player/player_manager/)

PlayerData:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/player/player/)
```

--------------------------------

### Starting Scout ID

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/attribute

Determines the Unit ID for the starting scout unit. This can be set to any unit, including buildings.

```Python
STARTING_SCOUT_ID = 263
```

--------------------------------

### UnitAIAction Dataset Documentation

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/starting_age

API documentation for the UnitAIAction dataset, detailing the actions that AI-controlled units can perform.

```APIDOC
UnitAIAction:
  Description: Defines the possible actions for AI-controlled units.
```

--------------------------------

### XS Management API

Source: https://ksneijders.github.io/AoE2ScenarioParser/hello_world

API documentation for XsManager and XsCheck classes, likely related to XS (eXtensible Scripting) features.

```APIDOC
XsManager:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/xs/xs_manager_de/)

XsCheck:
  (See https://ksneijders.github.io/AoE2ScenarioParser/api_docs/xs/xs_check/)
```

--------------------------------

### Initialize AoE2ScenarioParser

Source: https://ksneijders.github.io/AoE2ScenarioParser/hello_world

Loads an existing Age of Empires 2 scenario file and initializes the scenario object. It also sets up managers for triggers, units, and the map.

```python
from AoE2ScenarioParser.datasets.players import PlayerId
from AoE2ScenarioParser.datasets.units import UnitInfo
from AoE2ScenarioParser.scenarios.aoe2_de_scenario import AoE2DEScenario

# The path to your scenario folder
input_folder = "C:/path/to/your/scenario/folder/"

# The scenario object.
scenario = AoE2DEScenario.from_file(input_folder + "hello world.aoe2scenario")

# Save reference to the manager, so you don't have to do "scenario.trigger_manager..." each time
trigger_manager = scenario.trigger_manager
unit_manager = scenario.unit_manager
map_manager = scenario.map_manager

# Save the created trigger
hello_world_trigger = trigger_manager.add_trigger("Hello World Trigger")
```

--------------------------------

### Starting Scout ID Attribute

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/attribute

Defines the unit ID for the starting scout unit in a scenario. This can be set to any unit, including buildings.

```APIDOC
STARTING_SCOUT_ID = 263
Value: 263
Purpose: Unit ID for the starting scout. Can be set to any unit (even buildings)
Default Values:
  * 448: (Scout Cavalry) Default
  * 751: (Eagle Scout) Aztecs, Incas and Mayans
  * 1755: (Camel Scout) Gurjaras
```

--------------------------------

### AoE2ScenarioParser API Datasets

Source: https://ksneijders.github.io/AoE2ScenarioParser/getting_started

Provides links to API documentation for various datasets within the AoE2ScenarioParser library, covering game elements like operations, player information, units, and more.

```APIDOC
Operation: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/operation/
OtherInfo: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/other/
PanelLocation: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/panel_location/
PlayerColorId: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/player_color_id/
PlayerId: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/players/
ProjectileHitMode: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/projectile_hit_mode/
ProjectileInfo: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/projectiles/
ProjectileSmartMode: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/projectile_smart_mode/
ProjectileVanishMode: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/projectile_vanish_mode/
ScenarioVariant: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/scenario_variant/
SecondaryGameMode: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/secondary_game_mode/
SelectionEffect: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/selection_effect/
StartingAge: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/starting_age/
TechInfo: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/techs/
TechnologyState: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/technology_state/
TerrainId: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/terrains/
TerrainRestrictions: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/terrain_restrictions/
TimeUnit: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/time_unit/
UnitAIAction: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/unit_ai_action/
UnitInfo: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/units/
UnitTrait: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/unit_trait/
VictoryCondition: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/victory_condition/
VictoryTimerType: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/victory_timer_type/
VisibilityState: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/visibility_state/
InfoDatasetBase: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/support/info_dataset_base/
```

--------------------------------

### Convert Scenario Operation Example

Source: https://ksneijders.github.io/AoE2ScenarioParser/examples/operations

Example demonstrating how to convert a scenario file to or from a Return of Rome scenario format using the AoE2 Scenario Parser.

```Python
# Example usage for converting scenarios
# from ksneijders_github_io_aoe2scenarioparser.examples.operations import convert_scenario

# Placeholder for actual conversion logic
print("Scenario conversion example")
```

--------------------------------

### AoE2ScenarioParser Cheatsheets: Example Usage

Source: https://ksneijders.github.io/AoE2ScenarioParser/cheatsheets/xs_check

Provides an example demonstrating the usage of the AoE2ScenarioParser, likely showcasing common operations or a specific workflow.

```APIDOC
Example: https://ksneijders.github.io/AoE2ScenarioParser/cheatsheets/xs_check/#example
```

--------------------------------

### Starting Age Dataset

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/object_attribute

Specifies the starting age for players in Age of Empires 2 scenarios. This dataset is used to configure the initial age of civilizations.

```APIDOC
StartingAge:
  Description: Starting age configurations for players.
```

--------------------------------

### Load Scenario File

Source: https://ksneijders.github.io/AoE2ScenarioParser/getting_started

Illustrates how to create a Scenario object by loading an existing Age of Empires 2 scenario file using the `from_file` class method.

```Python
scenario = AoE2DEScenario.from_file(input_path)
```

--------------------------------

### API Docs: Core Scenario Handling

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/starting_age

API documentation for core scenario parsing classes, including AoE2Scenario and AoE2DEScenario.

```APIDOC
AoE2Scenario:
  Description: Handles parsing and manipulation of standard Age of Empires II scenario files.

AoE2DEScenario:
  Description: Handles parsing and manipulation of Age of Empires II: Definitive Edition scenario files.
```

--------------------------------

### TechInfo - Get Unique Unit Upgrades

Source: https://ksneijders.github.io/AoE2ScenarioParser/cheatsheets/datasets

Shows how to get unique unit upgrades using `unique_unit_upgrades()` from TechInfo, with options to exclude castle or non-castle upgrades.

```Python
# Get all unique unit techs (e.g. ELITE_LONGBOWMAN, ELITE_TEUTONIC_KNIGHT etc.)
# You can disable certain categories like:
# - exclude_castle_techs
# - exclude_non_castle_techs  (Excludes stuff like: ELITE_LONGBOAT, IMPERIAL_SKIRMISHER)
# Example:
uu_castle_upgrades = TechInfo.unique_unit_upgrades(exclude_non_castle_techs=True)
```

--------------------------------

### OptionManager API Documentation

Source: https://ksneijders.github.io/AoE2ScenarioParser/examples/examples

API documentation for the OptionManager class, managing scenario options.

```APIDOC
OptionManager:
  __init__(scenario_data: dict)
    Initializes the OptionManager with scenario data.
    Parameters:
      scenario_data: The dictionary containing scenario data.

  get_option(key: str)
    Retrieves a specific option by its key.
    Parameters:
      key: The key of the option to retrieve.
    Returns: The value of the option.

  set_option(key: str, value: any)
    Sets a specific option.
    Parameters:
      key: The key of the option to set.
      value: The new value for the option.
```

--------------------------------

### UnitInfo - Get Unique Units

Source: https://ksneijders.github.io/AoE2ScenarioParser/cheatsheets/datasets

Shows how to get all unique units using the `unique_units()` function from UnitInfo, with options to exclude elite, castle, or non-castle units.

```Python
# Get all unique units (e.g. HUSKARL, CONQUISTADOR, LONGBOAT, SLINGER etc.)
# You can disable certain categories like:
# - exclude_elite_units
# - exclude_non_elite_units
# - exclude_castle_units  (From the castle building)
# - exclude_non_castle_units  (From anything but the castle building)
# Example:
all_unique_non_castle_non_elite_units = UnitInfo.unique_units(exclude_elite_units=True, exclude_castle_units=True)
```

--------------------------------

### Get Tile by Coordinates or Index

Source: https://ksneijders.github.io/AoE2ScenarioParser/cheatsheets/map

Provides methods to get a specific tile from the map using either its X and Y coordinates or its index in the one-dimensional terrain list.

```Python
map_manager.get_tile(x=5, y=8)  # Get tile at x5,y8
map_manager.get_tile(i=85)      # Get the 86th tile (0 based, 0 is the 1st tile, 1 is the second tile etc.)
```

--------------------------------

### InfoDatasetBase Documentation

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/starting_age

API documentation for the InfoDatasetBase class, serving as a base for various information datasets.

```APIDOC
InfoDatasetBase:
  Description: Base class for datasets that provide information about game elements.
```

--------------------------------

### Starting Villagers and Resource Settings

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/trigger_lists/attribute

Configures the initial number of villagers and starting resource amounts (food, wood, stone, gold) for players in Random Map Scenarios (RMS).

```APIDOC
STARTING_VILLAGERS = 84
    - Purpose: Number of starting villagers
    - Default Values:
        - 3:  Default
        - 4:  Mayans
        - 6:  Chinese
    - Note: Only works for RMS, changing this manually in the editor does nothing

STARTING_FOOD = 91
    - Purpose: Starting food amount
    - Note: Only works for RMS, changing this manually in the editor does nothing but its a way to check starting food amount

STARTING_WOOD = 92
    - Purpose: Starting wood amount
    - Note: Only works for RMS, changing this manually in the editor does nothing but its a way to check starting wood amount

STARTING_STONE = 93
    - Purpose: Starting stone amount
    - Note: Only works for RMS, changing this manually in the editor does nothing but its a way to check starting stone amount

STARTING_GOLD = 94
    - Purpose: Starting gold amount
    - Note: Only works for RMS, changing this manually in the editor does nothing but its a way to check starting gold amount
```

--------------------------------

### AoE2Scenario Initialization and Callbacks

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/aoe2_scenario

Handles the initialization of an AoE2Scenario object, including setting game versions, source locations, and registering callbacks for write operations. It also manages scenario metadata and actions.

```Python
class AoE2Scenario:
    def on_write(self, func: Func) -> Func:
        """Register a function to be called on write (intended to be used as a decorator)"""
        self._on_write_funcs.append(func)
        return func

    @property
    def scenario_version_tuple(self) -> tuple[int, ...]:
        return tuple(map(int, self.scenario_version.split('.')))

    def __init__(
            self,
            game_version: str,
            scenario_version: str,
            source_location: str,
            name: str,
            variant: ScenarioVariant | None = None
    ):
        # Scenario meta info
        self.game_version: str = game_version
        self.scenario_version: str = scenario_version
        self.source_location: str = source_location
        self._variant: ScenarioVariant | None = variant
        self._time_start: float = time.time()

        # Actual scenario content
        self.structure: Dict = {}
        self.sections: Dict[str, AoE2FileSection] = {}
        self._object_manager: AoE2ObjectManager | None = None

        # For Scenario Store functionality
        self.name: str = name
        self.uuid: UUID = uuid4()
        store.register_scenario(self)

        # Actions through the scenario
        self.new: ObjectFactory = ObjectFactory(self.uuid)
        self.actions: ScenarioActions = ScenarioActions(self.uuid)

        # Used in debug functions
        self._file = None
        self._file_header = None
        self._decompressed_file_data = None

        # Callbacks
        self._on_write_funcs = []
```

--------------------------------

### API Documentation: Settings

Source: https://ksneijders.github.io/AoE2ScenarioParser/getting_started

Provides API documentation for the Settings class, likely used for managing configuration or settings related to the scenario parser.

```APIDOC
Settings:
  __init__(settings_path: str = None)
    Initializes the Settings object.
    Parameters:
      settings_path: Optional path to a settings file.

  load_settings(settings_path: str)
    Loads settings from a specified file.

  get_setting(key: str, default: any = None) -> any
    Retrieves a specific setting by its key.
    Parameters:
      key: The key of the setting to retrieve.
      default: The default value to return if the key is not found.
    Returns: The value of the setting.

  set_setting(key: str, value: any)
    Sets a specific setting.
    Parameters:
      key: The key of the setting to set.
      value: The value to assign to the setting.
```

--------------------------------

### AoE2 Scenario Parser Trigger Examples

Source: https://ksneijders.github.io/AoE2ScenarioParser/examples/triggers

Examples demonstrating how to manipulate triggers within AoE2 scenarios using the parser. Includes functionalities like replacing sound names and importing triggers from other scenarios.

```Python
# Example: Replace all sound names with a specific name
# parser.triggers.replace_sound_names('new_sound.wav')

# Example: Importing all triggers from another scenario
# parser.triggers.import_triggers('path/to/other_scenario.aoe2scenario')
```

--------------------------------

### PanelLocation Dataset Documentation

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/starting_age

API documentation for the PanelLocation dataset, detailing its structure and usage within the AoE2ScenarioParser.

```APIDOC
PanelLocation:
  Description: Represents the location of a panel in the Age of Empires II scenario editor.
```

--------------------------------

### Set Default Starting Resources

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/player/player_manager

Sets the default starting resources (food, wood, gold, stone) for specified players or all players. It includes a warning that this method does not account for civilization-specific bonuses.

```Python
def set_default_starting_resources(self, players: List[PlayerId] = None) -> None:
        """
        Sets the default starting resources for all players

        Warning: Does NOT take civilizations into account
            This does not take the current selected civ of this player into account. For example, a player with the
            Chinese civ selected will still be set to 200 food. Generally speaking, it's recommended to not use this for
            competitive, normal play. You can select `low` resources in the lobby menu to get 'normal' resources for
            every civ.

        Args:
            players: A list of players, defaults to all players (incl GAIA) when left out
        """
        if players is None:
            players = PlayerId.all()
        for player in players:
            self.players[player].food = 200
            self.players[player].wood = 200
            self.players[player].gold = 100
            self.players[player].stone = 200
```

--------------------------------

### TechInfo Dataset Documentation

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/starting_age

API documentation for the TechInfo dataset, providing details about technologies available in Age of Empires II.

```APIDOC
TechInfo:
  Description: Contains information about various technologies, their costs, prerequisites, and effects.
```

--------------------------------

### Get Villager Units

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/datasets/units

Retrieves a list of villager units, with options to exclude female or male villagers. This function categorizes villagers by gender and provides a clean way to get specific villager types.

```python
@staticmethod
def vils(
        exclude_female: bool = False,
        exclude_male: bool = False,
) -> List[UnitInfo]:
    """
    Args:
        exclude_female: if set to true, exclude the female villagers
        exclude_male: if set to true, exclude the male villagers

    Returns:
        A list of villager UnitInfo objects
    """
    villagers = {
        "base": {
            "male": [
                UnitInfo.VILLAGER_MALE,
                UnitInfo.VILLAGER_MALE_MONASTERY,
                UnitInfo.VILLAGER_MALE_BUILDER,
                UnitInfo.VILLAGER_MALE_FARMER,
                UnitInfo.VILLAGER_MALE_FISHERMAN,
                UnitInfo.VILLAGER_MALE_FORAGER,
                UnitInfo.VILLAGER_MALE_GOLD_MINER,
                UnitInfo.VILLAGER_MALE_HUNTER,
                UnitInfo.VILLAGER_MALE_LUMBERJACK,
                UnitInfo.VILLAGER_MALE_REPAIRER,
                UnitInfo.VILLAGER_MALE_SHEPHERD,
                UnitInfo.VILLAGER_MALE_STONE_MINER,
                UnitInfo.VILLAGER_MALE_OYSTER_GATHERER,
                UnitInfo.VILLAGER_MALE_HERDER,
            ],
            "female": [
                UnitInfo.VILLAGER_FEMALE,
                UnitInfo.VILLAGER_FEMALE_BUILDER,
                UnitInfo.VILLAGER_FEMALE_FARMER,
                UnitInfo.VILLAGER_FEMALE_FISHERMAN,
                UnitInfo.VILLAGER_FEMALE_FORAGER,
                UnitInfo.VILLAGER_FEMALE_GOLD_MINER,
                UnitInfo.VILLAGER_FEMALE_HUNTER,
                UnitInfo.VILLAGER_FEMALE_LUMBERJACK,
                UnitInfo.VILLAGER_FEMALE_REPAIRER,
                UnitInfo.VILLAGER_FEMALE_SHEPHERD,
                UnitInfo.VILLAGER_FEMALE_STONE_MINER,
                UnitInfo.VILLAGER_FEMALE_OYSTER_GATHERER,
                UnitInfo.VILLAGER_FEMALE_HERDER,
            ],
        },
    }

    units_to_return = []

    if not exclude_female:
        units_to_return.extend(villagers["base"]["female"])
    if not exclude_male:
        units_to_return.extend(villagers["base"]["male"])

    return units_to_return
```

--------------------------------

### Create and Load Section

Source: https://ksneijders.github.io/AoE2ScenarioParser/api_docs/aoe2_scenario

Initializes a file section by name and populates its retrievers with data from a generator. Logs progress and success.

```Python
def _create_and_load_section(self, name: str, igenerator: IncrementalGenerator) -> None:
        """
        Initialises a file section from its name and fills its retrievers with data from the given generator

        Args:
            name: The name of the file section
            igenerator: The generator to fill the data from

        Returns:
            An AoE2FileSection representing the given section name with its data initialised from the generator
        """
        s_print(f"\t🔄 Parsing {name}...", color="yellow")
        section = AoE2FileSection.from_structure(name, self.structure.get(name), self.uuid)
        self._add_to_sections(section)
        s_print(f"\t🔄 Gathering {name} data...", color="yellow")
        section.set_data_from_generator(igenerator)
        s_print(f"\t✔ {name}", final=True, color="green")
```
Tokens:
Raw