DOCSEARCHbyAlgolia
Submit Docs

Pokémon Platinum Decompilation Tools

repository·main·Indexed 18 days ago

https://github.com/pret/pokeplatinum

Tools and documentation to assist in the decompilation of Pokémon Platinum. Includes the m2ctx tool for generating decomp.me context files, the nitroarc C library and CLI for Nitro Archive (NARC) manipulation, and NitroBTX for NSBTX texture files. Provides technical specifications for the game's map subsystems, 2D rendering architecture, VRAM management, and 3D rendering abstraction layers including Easy3D and Easy3DObject.

Tokens
46.9K
Snippets
85
Records
141
Agent score
67%

What's inside pokeplatinum

  2. Overview of Data Processing Tools

    main

    The project uses a suite of custom compiler tools located in tools/dataproc to convert plain-text data files (primarily JSON) into game-ready binary data. These tools use a common interface defined in lib/dataproc.c for querying data markup and providing validation and error reporting.

    Key shared infrastructure used by these tools includes:

    • Parsing C enums and preprocessor definitions from headers into lookup tables.
    • Generating output C header files using .template files.
    • Creating output NARC files via libnitroarc.
    • Writing dependency files at runtime to ensure correct build ordering.

  3. Move Data File Format Overview

    main

    The moveproc build tool consumes move data organized into subdirectories under res/moves/<name>. Each move directory must contain three specific files to define its metadata, visual animation, and battle logic:

    1. data.json: Contains internal metadata such as stats, type, flags, and text.
    2. anim.s: An assembly script defining the move's animation in battles and contests.
    3. script.s: An assembly script defining the move's execution logic during battle.

  4. Trainer Data File Format Overview

    main
    The trainerproc build tool consumes trainer data from JSON files located at res/trainers/data/<name>.json. Each file represents a single trainer and contains metadata for the trainer and their Pokémon party. These fields are mapped to structs defined in include/struct_defs/trainer_data.h.

  5. Understand the map-related subsystems in PokePlatinum

    main

    The map system in PokePlatinum is composed of several interacting subsystems that allow the game to render a seamless world. Key components include:

    • Maps: 2D grids of 32x32 tiles.
    • Map Headers: Metadata structures associated with specific map IDs containing information like music, map names, and cycling permissions.
    • Map Matrices: 2D arrays of maps that form playable areas (e.g., the 30x30 overworld matrix), enabling dynamic loading/unloading as the player moves.
    • Areas: Collections of maps that share the same textures and map prop models.
    • Map Objects: Entities placed on maps, such as the player or NPCs.
    • Map Props: 3D models placed on maps, such as buildings or furniture.
    • BDHC: A subsystem providing terrain height data used for collision detection and map object height calculations.

    For technical details on specific subsystems, refer to the following documentation files:

    • maps.md: General map overview.
    • bdhc.md: BDHC subsystem and height information.
    • loading_maps.md: Map loading processes.
    • file_format_specifications.md: Technical data structures and file formats.
    • dynamic_map_features.md: Dynamic map features system.

  6. What is the BDHC subsystem?

    main

    The BDHC subsystem is used to calculate terrain height for collision detection and to enable 3D height in an otherwise 2D movement system. This data is stored alongside individual maps.

    Coordinate System:

    • 2D points are represented by $(x, z)$ coordinates.
    • The game uses a right-hand rule coordinate system where the Y axis points upwards (representing height).

  7. In-Game Trade Data File Format

    main
    The npctradeproc build tool consumes in-game trade data via JSON files located at res/npc_trades/<name>.json. Each file represents a single NPC trade event and contains metadata for both the trade event and the Pokémon being received. These JSON fields are mapped directly onto the NPCTradeMon struct defined in include/overlay006/npc_trade.h.

  8. Configure Trainer Dialogue Messages

    main

    The messages array defines dialogue spoken during battle. Each entry requires a type (from enum TrainerMessageType, e.g., TRMSG_PRE_BATTLE, TRMSG_DEFEAT, TRMSG_POST_BATTLE, TRMSG_REMATCH) and an en_US field.

    • en_US can be a single string or an array of strings for multi-line messages.
    • Use the garbage key instead of en_US to represent padding present in the retail ROM.

  9. Understand the Dynamic Map Features system

    main

    Dynamic map features allow map layouts to change based on player input. The system relies on two types of data:

    • Dynamic map features data (runtime data): Specific to a feature and only available during runtime (e.g., instances of map props used for movable platforms).
    • Persisted map features data (persisted data): A 32-byte buffer in the save file used to store state that must survive a save/load cycle (e.g., the position of a platform).

    Important Constraints:

    • Only one dynamic map feature can be active at any given time across all loaded maps.
    • Because of this restriction, the system is primarily used in dungeons or small map matrices (usually 1x1) rather than the overworld.
    • This system is intended for layout changes; it does not include simple obstacles like movable boulders or breakable rocks.

  10. Group maps with Areas

    main

    An Area is a grouping mechanism for maps. While a map can only belong to one area, a map matrix can contain multiple areas.

    Purpose of Areas: Areas group rendering resources that are common to multiple maps to optimize loading. When entering a map within an area, the following are loaded:

    • 3D models of map props
    • Textures of map props
    • Animation data of map props
    • Textures of map models
    • Lighting configuration

  11. Understand the 2D Rendering and VRAM architecture

    main

    The Nintendo DS 2D rendering system uses a layered approach with 8 total layers split across the Main and Sub screens (indices 0 through 3 for each display).

    Rendering relies on a 656 KB VRAM chunk divided into 9 banks:

    • Four 128 KB banks
    • One 64 KB bank
    • One 32 KB bank
    • Three 16 KB banks

    Key Constraints:

    • The 2D and 3D engines cannot access the same bank concurrently.
    • The ARM7 co-processor can only access two of the four 128 KB banks.
    • Sprite graphics cannot be stored in the specific section of VRAM used for these banks.
    • The main screen cannot access the third 16 KB bank.

  12. Map Data and Map Props

    main

    The Map Data archive contains the heavy assets required for rendering and interaction:

    • Tile Attributes: Dictates collision and tile behavior (e.g., tall grass, water, trash cans).
    • Base 3D Model: Stored in an NSBMD container.
    • BDHC Data: Height information.
    • Map Props: Instances of 3D models placed on the map. Each prop instance includes:
      • 3D model identifier
      • Position
      • Rotation
      • Scale