cute.zombie.mp4

WorldGen

WorldGen is a local-first Minecraft structure generator split into two codebases:

• backend/: a typed Python backend that owns job orchestration, artifacts, and the AI/mesh/voxel pipeline.
• minecraft-mod/: a Fabric 26.1 mod that owns /gen, preview controls, and server-authoritative placement.

Use the docs that match the target:

• Java Edition / Fabric mod: minecraft-mod/README.md
• Backend pipeline and Bedrock behavior-pack export: backend/README.md

Java Edition Usage

Generate a structure:

/gen <size> <prompt...>

Example:

/gen 16 oak tree
/gen 128 a 13th century castle

While the preview is active, adjust orientation and position with:

• Aim at a block within 128 blocks to move the preview target
• Z: rotate +90 degrees around Z
• X: rotate +90 degrees around X
• C: rotate +90 degrees around Y

When the preview looks right:

• Enter: place the structure
• Esc: cancel the preview

Undo the most recent placement:

/gen undo

Bedrock Behavior Packs

Bedrock behavior packs are backend export artifacts, not part of the Fabric mod.

Generated Bedrock packs live under %LOCALAPPDATA%\WorldGen\generations\<generation>\ as:

• bedrock_behavior_pack\
• <generation>.mcpack

For distribution, use the single-file .mcpack. The unpacked bedrock_behavior_pack\ directory is mainly there for inspection and debugging.

To use the Bedrock pack:

1. Import the .mcpack into Minecraft Bedrock.
2. Enable the imported behavior pack on your Bedrock world.
3. Join the world. Each installed pack gives players its own pack-specific controller item.
4. Use the controller item to open the UI.

The scripted Bedrock UI contains:

• Place Object
• Browse All

If the controller item is missing or you want to force-open the UI, run:

/function worldgen/open

The generated help command is:

/function worldgen/help

For the full Bedrock export and backend documentation, see backend/README.md.

One-Command Stack

Start the backend, modded server, and modded client together:

python .\tools\run_local_stack.py

The launcher waits for the backend and server to become ready, starts the client, streams logs from all three processes, and shuts everything down cleanly on Ctrl+C. The backend process runs inside Ubuntu 22.04 on WSL2 using the worldgen-py311 env; the Minecraft mod and client stay on Windows. It writes timestamped logs to minecraft-mod\build\reports\run-stack-*.log.

Repo Layout

• backend/
• minecraft-mod/
• docs/SETUP.md
• tools/

Java Edition Quick Start

1. Follow docs/SETUP.md to install Java 25, Python 3.11, Fabric Loader, WSL2 on Ubuntu 22.04, and the backend/TRELLIS.2 dependencies.
2. Bootstrap and verify the TRELLIS.2 WSL backend:

.\tools\bootstrap-trellis.ps1 -Run

3. Start the backend from Windows. The launcher will enter Ubuntu 22.04 WSL2 and use worldgen-py311:

.\tools\run-backend.ps1

For local development, keep backend settings in an ignored file at backend\.env.local:

OPENAI_API_KEY=replace-me
WORLDGEN_DATA_ROOT=/mnt/c/Users/<you>/AppData/Local/WorldGen
WORLDGEN_TRELLIS_MODEL=microsoft/TRELLIS.2-4B
WORLDGEN_TRELLIS_REPO=/home/<you>/src/TRELLIS.2
WORLDGEN_TRELLIS_LOW_VRAM=0
WORLDGEN_TRELLIS_WARMUP_TIMEOUT_SECONDS=600
WORLDGEN_TRELLIS_REQUEST_TIMEOUT_SECONDS=1800
WORLDGEN_TRELLIS_PIPELINE_TYPE=1024_cascade
WORLDGEN_TRELLIS_TEXTURE_SIZE=2048
WORLDGEN_TRELLIS_GLB_DECIMATION_TARGET=20000

The backend auto-loads backend\.env.local, backend\.env, repo-root .env.local, and repo-root .env. Those files are loaded inside WSL, so use Linux/WSL paths instead of C:\....

Or launch the whole local stack in one command:

python .\tools\run_local_stack.py

4. Build the Fabric mod:

.\tools\build-mod.ps1

5. Start the modded server:

.\tools\run-mod-server.ps1

This runs the Fabric dev server for the mod from minecraft-mod via Gradle and forces the dev server default game mode to creative.

6. Launch the modded client:

.\tools\run-mod-client.ps1

By default, the client quick-plays straight into 127.0.0.1:25565. If you want to open the client without auto-connecting, use:

.\tools\run-mod-client.ps1 -NoQuickPlay

7. Run the fully automated local end-to-end check:

python .\tools\e2e_full_stack.py

8. Run the backend-only diagnostic loop for one prompt:

cd /mnt/c/Users/savet/Desktop/WorldGen/backend
python scripts/diagnose_generation.py --prompt "oak tree" --size 16

This writes concept.png, meshes, occupancy projections, block projections, and diagnostic-sheet.png under backend\.diagnostics\. The canonical textured artifact is textured_mesh.glb.

Notes

• The backend is designed to run on Ubuntu 22.04 under WSL2; the Minecraft client and Fabric mod remain on Windows.
• The mod target is Minecraft 26.1 with Java 25.
• If OPENAI_API_KEY is unset, the backend falls back to deterministic local stub images for development and testing.
• Concept-image outputs are cached under %LOCALAPPDATA%\WorldGen\image-cache, so repeated prompts such as oak tree reuse earlier image generation results.
• The separately installed server under C:\Users\savet\Desktop\minecraft is a vanilla server. Install Fabric server loader there before copying the mod jar into mods/.