Oxidized MC — Tools

Centralized development tools for the Oxidized MC ecosystem.

Structure

tools/
├── mc-ref/                          # Minecraft reference setup
│   ├── setup-ref.sh                 # Download & decompile MC JAR
│   └── diff-versions.sh             # Compare two decompiled versions
└── data/                            # Data extraction & bundling
    ├── bundle_registries.py         # Bundle registry JSON → registries.json
    ├── bundle_tags.py               # Bundle tag JSON → tags.json
    └── extract_block_properties.py  # Extract block properties from Blocks.java

Prerequisites

• Java ≥ 21 — for decompilation and data generation
• curl, jq — for downloading JARs
• Python 3.12+ — for data extraction scripts

Usage

This repo is a submodule of the oxidized-mc meta-repo. All scripts are run from the tools/ directory.

Output goes to mc-server-ref/ at the tools repository root (gitignored). Use --ref-dir to override the output location if needed.

Decompile Minecraft JAR

# Server (default) — writes to mc-server-ref/
./mc-ref/setup-ref.sh

# Client — writes to mc-server-ref/ (decompiles client JAR instead)
./mc-ref/setup-ref.sh --mode client

# Custom output directory
./mc-ref/setup-ref.sh --ref-dir /path/to/mc-server-ref

Compare versions

# Default: compare 26.1-pre-3 → 26.1
./mc-ref/diff-versions.sh

# Custom versions
./mc-ref/diff-versions.sh 25.4 26.1

# Custom ref directory
./mc-ref/diff-versions.sh --ref-dir /path/to/mc-server-ref 25.4 26.1

Bundle registries

# Default: reads from mc-server-ref/, writes to ../server/crates/...
python3 data/bundle_registries.py

# Custom paths
python3 data/bundle_registries.py --ref-dir /path/to/mc-server-ref --project-dir /path/to/server

Bundle tags

python3 data/bundle_tags.py
python3 data/bundle_tags.py --ref-dir /path/to/mc-server-ref

Extract block properties

python3 data/extract_block_properties.py
python3 data/extract_block_properties.py --ref-dir /path/to/mc-server-ref

Decompilation output

After running setup-ref.sh, the tools directory will contain:

mc-server-ref/                     ← at tools root, gitignored
├── vineflower-1.11.2.jar          # VineFlower decompiler
├── cfr-0.152.jar                  # CFR fallback decompiler
├── decompiled → 26.1/decompiled   # Symlink to versioned directory
├── generated → 26.1/generated
├── mc-extracted → 26.1/mc-extracted
└── 26.1/
    ├── server.jar                 # Downloaded bundled launcher JAR
    ├── client.jar                 # Client JAR (client mode only)
    ├── extracted/server.jar       # Unbundled server JAR
    ├── decompiled/                # ~4 800 Java source files
    ├── generated/                 # Vanilla data-generator reports
    └── mc-extracted/              # Registry & tag data