# Code Generation (`pumpkin-codegen`)

Minecraft is a massive game with thousands of block states, items, packet IDs, sound events, recipes, and biome parameters. These registries frequently change between Minecraft updates.

To maintain 100% fidelity without manually maintaining tens of thousands of error-prone constants, Pumpkin utilizes an automated code generation tool: [`tools/pumpkin-codegen`](https://github.com/Pumpkin-MC/Pumpkin/tree/master/tools/pumpkin-codegen).

---

## Purpose & Workflow

`pumpkin-codegen` parses official Minecraft server data generator reports, asset files, and version specifications, and outputs zero-cost, strongly-typed Rust files directly into [`crates/pumpkin-data`](https://github.com/Pumpkin-MC/Pumpkin/tree/master/crates/pumpkin-data).

The pipeline operates in three distinct stages:
1. **Ingestion**: Reads raw JSON assets and vanilla server reports from `assets/` and `assets/datapacks/`.
2. **Transformation**: Normalizes states, calculates bitsets, processes ViaVersion remappings, and optimizes lookup tables.
3. **Emission**: Emits compiled Rust constants and structs into [`crates/pumpkin-data/src/generated`](https://github.com/Pumpkin-MC/Pumpkin/tree/master/crates/pumpkin-data/src/generated).

---

## Generated Datasets

`pumpkin-codegen` generates the following components in `pumpkin-data`:

| Category | Description | Generated Source |
| :--- | :--- | :--- |
| **Packets** | Serverbound and clientbound packet IDs for all protocol states across supported Minecraft versions. | `packet.rs` |
| **Blocks** | Block definitions, default states, state properties (facing, powered, waterlogged, etc.), and block collision boxes. | `block.rs` |
| **Items** | Item definitions, stack sizes, durability, data components, food properties, and equipment slots. | `item.rs` |
| **Registries** | Dynamic registries for biomes, dimensions, chat types, damage types, trim materials, and banner patterns. | `registry.rs` |
| **Biomes & Noise** | Climate parameters, noise router configurations, 3D noise settings, and surface rules. | `biome.rs`, `noise_router.rs` |
| **Entities** | Entity types, default bounding boxes, attributes, and tracked entity metadata schemas. | `entity_type.rs`, `tracked_data.rs` |
| **Recipes & Crafting** | Shaped, shapeless, smelting, blasting, smoking, and stonecutting recipes. | `recipes.rs` |
| **Tags** | Block tags, item tags, fluid tags, and entity type tags (e.g., `#minecraft:mineable/pickaxe`). | `tag.rs` |
| **Enchantments & Potions** | Enchantment definitions, potion effects, and brewing stand recipes. | `enchantments.rs`, `potion.rs` |
| **Translations** | Official localization keys for chat messages and item names. | `translations.rs` |
| **Plugin WIT** | WebAssembly Component Model WIT files defining plugin interfaces. | `wit/` |

---

## Running Code Generation

To run the code generator locally:

```bash
# Navigate to the workspace root
cd Pumpkin

# Run the codegen tool
cargo run -p pumpkin-codegen
```

### When Should You Run Codegen?

- **Upgrading to a New Minecraft Version**: When porting Pumpkin to a new minor or major Minecraft release.
- **Adding Protocol Mappings**: When adding support for an older or newer client protocol version.
- **Updating WIT Definitions**: When adding new functions or types to the WebAssembly plugin API.

---

## Data Sources

`pumpkin-codegen` reads data from several primary sources:

1. **Minecraft Data Generator Reports**: Generated by running `java -DbundlerMainClass=net.minecraft.data.Main -jar server.jar --reports`.
2. **Minecraft Client Assets**: Extracted from client `.jar` files for translation keys, model shapes, and sound mappings.
3. **Minecraft Protocol Wiki**: Cross-referenced with protocol specifications for packet IDs.