### Launcher Integration Example

Source: https://github.com/archipelagomw/archipelago/blob/main/docs/adding games.md

Example of how to integrate a Python client with the Archipelago Launcher. This function launches the client using `LauncherComponent.launch` and can be extended with arguments.

```python
def my_func(*args: str):
	from .client import run_client
	LauncherComponent.launch(run_client, name="My Client", args=args)
```

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

### Install Dependencies (Linux)

Source: https://github.com/archipelagomw/archipelago/blob/main/worlds/sm64ex/docs/setup_en.md

Installs required dependencies for compiling SM64EX on Linux. SM64EX will dynamically link jsoncpp if available, otherwise it links statically.

```bash
sdl2 glew cmake python make patch git
```

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

### Install .NET Runtime for Proton

Source: https://github.com/archipelagomw/archipelago/blob/main/worlds/dark_souls_3/docs/setup_en.md

When running on Linux with Proton, install the .NET Runtime under plain WINE. This is required for DS3Randomizer.exe to function.

```shell
dotnet-runtime-6.0
```

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

### YAML Example with Advanced Settings

Source: https://github.com/archipelagomw/archipelago/blob/main/worlds/generic/docs/advanced_settings_en.md

This example demonstrates the use of various advanced settings, including random number generation for option values and item pools, within a game configuration file.

```yaml
description: An example using various advanced options
name: Example Player
game: 
  A Link to the Past: 10
  Timespinner: 10
requires: 
  version: 0.6.4
  game:
      A Link to the Past: 0.6.4
A Link to the Past:
  accessibility: minimal
  progression_balancing: 50
  smallkey_shuffle:
    original_dungeon: 1
    any_world: 1
  crystals_needed_for_gt:
    random-low: 1
  crystals_needed_for_ganon:
    random-range-high-1-7: 1
  local_items:
    - Bombos
    - Ether
    - Quake
  non_local_items:
    - Moon Pearl
  start_inventory:
    Pegasus Boots: 1
    Bombs (3): 2
  start_hints:
    - Hammer
  start_location_hints:
    - Spike Cave
  exclude_locations:
    - Cave 45
  priority_locations:
    - Link's House
  item_links:
    - name: rods
      item_pool:
        - Fire Rod
        - Ice Rod
      replacement_item: "Rupee (1)"
      link_replacement: true
  triggers:
    - option_category: A Link to the Past
      option_name: smallkey_shuffle
      option_result: any_world
      options:
        A Link to the Past:
          bigkey_shuffle: any_world
          map_shuffle: any_world
          compass_shuffle: any_world
Timespinner:
  accessibility: minimal
  progression_balancing: 50
  item_links: # Share part of your item pool with other players.
    - name: TSAll
      item_pool:
        - Everything
      local_items:
        - Twin Pyramid Key
        - Timespinner Wheel
      replacement_item: null
      skip_if_solo: true

```

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

### Launch StarCraft 2 Client on macOS

Source: https://github.com/archipelagomw/archipelago/blob/main/worlds/sc2/docs/setup_en.md

Command to start the client when running from source on macOS.

```bash
python3 Starcraft2Client.py
```

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

### Install Dependencies (Windows MSYS2)

Source: https://github.com/archipelagomw/archipelago/blob/main/worlds/sm64ex/docs/setup_en.md

Installs necessary dependencies for compiling SM64EX on Windows using MSYS2. Ensure you are in a MinGW x64 shell.

```bash
pacman -Syuu

```

```bash
pacman -S unzip mingw-w64-x86_64-gcc mingw-w64-x86_64-glew mingw-w64-x86_64-SDL2 git make python3 mingw-w64-x86_64-cmake
```

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

### Full Rule Serialization Example

Source: https://github.com/archipelagomw/archipelago/blob/main/docs/rule builder.md

A comprehensive example demonstrating the serialization of a complex rule involving 'And', 'Or', 'Has', and 'CanReachRegion' rules with options.

```python
rule = And(
    Has("a", options=[OptionFilter(ToggleOption, 0)]),
    Or(Has("b", count=2), CanReachRegion("c"), options=[OptionFilter(ToggleOption, 1)]),
)
assert rule.to_dict() == {
    "rule": "And",
    "options": [],
    "children": [
        {
            "rule": "Has",
            "options": [
                {
                    "option": "worlds.my_world.options.ToggleOption",
                    "value": 0,
                    "operator": "eq",
                },
            ],
            "args": {
                "item_name": "a",
                "count": 1,
            },
        },
        {
            "rule": "Or",
            "options": [
                {
                    "option": "worlds.my_world.options.ToggleOption",
                    "value": 1,
                    "operator": "eq",
                },
            ],
            "children": [
                {
                    "rule": "Has",
                    "options": [],
                    "args": {
                        "item_name": "b",
                        "count": 2,
                    },
                },
                {
                    "rule": "CanReachRegion",
                    "options": [],
                    "args": {
                        "region_name": "c",
                    },
                },
            ],
        },
    ],
}
```

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

### Build AppImage Distribution

Source: https://github.com/archipelagomw/archipelago/blob/main/docs/running from source.md

After generating the binary distribution, use setup.py to create an AppImage in the 'dist/' directory. Requires appimagetool in the current directory.

```bash
python setup.py bdist_appimage
```

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

### Basic Trigger Example

Source: https://github.com/archipelagomw/archipelago/blob/main/worlds/generic/docs/triggers_en.md

This example shows a basic trigger that grants Rupees when a specific shop item slot count is met.

```yaml
triggers:
  - option_category: A Link to the Past
    option_name: shop_item_slots
    option_result: 15
    options:
      A Link to the Past:
        start_inventory:
          Rupees (300): 2
```

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

### Build Executable Distribution

Source: https://github.com/archipelagomw/archipelago/blob/main/docs/running from source.md

Use setup.py to generate a binary distribution of Archipelago in the 'build/' directory.

```bash
python setup.py build_exe
```

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

### Example WebWorld Options Presets

Source: https://github.com/archipelagomw/archipelago/blob/main/docs/world api.md

Demonstrates how to define presets for game options within the WebWorld class. These presets allow users to select predefined configurations for various game settings on the webhost.

```Python
# presets.py
options_presets = {
    "Limited Potential": {
        "progression_balancing":    0,
        "fairy_chests_per_zone":    2,
        "starting_class":           "random",
        "chests_per_zone":          30,
        "vendors":                  "normal",
        "architect":                "disabled",
        "gold_gain_multiplier":     "half",
        "number_of_children":       2,
        "free_diary_on_generation": False,
        "health_pool":              10,
        "mana_pool":                10,
        "attack_pool":              10,
        "magic_damage_pool":        10,
        "armor_pool":               5,
        "equip_pool":               10,
        "crit_chance_pool":         5,
        "crit_damage_pool":         5,
    }
}

```

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

### Get Request

Source: https://github.com/archipelagomw/archipelago/blob/main/docs/network protocol.md

Used to request single or multiple values from the server's data storage. A Get package will be answered with a Retrieved package.

```APIDOC
## POST /data/get

### Description
Used to request a single or multiple values from the server's data storage, see the [Set](#Set) package for how to write values to the data storage. A Get package will be answered with a [Retrieved](#Retrieved) package.

### Method
POST

### Endpoint
/data/get

### Request Body
- **keys** (list[str]) - Required - Keys to retrieve the values for.

Additional arguments sent in this package will also be added to the [Retrieved](#Retrieved) package it triggers.

### Special Keys
- **hints_{team}_{slot}** (list[Hint]) - All Hints belonging to the requested Player.
- **slot_data_{slot}** (dict[str, any]) - slot_data belonging to the requested slot.
- **item_name_groups_{game_name}** (dict[str, list[str]]) - item_name_groups belonging to the requested game.
- **location_name_groups_{game_name}** (dict[str, list[str]]) - location_name_groups belonging to the requested game.
- **client_status_{team}_{slot}** (ClientStatus) - The current game status of the requested player.
- **race_mode** (int) - 0 if race mode is disabled, and 1 if it's enabled.
```

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

### Configure EmuHawk ROM arguments

Source: https://github.com/archipelagomw/archipelago/blob/main/worlds/adventure/docs/setup_en.md

Example configuration for host.yaml to automatically load the Lua connector script when launching EmuHawk.

```yaml
rom_args: "--lua=C:/ProgramData/Archipelago/data/lua/connector_adventure.lua"
```

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

### World Class Docstring Example

Source: https://github.com/archipelagomw/archipelago/blob/main/docs/world api.md

Example of a docstring for a game world class, which will be displayed on the AP website. Docstrings must be triple-quoted and follow reST style.

```python
from worlds.AutoWorld import World


class MyGameWorld(World):
    """This is the description of My Game that will be displayed on the AP website."""
```

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

### Configure Archipelago Environment Variables

Source: https://github.com/archipelagomw/archipelago/blob/main/worlds/sc2/docs/setup_en.md

Set the StarCraft II installation path and locate the Archipelago AppImage file.

```bash
# FIXME Uncomment the following lines if experiencing issues with DXVK (like DDRAW.ddl does not exist)
#export WINEDLLOVERRIDES=d3d10core,d3d11,d3d12,d3d12core,d3d9,d3dcompiler_33,d3dcompiler_34,d3dcompiler_35,d3dcompiler_36,d3dcompiler_37,d3dcompiler_38,d3dcompiler_39,d3dcompiler_40,d3dcompiler_41,d3dcompiler_42,d3dcompiler_43,d3dcompiler_46,d3dcompiler_47,d3dx10,d3dx10_33,d3dx10_34,d3dx10_35,d3dx10_36,d3dx10_37,d3dx10_38,d3dx10_39,d3dx10_40,d3dx10_41,d3dx10_42,d3dx10_43,d3dx11_42,d3dx11_43,d3dx9_24,d3dx9_25,d3dx9_26,d3dx9_27,d3dx9_28,d3dx9_29,d3dx9_30,d3dx9_31,d3dx9_32,d3dx9_33,d3dx9_34,d3dx9_35,d3dx9_36,d3dx9_37,d3dx9_38,d3dx9_39,d3dx9_40,d3dx9_41,d3dx9_42,d3dx9_43,dxgi,nvapi,nvapi64
#export DXVK_ENABLE_NVAPI=1

# FIXME Replace with path to StarCraft II install folder
export SC2PATH="/home/user/Games/starcraft-ii/drive_c/Program Files (x86)/StarCraft II/"

# FIXME Set to directory which contains Archipelago AppImage file
PATH_TO_ARCHIPELAGO=

# Gets the latest version of Archipelago AppImage in PATH_TO_ARCHIPELAGO.
# If PATH_TO_ARCHIPELAGO is not set, this defaults to the directory containing
# this script file.
ARCHIPELAGO="$(ls ${PATH_TO_ARCHIPELAGO:-$(dirname $0)}/Archipelago_*.AppImage | sort -r | head -1)"

# Start the Archipelago client
$ARCHIPELAGO "Starcraft 2 Client"
```

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

### Install Linux Dependencies for Aquaria Randomizer

Source: https://github.com/archipelagomw/archipelago/blob/main/worlds/aquaria/docs/setup_en.md

Use this command to install necessary dependencies for the Aquaria randomizer on Debian-based Linux systems. This command requires sudo privileges.

```bash
sudo apt install liblua5.1-0-dev libogg-dev libvorbis-dev libopenal-dev libsdl2-dev
```

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

### Heretic In-Game Hinting Example

Source: https://github.com/archipelagomw/archipelago/blob/main/worlds/heretic/docs/setup_en.md

Example of how to use the in-game chat to hint for items in Heretic. The game supports both full location names and a simplified keyword-based approach.

```plaintext
!hint The River of Fire (E2M3) - Green key
```

```plaintext
!hint e2m3 green
```

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

### Connection Plando Examples

Source: https://github.com/archipelagomw/archipelago/blob/main/worlds/generic/docs/plando_en.md

Configure connection plando settings for games like A Link to the Past. Supports entrance, exit, direction, and percentage options for connections.

```yaml
plando_connections:
    # example block 1 - A Link to the Past
    - entrance: Cave Shop (Lake Hylia)
      exit: Cave 45
      direction: entrance
    - entrance: Cave 45
      exit: Cave Shop (Lake Hylia)
      direction: entrance
    - entrance: Agahnims Tower
      exit: Old Man Cave Exit (West)
      direction: exit
```

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

### Test Executable Setup

Source: https://github.com/archipelagomw/archipelago/blob/main/test/cpp/CMakeLists.txt

Defines the test executable, links Google Test libraries, and configures test environment properties.

```cmake
add_executable(test_default)

target_include_directories(test_default
        PRIVATE
        ${GTEST_INCLUDE_DIRS}
)

target_link_libraries(test_default
        ${GTEST_BOTH_LIBRARIES}
)

add_test(
        NAME test_default
        COMMAND  test_default
)

set_property(
        TEST test_default
        PROPERTY ENVIRONMENT "ASAN_OPTIONS=allocator_may_return_null=1"
)
```

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

### Tracker Data Response Example

Source: https://github.com/archipelagomw/archipelago/blob/main/docs/webhost api.md

Example JSON response structure returned by the /tracker/<suuid:tracker> endpoint. Note that the cache timer for this data is 60 seconds.

```json
{
  "aliases": [
    {
      "team": 0,
      "player": 1,
      "alias": "Incompetence"
    },
    {
      "team": 0,
      "player": 2,
      "alias": "Slot_Name_2"
    },
    {
      "team": 0,
      "player": 3,
      "alias": null
    },
  ],
  "player_items_received": [
    {
      "team": 0,
      "player": 1,
      "items": [
        [1, 1, 1, 0],
        [2, 2, 2, 1]
      ]
    },
    {
      "team": 0,
      "player": 2,
      "items": [
        [1, 1, 1, 2],
        [2, 2, 2, 0]
      ]
    }
  ],
  "player_checks_done": [
    {
      "team": 0,
      "player": 1,
      "locations": [
        1,
        2
      ]
    },
    {
      "team": 0,
      "player": 2,
      "locations": [
        1,
        2
      ]
    }
  ],
  "total_checks_done": [
    {
      "team": 0,
      "checks_done": 4
    }
  ],
  "hints": [
    {
      "team": 0,
      "player": 1,
      "hints": [
        [1, 2, 4, 6, 0, "", 4, 0]
      ]
    },
    {
      "team": 0,
      "player": 2,
      "hints": []
    }
  ],
  "activity_timers": [
    {
      "team": 0,
      "player": 1,
      "time": "Fri, 18 Apr 2025 20:35:45 GMT"
    },
    {
      "team": 0,
      "player": 2,
      "time": "Fri, 18 Apr 2025 20:42:46 GMT"
    }
  ],
  "connection_timers": [
    {
      "team": 0,
      "player": 1,
      "time": "Fri, 18 Apr 2025 20:38:25 GMT"
    },
    {
      "team": 0,
      "player": 2,
      "time": "Fri, 18 Apr 2025 21:03:00 GMT"
    }
  ],
  "player_status": [
    {
      "team": 0,
      "player": 1,
      "status": 0
    },
    {
      "team": 0,
      "player": 2,
      "status": 0
    }
  ]
}
```

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

### Connect to Archipelago via Command Line

Source: https://github.com/archipelagomw/archipelago/blob/main/worlds/doom_ii/docs/setup_en.md

Use the command line to launch the game with specific server and player connection parameters.

```bash
crispy-apdoom -game doom2 -apserver <server> -applayer <slot name>
```

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

### Typical YAML Structure

Source: https://github.com/archipelagomw/archipelago/blob/main/worlds/generic/docs/advanced_settings_en.md

Illustrates the basic structure of a YAML file with nested options and their corresponding weights. Use two spaces for indentation.

```yaml
root_option:
  nested_option_one:
    option_one_setting_one: 1
    option_one_setting_two: 0
  nested_option_two:
    option_two_setting_one: 14
    option_two_setting_two: 43
```

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

### Hinting in DOOM II

Source: https://github.com/archipelagomw/archipelago/blob/main/worlds/doom_ii/docs/setup_en.md

Examples of chat commands for requesting hints during gameplay.

```text
!hint Underhalls (MAP02) - Red keycard
```

```text
!hint map02 red
```

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

### Define NamedRange Options

Source: https://github.com/archipelagomw/archipelago/blob/main/docs/options api.md

Example of configuring a NamedRange with specific integer mappings.

```python
range_start = 1
range_end = 99
special_range_names = {
    "normal": 20,
    "extreme": 99,
    "unlimited": -1,
}
```