### Install Ubuntu on WSL

Source: https://github.com/pret/pokeplatinum/blob/main/INSTALL.md

Installs Ubuntu on Windows Subsystem for Linux. This command is run in PowerShell as Administrator.

```powershell
wsl --install -d Ubuntu
```

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

### Install Debian/Ubuntu Build Dependencies

Source: https://github.com/pret/pokeplatinum/blob/main/INSTALL.md

Install the required build tools and libraries using apt on Debian-based systems.

```bash
sudo apt install bison flex g++ gcc-arm-none-eabi git make ninja-build pkg-config wget python3 xz-utils nasm libc6:i386
```

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

### Install pre-commit and set up hooks

Source: https://github.com/pret/pokeplatinum/blob/main/CONTRIBUTING.md

Install pre-commit to manage project hooks and ensure consistent tooling versions across contributors. This is recommended for a smooth contribution experience.

```bash
python -m venv .venv
source .venv/bin/activate.sh
pip install pre-commit
```

```bash
pre-commit install
```

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

### VS Code / Editor Setup

Source: https://context7.com/pret/pokeplatinum/llms.txt

Instructions for setting up VS Code with a compilation database for IntelliSense and the clangd language server.

```APIDOC
## VS Code / Editor Setup

A compilation database is required for IntelliSense and the `clangd` language server. Generate it once after the first build, then configure `.vscode/c_cpp_properties.json`.

```bash
# Generate compile_commands.json (re-run after adding/removing source files)
python tools/devtools/gen_compile_commands.py
```

```json
// .vscode/c_cpp_properties.json
{
  "configurations": [
    {
      "name": "Linux",
      "includePath": [
        "${workspaceFolder}/build/**",
        "${workspaceFolder}/include/**"
      ],
      "forcedInclude": [ "${workspaceFolder}/include/pch/global_pch.h" ],
      "defines": [ "SDK_ARM9", "BOOL=int" ],
      "compilerPath": "/usr/bin/arm-none-eabi-gcc",
      "cStandard": "c99",
      "cppStandard": "c++17",
      "intelliSenseMode": "linux-gcc-arm",
      "compileCommands": "${workspaceFolder}/compile_commands.json"
    }
  ],
  "version": 4
}
```
```

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

### Install Build Dependencies on Ubuntu

Source: https://github.com/pret/pokeplatinum/blob/main/INSTALL.md

Installs essential build dependencies for the project on Ubuntu. This includes compilers, build tools, and libraries.

```bash
sudo apt install bison flex g++ gcc-arm-none-eabi git lib32z1 make ninja-build pkg-config python3 p7zip
```

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

### Show Diff Syntax in Tutorials

Source: https://github.com/pret/pokeplatinum/wiki/Tutorials

Tutorials may use diff syntax to indicate changes. Lines starting with '+' are additions, and lines starting with '-' are deletions.

```diff
this is some code
-delete - lines
+add + lines
```

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

### Install macOS Xcode Command Line Tools

Source: https://github.com/pret/pokeplatinum/blob/main/INSTALL.md

Install the necessary command line utilities provided by Apple for macOS development.

```zsh
xcode-select --install
```

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

### Verify clangd Installation

Source: https://github.com/pret/pokeplatinum/blob/main/docs/editor_setup/helix.md

Confirm that clangd is installed and accessible in your system's PATH by checking its version.

```bash
clangd --version
```

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

### Install Fedora Build Dependencies

Source: https://github.com/pret/pokeplatinum/blob/main/INSTALL.md

Install required build tools and libraries using dnf on Fedora and its derivatives.

```bash
sudo dnf install arm-none-eabi-gcc-cs bison flex gcc-c++ git make ninja-build python3 wget2 xz glibc32
```

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

### Clone and Build pokeplatinum ROM (Rev 1)

Source: https://context7.com/pret/pokeplatinum/llms.txt

Clone the repository, install dependencies, and build the default Rev 1 ROM. Run 'make check' to verify the SHA-1 hash.

```bash
git clone https://github.com/pret/pokeplatinum
cd pokeplatinum

sudo dpkg --add-architecture i386 && sudo apt update
sudo apt install bison flex g++ gcc-arm-none-eabi git make ninja-build \ 
    pkg-config wget python3 xz-utils nasm libc6:i386

make

ROM_REVISION=0 make

make check

make debug
```

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

### Install macOS Dependencies with Homebrew

Source: https://github.com/pret/pokeplatinum/blob/main/INSTALL.md

Update Homebrew and install required build tools and libraries for macOS.

```zsh
brew update
brew install gcc@14 ninja libpng pkg-config arm-none-eabi-gcc xz
brew install --cask wine-stable
```

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

### Constructing a New Archive

Source: https://github.com/pret/pokeplatinum/blob/main/tools/nitroarc/doc/nitroarc.3.adoc

Example demonstrating how to construct a new Nitro Archive with custom memory allocation.

```APIDOC
## Constructing a New Archive

### Description
This example illustrates how to create a new Nitro Archive by packing multiple files into it, using custom memory allocation functions.

### Code
```c
#include <stdint.h>
#include <stdlib.h>
#include <nitroarc.h>

static void* libc_malloc(void *ctx, unsigned items, unsigned size) {
    return malloc(items * size);
}

static void libc_free(void *ctx, void *ptr, unsigned items, unsigned size) {
    free(ptr);
}

static void* libc_realloc(void *ctx, void *ptr, unsigned items, unsigned size) {
    return realloc(ptr, items * size);
}

extern int read_file(const char *filename, char **out_data, uint32_t *out_size);
extern int write_file(const char *filename, const char *data, uint32_t size);

static void make_archive(const char *target, const char **members, int count) {
    nitroarc_packer_t packer;
    packer.malloc  = libc_malloc;
    packer.realloc = libc_realloc;
    packer.free    = libc_free;

    char    *data = NULL;
    uint32_t size = 0;

    nitroarc_pinit(&packer, count, false, false);

    for (int i = 0; i < count; i++) {
        load_file(members[i], &data, &size);
        nitroarc_ppack(&packer, data, size, members[i]);
        free(data);
    }

    nitroarc_pseal(&packer, &data, &size);
    write_file(target, data, size);
    free(data);
}
```
```

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

### Enable 32-bit Architecture on Debian/Ubuntu

Source: https://github.com/pret/pokeplatinum/blob/main/INSTALL.md

Prepare Debian-based systems for 32-bit package installations before updating the package list.

```bash
sudo dpkg --add-architecture i386 && sudo apt update
```

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

### Pre-commit and Clang-format Setup (Bash)

Source: https://context7.com/pret/pokeplatinum/llms.txt

Commands to set up pre-commit hooks for automatic code formatting with clang-format. This ensures consistent code style across the project.

```bash
python -m venv .venv
source .venv/bin/activate
pip install pre-commit
pre-commit install        # installs git hooks; formatting runs on every commit

# Or, format the whole tree manually at any time:
make format
```

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

### Install MSYS2 Build Dependencies

Source: https://github.com/pret/pokeplatinum/blob/main/INSTALL.md

After updating the package registry, execute these commands to add the mingw64 bin directory to your PATH and install essential build tools.

```bash
echo 'export PATH=${PATH}:/mingw64/bin' >> ~/.bashrc
source ~/.bashrc
pacman -S bison flex gcc git make ninja python mingw-w64-x86_64-arm-none-eabi-gcc p7zip
```

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

### Install Arch Linux Build Dependencies

Source: https://github.com/pret/pokeplatinum/blob/main/INSTALL.md

Install necessary build tools and libraries using pacman on Arch Linux, ensuring the multilib repository is enabled.

```bash
sudo pacman -S arm-none-eabi-gcc bison flex gcc git make ninja python wget xz lib32-glibc
```

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

### pre-commit / clang-format Integration

Source: https://context7.com/pret/pokeplatinum/llms.txt

Guide to integrating clang-format for code formatting using pre-commit hooks and manual formatting commands.

```APIDOC
## pre-commit / clang-format Integration

Pin the exact `clang-format` version used in CI by installing `pre-commit` into a local virtual environment.

```bash
python -m venv .venv
source .venv/bin/activate
pip install pre-commit
pre-commit install        # installs git hooks; formatting runs on every commit

# Or, format the whole tree manually at any time:
make format
```
```

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

### Run Persistent Wine Server

Source: https://github.com/pret/pokeplatinum/blob/main/INSTALL.md

Start a Wine server in the background to potentially speed up builds on macOS. This may require a manual restart of 'make' if it hangs.

```zsh
wineserver -p
```

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

### Read Archive Example

Source: https://github.com/pret/pokeplatinum/blob/main/tools/nitroarc/doc/nitroarc.3.adoc

Demonstrates how to read an existing Nitro Archive from a file stream. Assumes an external function `read_file` exists to load file content into memory.

```c
#include <stdint.h>
#include <nitroarc.h>

extern int read_file(const char *filename, char **out_data, uint32_t *out_size);

static nitroarc_t read_archive(const char *target) {
    nitroarc_t archive;
    char      *data = NULL;
    uint32_t   size = 0;

    read_file(target, &data, &size);
    nitroarc_read(data, size, &archive);
    return archive;
}
```

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

### Construct New Archive Example

Source: https://github.com/pret/pokeplatinum/blob/main/tools/nitroarc/doc/nitroarc.3.adoc

Illustrates how to construct a new Nitro Archive using a custom memory allocation interface. It defines standard C library wrappers for malloc, realloc, and free.

```c
#include <stdint.h>
#include <stdlib.h>
#include <nitroarc.h>

static void* libc_malloc(void *ctx, unsigned items, unsigned size) {
    return malloc(items * size);
}

static void libc_free(void *ctx, void *ptr, unsigned items, unsigned size) {
    free(ptr);
}

static void* libc_realloc(void *ctx, void *ptr, unsigned items, unsigned size) {
    return realloc(ptr, items * size);
}

extern int read_file(const char *filename, char **out_data, uint32_t *out_size);
extern int write_file(const char *filename, const char *data, uint32_t size);

static void make_archive(const char *target, const char **members, int count) {
    nitroarc_packer_t packer;
    packer.malloc  = libc_malloc;
    packer.realloc = libc_realloc;
    packer.free    = libc_free;

    char    *data = NULL;
    uint32_t size = 0;

    nitroarc_pinit(&packer, count, false, false);

    for (int i = 0; i < count; i++) {
        load_file(members[i], &data, &size);
        nitroarc_ppack(&packer, data, size, members[i]);
        free(data);
    }

    nitroarc_pseal(&packer, &data, &size);
    write_file(target, data, size);
    free(data);
}
```

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

### Configure nvim-treesitter

Source: https://github.com/pret/pokeplatinum/blob/main/docs/editor_setup/neovim.md

Integrate nvim-treesitter for improved C/C++ parsing and syntax highlighting by adding this configuration to your init.lua. It ensures the C and C++ parsers are installed and enables highlighting and indentation.

```lua
require("lazy").setup({
  -- <previous configuration above this line>
  {
    "nvim-treesitter/nvim-treesitter",
    build = ":TSUpdate",
    config = function()
      local configs = require("nvim-treesitter.configs")
      configs.setup({
        ensure_installed = {
          "c",
          "cpp",
        },
        sync_install = false,
        highlight = { enable = true },
        indent = { enable = true },
      })
    end
  }
})
```

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

### Build and Check Project

Source: https://github.com/pret/pokeplatinum/blob/main/CONTRIBUTING.md

Run this command to ensure your development environment is set up correctly and the project builds successfully.

```bash
make check
```

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

### Configure C/C++ Project Properties

Source: https://github.com/pret/pokeplatinum/blob/main/docs/editor_setup/visual_studio_code.md

This JSON configuration file sets up IntelliSense for the C/C++ extension. Ensure the 'name' and 'intelliSenseMode' properties match your platform.

```json
{
  "configurations": [
    {
      "name": "Linux",
      "includePath": [
        "${workspaceFolder}/build/**",
        "${workspaceFolder}/include/**"
      ],
      "forcedInclude": [ "${workspaceFolder}/include/pch/global_pch.h" ],
      "defines": [ "SDK_ARM9", "BOOL=int" ],
      "compilerPath": "/usr/bin/arm-none-eabi-gcc",
      "cStandard": "c99",
      "cppStandard": "c++17",
      "intelliSenseMode": "linux-gcc-arm",
      "compileCommands": "${workspaceFolder}/compile_commands.json"
    }
  ],
  "version": 4
}
```

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

### 2D Background Initialization (C)

Source: https://context7.com/pret/pokeplatinum/llms.txt

C code demonstrating the initialization and configuration of 2D backgrounds using the BgSystem API. It covers setting up templates, filling tilemaps, and scheduling updates.

```c
#include "bg_system.h"

// Define a background template in ROM
static const BgTemplate sBgTemplate = {
    .x          = 0,
    .y          = 0,
    .bufferSize = 0x800,
    .baseTile   = 0,
    .screenSize = 0,
    .colorMode  = 0,          // 16-color mode
    .screenBase = 1,
    .charBase   = 0,
    .bgExtPltt  = 0,
    .priority   = 0,
    .areaOver   = 0,
    .dummy      = 0,
    .mosaic     = FALSE,
};

void MyScreen_Init(BgConfig *bgConfig)
{
    // Initialize a static background on layer 0 using the template
    Bg_InitFromTemplate(bgConfig, 0, &sBgTemplate, BG_TYPE_STATIC);

    // Fill the tilemap with tile 0 immediately (commits to VRAM now)
    Bg_FillTilemap(bgConfig, 0, 0x0000);

    // Schedule a deferred fill — VRAM is not touched until Bg_RunScheduledUpdates
    Bg_ScheduleFillTilemap(bgConfig, 0, 0x0000);

    // Scroll the background
    Bg_SetScroll(bgConfig, 0, BG_SCROLL_X, 16);
    Bg_SetScroll(bgConfig, 0, BG_SCROLL_Y, 0);

    // Commit all scheduled scroll + transfer operations at VBlank
    Bg_RunScheduledUpdates(bgConfig);
}
```

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

### Update Ubuntu Package Registry

Source: https://github.com/pret/pokeplatinum/blob/main/INSTALL.md

Updates the package list and upgrades installed packages on Ubuntu. This should be run after initial installation or upgrade.

```bash
sudo apt update && sudo apt upgrade
```

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

### Install GNU coreutils on Older macOS

Source: https://github.com/pret/pokeplatinum/blob/main/INSTALL.md

If using macOS Monterey (12) or earlier, install GNU coreutils for build script compatibility.

```zsh
brew install coreutils
```

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

### Configure nvim-lspconfig for clangd

Source: https://github.com/pret/pokeplatinum/blob/main/docs/editor_setup/neovim.md

Add this configuration to your init.lua to set up the clangd language server with nvim-lspconfig. It defines how clangd identifies project roots and the commands to launch it with specific options.

```lua
require("lazy").setup({
  -- <previous configuration above this line>
  {
    "neovim/nvim-lspconfig",
    opts = {
      servers = {
        clangd = {
          root_dir = function(fname)
            return require("lspconfig.util").root_pattern(
              "Makefile",
              "build.ninja",
              "CMakeLists.txt",
              "compile_commands.json",
              "compile_flags.txt",
              "configure.ac",
              "configure.in",
              "config.h.in",
              "meson.build",
              "meson.options",
            )(fname) or require("lspconfig.util").find_git_ancestor(fname)
          end,
          cmd = {
            "clangd",
            "--background-index",
            "--clang-tidy",
            "--header-insertion=iwyu",
            "--completion-style=detailed",
            "--function-arg-placeholders",
            "--fallback-style=llvm",
          },
          init_options = {
            usePlaceholders = true,
            completeUnimported = true,
            clangdFileStatus = true,
          },
        },
      },
    },
  },
})
```

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

### Build PokePlatinum ROM

Source: https://github.com/pret/pokeplatinum/blob/main/INSTALL.md

Run this command to build the standard PokePlatinum ROM. Ensure you are in the repository's root directory.

```bash
make
```

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

### Add Remote Repository and Set Origin

Source: https://github.com/pret/pokeplatinum/blob/main/CONTRIBUTING.md

Configure your local repository to interact with the official 'pret/pokeplatinum' repository and your personal fork. This is a necessary step before pushing changes.

```bash
git remote add pret https://github.com/pret/pokeplatinum.git
git remote set-url origin https://github.com/<YOUR_USER>/pokeplatinum.git
```

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

### Decoding an Existing Archive

Source: https://github.com/pret/pokeplatinum/blob/main/tools/nitroarc/doc/nitroarc.3.adoc

Example demonstrating how to read and decode an existing Nitro Archive from a file stream.

```APIDOC
## Decoding an Existing Archive

### Description
This example shows how to read a Nitro Archive from a file and decode it into a usable structure.

### Code
```c
#include <stdint.h>
#include <nitroarc.h>

extern int read_file(const char *filename, char **out_data, uint32_t *out_size);

static nitroarc_t read_archive(const char *target) {
    nitroarc_t archive;
    char      *data = NULL;
    uint32_t   size = 0;

    read_file(target, &data, &size);
    nitroarc_read(data, size, &archive);
    return archive;
}
```
```

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

### Update MSYS2 Package Registry

Source: https://github.com/pret/pokeplatinum/blob/main/INSTALL.md

Run this command after installing MSYS2 to update its package registry. Confirm with 'Y' when prompted.

```bash
pacman -Syu
```

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

### Define Starter Pokemon Species

Source: https://github.com/pret/pokeplatinum/wiki/Tutorial:-Changing-Starter-Pokemon

Modify these defines in `src/choose_starter/choose_starter_app.c` to change the species of the starter Pokemon.

```diff
#include "vram_transfer.h"

#define NUM_STARTER_OPTIONS 3
- #define STARTER_OPTION_0    SPECIES_TURTWIG
- #define STARTER_OPTION_1    SPECIES_CHIMCHAR
- #define STARTER_OPTION_2    SPECIES_PIPLUP
+ #define STARTER_OPTION_0    SPECIES_BULBASAUR
+ #define STARTER_OPTION_1    SPECIES_CHARMANDER
+ #define STARTER_OPTION_2    SPECIES_SQUIRTLE

#define OAM_MAIN_START 0
#define OAM_MAIN_END   128

```

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

### Initial Map Loading Flowchart

Source: https://github.com/pret/pokeplatinum/blob/main/docs/maps/loading_maps.md

This flowchart illustrates the sequence of operations involved in the initial loading of maps, including initialization of various managers and data structures, loading of textures, models, and animations, and the final callback for map loading.

```mermaid
flowchart TD
    start(Initial loading starts)
    init_map_prop_animation_managers[Initialize map prop animations managers]
    init_area_data_manager[Initialize area data structures]

    load_map_tex_set[Load map textures]
    load_map_areabm_texset[Load map props textures]
    load_map_prop_models[Load map prop models]
    load_map_prop_animations[Load map prop animations]
    load_map_prop_matshp[Load map prop materials & shapes]

    init_loaded_maps[Initialize loaded maps quadrants]
    done_loading_map@{ shape: diamond, label: "Finished loading \n all 4 maps?" }

    init_bdhc[Initialize BDHC data structures]
    load_terrain_attributes[Load terrain attributes]
    load_map_props[Load map props]
    load_map_model[Load map base 3D model]
    load_bdhc[Load BDHC data]
    call_map_loaded_callback[Call the map loaded callback]

    start --> init_map_prop_animation_managers
    init_map_prop_animation_managers --> init_area_data_manager
    init_area_data_manager --> load_area_data

    subgraph load_area_data[Load area data]
        direction LR
        load_map_tex_set --> load_map_areabm_texset
        load_map_areabm_texset --> load_map_prop_models
        load_map_prop_models --> load_map_prop_animations
        load_map_prop_animations --> load_map_prop_matshp
    end

    load_area_data --> load_land_data

    subgraph load_land_data[Load map data]
        direction LR
        init_loaded_maps --> load_land_data_single

        subgraph load_land_data_single[Load data of a single map]
        direction LR
            init_bdhc --> load_terrain_attributes
            load_terrain_attributes --> load_map_props
            load_map_props --> load_map_model
            load_map_model --> load_bdhc
            load_bdhc --> call_map_loaded_callback
        end

        load_land_data_single --> done_loading_map
        done_loading_map -->|No| load_land_data_single
    end
```

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

### Accessing Map Header at Runtime

Source: https://context7.com/pret/pokeplatinum/llms.txt

Example of how to retrieve a map header at runtime using the MapHeader_Get function with a specific map header ID.

```c
// Accessing a map header at runtime
const MapHeader *header = MapHeader_Get(MAP_HEADER_JUBILIFE_CITY);

```

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

### Lightweight Logging System in C

Source: https://context7.com/pret/pokeplatinum/llms.txt

Utilize EmulatorLog for prefixed, newline-terminated logs and EmulatorPrintf for raw output. Enabled via 'make debug' or '-Dlogging_enabled=true'.

```c
#include "debug.h"

void SomeSubsystem_Update(int frameCount)
{
    // EmulatorLog prepends "[GAME_LOG] " and appends "\n"
    EmulatorLog("SomeSubsystem_Update called on frame %d", frameCount);

    int hp = 42;
    EmulatorLog("Player HP: %d", hp);

    // EmulatorPrintf is a raw printf with no prefix or newline added
    EmulatorPrintf("raw value = 0x%08X\n", 0xDEADBEEF);
}
// Emulator output:
// [GAME_LOG] SomeSubsystem_Update called on frame 1
// [GAME_LOG] Player HP: 42
// raw value = 0xDEADBEEF
```

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

### Configure Meson Language Server for Neovim

Source: https://github.com/pret/pokeplatinum/blob/main/docs/editor_setup/neovim.md

Add this configuration to your init.lua to enable mesonlsp support within nvim-lspconfig. It specifies the root directory detection and command to run the language server.

```lua
require("lazy").setup({
  -- <previous configuration above this line>
  {
    "neovim/nvim-lspconfig",
    opts = {
      servers = {
        -- <previous configuration above this line>
        mesonlsp = {
          root_dir = function(fname)
            return require("lspconfig.util").root_pattern(
              "meson.build",
              "meson.options",
              "meson_options.txt",
            )(fname) or require("lspconfig.util").find_git_ancestor(fname)
          end,
          cmd = { 'mesonlsp', '--lsp', },
          filetypes = { 'meson' },
        },
      },
    },
  },
})
```

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

### Upgrade Existing Ubuntu WSL Install

Source: https://github.com/pret/pokeplatinum/blob/main/INSTALL.md

Upgrades existing packages and performs a full system upgrade on Ubuntu. This is part of the process to update older Ubuntu versions to a more recent, supported version.

```bash
sudo apt upgrade && sudo apt full-upgrade
```

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

### Generated Enum from Text File

Source: https://github.com/pret/pokeplatinum/blob/main/CONTRIBUTING.md

Example of how a text file containing constants is transformed into a C enum or preprocessor definitions. This allows a single source of truth for values used in both C and assembly.

```text
DAY_OF_WEEK_SUNDAY
DAY_OF_WEEK_MONDAY
DAY_OF_WEEK_TUESDAY
DAY_OF_WEEK_WEDNESDAY
DAY_OF_WEEK_THURSDAY
DAY_OF_WEEK_FRIDAY
DAY_OF_WEEK_SATURDAY
```

```c
#ifdef POKEPLATINUM_GENERATED_ENUM

enum DayOfWeek {
    DAY_OF_WEEK_SUNDAY    = 0,
    DAY_OF_WEEK_MONDAY    = 1,
    DAY_OF_WEEK_TUESDAY   = 2,
    DAY_OF_WEEK_WEDNESDAY = 3,
    DAY_OF_WEEK_THURSDAY  = 4,
    DAY_OF_WEEK_FRIDAY    = 5,
    DAY_OF_WEEK_SATURDAY  = 6,
}; /* enum DayOfWeek */

#else

#define DAY_OF_WEEK_SUNDAY    0
#define DAY_OF_WEEK_MONDAY    1
#define DAY_OF_WEEK_TUESDAY   2
#define DAY_OF_WEEK_WEDNESDAY 3
#define DAY_OF_WEEK_THURSDAY  4
#define DAY_OF_WEEK_FRIDAY    5
#define DAY_OF_WEEK_SATURDAY  6

#endif /* POKEPLATINUM_GENERATED_ENUM */
```

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

### Bug Fixes: Diff Format for ROM Hacks

Source: https://context7.com/pret/pokeplatinum/llms.txt

Examples of bug fixes documented in diff format, applicable as ROM hacks or for merging into contributions. These address issues in battle engine logic, AI scoring, encounter mechanics, and VRAM management.

```diff
// --- Acid Rain (battle engine) ---
// BUG: Pursuit subtracts the fainted battler ID from the field-condition bitmask
// instead of storing the ID into BTLVAR_FAINTED_MON, corrupting weather state.
-    UpdateVarFromVar OPCODE_SUB_TO_ZERO, BTLVAR_FIELD_CONDITIONS, BTLVAR_SCRIPT_TEMP
+    UpdateVarFromVar OPCODE_SET, BTLVAR_FAINTED_MON, BTLVAR_SCRIPT_TEMP

// --- Post-KO Switch-In AI Scoring Overflow ---
// BUG: Score variables are u8, overflowing on quad-effective matchups (score 320 → 65).
-    u8 score, maxScore;
+    u32 score, maxScore;

// --- Fishing Encounters Ignore Sticky Hold / Suction Cups ---
// BUG: Expression result is discarded instead of assigned.
-                v0 * 2;
+                v0 *= 2;

// --- Defog HM Uses Water Palette ---
-        .paletteID = tm_water_NCLR,
+        .paletteID = tm_flying_NCLR,

// --- Invalid VRAM Manager Type in G3DPipeline_InitEx ---
// BUG: Allocates a texture VRAM manager instead of palette VRAM manager.
- NNS_GfdInitFrmTexVramManager(plttVramSize * PALETTE_VRAM_BLOCK_SIZE, TRUE);
+ NNS_GfdInitFrmPlttVramManager(plttVramSize * PALETTE_VRAM_BLOCK_SIZE, TRUE);

```

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

### 2D Rendering: Background API (`BgConfig`)

Source: https://context7.com/pret/pokeplatinum/llms.txt

Details on using the `BgConfig` API for 2D background rendering, including initialization, tilemap manipulation, and scrolling.

```APIDOC
## 2D Rendering: Background API (`BgConfig`)

Game Freak's 2D wrapping layer around the NitroSDK restricts the DS's seven background modes to three named types and provides a `BgTemplate` struct for ROM-stored layout presets. Scheduled update variants defer VRAM writes until the next VBlank, reducing tearing.

```c
#include "bg_system.h"

// Define a background template in ROM
static const BgTemplate sBgTemplate = {
    .x          = 0,
    .y          = 0,
    .bufferSize = 0x800,
    .baseTile   = 0,
    .screenSize = 0,
    .colorMode  = 0,          // 16-color mode
    .screenBase = 1,
    .charBase   = 0,
    .bgExtPltt  = 0,
    .priority   = 0,
    .areaOver   = 0,
    .dummy      = 0,
    .mosaic     = FALSE,
};

void MyScreen_Init(BgConfig *bgConfig)
{
    // Initialize a static background on layer 0 using the template
    Bg_InitFromTemplate(bgConfig, 0, &sBgTemplate, BG_TYPE_STATIC);

    // Fill the tilemap with tile 0 immediately (commits to VRAM now)
    Bg_FillTilemap(bgConfig, 0, 0x0000);

    // Schedule a deferred fill — VRAM is not touched until Bg_RunScheduledUpdates
    Bg_ScheduleFillTilemap(bgConfig, 0, 0x0000);

    // Scroll the background
    Bg_SetScroll(bgConfig, 0, BG_SCROLL_X, 16);
    Bg_SetScroll(bgConfig, 0, BG_SCROLL_Y, 0);

    // Commit all scheduled scroll + transfer operations at VBlank
    Bg_RunScheduledUpdates(bgConfig);
}
```
```

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

### Clone the pokeplatinum Repository

Source: https://github.com/pret/pokeplatinum/blob/main/INSTALL.md

Download the project source code from GitHub and navigate into the newly created directory.

```bash
git clone https://github.com/pret/pokeplatinum
cd pokeplatinum
```

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

### 3D Model Loading and Drawing (C)

Source: https://context7.com/pret/pokeplatinum/llms.txt

C code demonstrating the usage of the Easy3D system for initializing the 3D graphics pipeline, loading models from NARC archives, and drawing them with specified transformations.

```c
#include "easy3d.h"

Easy3DModel  gMyModel;

void My3DScene_Init(void)
{
    // Set up a 3D graphics state (must be done before any draw calls)
    Easy3D_Init();

    // Load model from a NARC archive (index, member)
    Easy3DModel_Load(&gMyModel, NARC_INDEX_DEMO__TITLE__TITLEDEMO, 1, HEAP_ID_FIELD1);
}

void My3DScene_Draw(fx32 x, fx32 y, fx32 z)
{
    VecFx32 pos = { x, y, z };
    VecFx32 scale = { FX32_CONST(1.0), FX32_CONST(1.0), FX32_CONST(1.0) };

    // Draw the model with an explicit position and scale (no object wrapper)
    Easy3DModel_Draw(&gMyModel, &pos, &scale, 0);
}

void My3DScene_Free(void)
{
    Easy3DModel_Free(&gMyModel);
    Easy3D_Shutdown();
}
```

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

### Load Model, Animations, and Bind to Easy3DObject

Source: https://github.com/pret/pokeplatinum/blob/main/docs/3d_rendering.md

Loads a model, its associated model animation, and texture animation from a NARC archive, then binds them to an Easy3DObject. An allocator is required for animations.

```c
// Open the title NARC
NARC *narc = NARC_ctor(NARC_INDEX_DEMO__TITLE__TITLEDEMO, HEAP_ID_FIELD1);

// Load the model from the title screen NARC. Member index 1 is the model data.
// There is also Easy3DModel_Load which takes a NARC index and a member index.
Easy3DModel_LoadFrom(&giratinaModel, narc, 1, HEAP_ID_FIELD1);
Easy3DObject_Init(&giratinaObj, &giratinaModel);

// Initialize the Allocator used by the animations
HeapExp_FndInitAllocator(&allocator, HEAP_ID_FIELD1, 4);

// Load the model animation with member index 2.
Easy3DAnim_LoadFrom(&giratinaModelAnim, &giratinaModel, narc, 2, HEAP_ID_FIELD1, &allocator);
// Bind the animation to the object
Easy3DObject_AddAnim(&giratinaObj, &giratinaModelAnim);

// Do the same for the texture animation
Easy3DAnim_LoadFrom(&giratinaTexAnim, &giratinaModel, narc, 0, HEAP_ID_FIELD1, &allocator);
Easy3DObject_AddAnim(&giratinaObj, &giratinaTexAnim);

NARC_dtor(narc);
```

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

### GDB Debugging: Build and Launch Commands

Source: https://context7.com/pret/pokeplatinum/llms.txt

Bash commands for building a debug-enabled ROM and setting up VS Code for GDB debugging. Requires a patched binutils-gdb fork for NDS overlay support.

```bash
# Build a debug-enabled ROM (enables GDB stub + EmulatorLog)
make debug

# The build produces build/debug.nef alongside the ROM.
# Use the .vscode/launch.json template to connect VS Code's debugger.
# Requires: https://github.com/joshua-smith-12/binutils-gdb-nds

```

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

### Load and Update Easy3DObject for Giratina

Source: https://context7.com/pret/pokeplatinum/llms.txt

Loads a 3D model, its bone animation, and texture animation, then updates its position, visibility, scale, and rotation for rendering. Requires NARC archive and allocator initialization.

```c
#include "easy3d_object.h"
#include "narc.h"

Easy3DObject  gGiratinaObj;
Easy3DModel   gGiratinaModel;
Easy3DAnim    gGiratinaModelAnim;
Easy3DAnim    gGiratinaTexAnim;
NNSFndAllocator gAllocator;

void GiratinaScene_Load(void)
{
    // Open NARC archive
    NARC *narc = NARC_ctor(NARC_INDEX_DEMO__TITLE__TITLEDEMO, HEAP_ID_FIELD1);

    // Load model (member 1) and initialize object wrapper
    Easy3DModel_LoadFrom(&gGiratinaModel, narc, 1, HEAP_ID_FIELD1);
    Easy3DObject_Init(&gGiratinaObj, &gGiratinaModel);

    // Initialize the allocator required by the animation system
    HeapExp_FndInitAllocator(&gAllocator, HEAP_ID_FIELD1, 4);

    // Load and bind bone animation (member 2)
    Easy3DAnim_LoadFrom(&gGiratinaModelAnim, &gGiratinaModel, narc, 2,
                        HEAP_ID_FIELD1, &gAllocator);
    Easy3DObject_AddAnim(&gGiratinaObj, &gGiratinaModelAnim);

    // Load and bind texture animation (member 0)
    Easy3DAnim_LoadFrom(&gGiratinaTexAnim, &gGiratinaModel, narc, 0,
                        HEAP_ID_FIELD1, &gAllocator);
    Easy3DObject_AddAnim(&gGiratinaObj, &gGiratinaTexAnim);

    NARC_dtor(narc);
}

void GiratinaScene_Update(const FieldSystem *fieldSystem)
{
    // Position at the player's location
    const VecFx32 *pos = PlayerAvatar_PosVector(fieldSystem->playerAvatar);
    Easy3DObject_SetPosition(&gGiratinaObj, pos->x, pos->y, pos->z);
    Easy3DObject_SetVisibility(&gGiratinaObj, TRUE);
    Easy3DObject_SetScale(&gGiratinaObj, FX32_CONST(0.5), FX32_CONST(0.5), FX32_CONST(0.5));

    // Rotate on Y axis each frame
    u16 angle = Easy3DObject_GetRotation(&gGiratinaObj, ROTATION_AXIS_Y);
    angle = (angle + 100) % 0xFFFF;
    Easy3DObject_SetRotation(&gGiratinaObj, angle, ROTATION_AXIS_Y);

    // Advance animations by one frame (looping)
    Easy3DAnim_UpdateLooped(&gGiratinaModelAnim, FX32_ONE);
    Easy3DAnim_UpdateLooped(&gGiratinaTexAnim,   FX32_ONE);

    // Render
    Easy3DObject_Draw(&gGiratinaObj);
}

```

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

### Contributing: Submitting a Pull Request

Source: https://context7.com/pret/pokeplatinum/llms.txt

Steps for forking the repository, setting up remotes, creating feature branches, verifying builds, and submitting a pull request.

```APIDOC
## Contributing: Submitting a Pull Request

```bash
# Fork the repo on GitHub, then configure remotes
git remote add pret https://github.com/pret/pokeplatinum.git
git remote set-url origin https://github.com/<YOUR_USER>/pokeplatinum.git

# Create a feature branch
git checkout -b my-feature-branch

# Verify your build produces a matching ROM before opening a PR
make check   # must print OK

# Push to your fork and open a PR on GitHub
git push -u origin my-feature-branch
```
```

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

### Generate Compilation Database

Source: https://github.com/pret/pokeplatinum/blob/main/docs/editor_setup/helix.md

Run this command from the project root to generate the compile_commands.json file, which clangd uses to understand project compilation.

```bash
python tools/devtools/gen_compile_commands.py
```

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

### Update Starter Pokemon Descriptions

Source: https://github.com/pret/pokeplatinum/wiki/Tutorial:-Changing-Starter-Pokemon

Edit the `res/text/unk_0360.json` file to reflect the new starter Pokemon names and descriptions.

```diff

    {
      "id": "pl_msg_00000360_00001",
      "en_US": [
-       "{COLOR 3}Tiny Leaf Pokémon TURTWIG{COLOR 0}!\n",
+       "{COLOR 3}Seed Pokémon BULBASAUR{COLOR 0}!\n",
        "Will you take this Pokémon?"
      ]
    },
    {
      "id": "pl_msg_00000360_00002",
      "en_US": [
-       "{COLOR 1}Chimp Pokémon CHIMCHAR{COLOR 0}!\n",
+       "{COLOR 1}Lizard Pokémon CHARMANDER{COLOR 0}!\n",
        "Do you choose this Pokémon?"
      ]
    },
    {
      "id": "pl_msg_00000360_00003",
      "en_US": [
-       "{COLOR 2}Penguin Pokémon{COLOR 0} {COLOR 2}PIPLUP{COLOR 0}!\n",
+       "{COLOR 2}Tiny Turtle Pokémon{COLOR 0} {COLOR 2}SQUIRTLE{COLOR 0}!\n",
        "Is this Pokémon the one for you?"
      ]
    },

```

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

### Create Helix language.toml for C/C++

Source: https://github.com/pret/pokeplatinum/blob/main/docs/editor_setup/helix.md

Create the language.toml file in the Helix configuration directory and configure it to use clang-format for auto-formatting C and H files.

```bash
cd .config/helix
touch language.toml
```

```toml
[[language]]
name = "c"
formatter = { command = 'clang-format'}
auto-format = true
file-types = ["c", "h"]
```

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

### Perform Ubuntu Release Upgrade

Source: https://github.com/pret/pokeplatinum/blob/main/INSTALL.md

Initiates a full release upgrade for the Ubuntu WSL distribution. This process can take a significant amount of time.

```bash
sudo do-release-upgrade
```

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

### Generate Context File with m2ctx

Source: https://github.com/pret/pokeplatinum/blob/main/tools/m2ctx/README.md

Run this command to generate a context file named 'ctx.c' from your source file. Copy the contents of 'ctx.c' into the 'Context' section of decomp.me.

```bash
./tools/m2ctx/m2ctx.sh src/npc_trade.c
```

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

### Create a .narc archive

Source: https://github.com/pret/pokeplatinum/blob/main/tools/nitroarc/doc/nitroarc.1.adoc

Use this command to create a new .narc archive containing all files from a specified directory.

```bash
nitroarc -cf archive.narc path/to/directory
```