67 lines
3.7 KiB
Markdown
67 lines
3.7 KiB
Markdown
# 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.
|