Skip to content

SETUP.md

Latest commit

 

History

History
134 lines (95 loc) · 4.16 KB

SETUP.md

File metadata and controls

134 lines (95 loc) · 4.16 KB
Raw

Windows + WSL2 Setup

Required Installs

  1. Install JDK 25 x64 and make sure java -version reports a Java 25 runtime.
  2. Install Python 3.11 x64 on Windows. The repo launchers and local stack scripts use it for orchestration, while the backend itself runs inside Ubuntu 22.04 on WSL2.
  3. Enable WSL2 and install Ubuntu 22.04.
  4. Install Fabric Loader for the Minecraft version pinned by minecraft-mod/gradle.properties.
  5. Optional: create a fresh OpenAI API key and keep it in 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

If you skip this, the backend uses deterministic local stub images for development.

TRELLIS Bootstrap

Use the helper script from the repo root to verify the WSL-side TRELLIS setup and print the exact commands for your Ubuntu 22.04 environment:

.\tools\bootstrap-trellis.ps1

If WSL is not ready yet, fix it first:

wsl --status
wsl -l -v
wsl --set-default-version 2

If Ubuntu-22.04 is not listed as version 2, enable the Windows features for Virtual Machine Platform and Windows Subsystem for Linux, reboot, and then run:

wsl --install -d Ubuntu-22.04
wsl --set-version Ubuntu-22.04 2

Backend Runtime

From the repo root:

.\tools\run-backend.ps1

The backend starts in Ubuntu 22.04 under WSL2 using the worldgen-py311 env. To set that env up manually inside WSL:

source ~/miniconda3/etc/profile.d/conda.sh
conda create -n worldgen-py311 python=3.11
conda activate worldgen-py311
cd /mnt/c/Users/savet/Desktop/WorldGen/backend
pip install -e .[dev]

Install TRELLIS.2 into the same WSL env:

bash /mnt/c/Users/savet/Desktop/WorldGen/tools/install-trellis-wsl.sh \
  --backend-dir /mnt/c/Users/savet/Desktop/WorldGen/backend \
  --runtime-env worldgen-py311 \
  --toolkit-env cuda124-toolkit

That installer clones ~/src/TRELLIS.2, initializes the o-voxel/third_party/eigen submodule, creates a matching CUDA 12.4.1 build-toolchain env, installs flash-attn, nvdiffrast, nvdiffrec, cumesh, flex_gemm, and o-voxel, and registers the TRELLIS source tree in worldgen-py311.

If you put overrides in backend\.env.local, remember that the backend reads them from inside WSL. Use Linux/WSL paths there, for example:

WORLDGEN_DATA_ROOT=/mnt/c/Users/<you>/AppData/Local/WorldGen
WORLDGEN_TRELLIS_REPO=/home/<you>/src/TRELLIS.2

Concept-image outputs are cached under %LOCALAPPDATA%\WorldGen\image-cache, so repeated prompts reuse earlier image generations. The canonical textured artifact is textured_mesh.glb.

Fabric Mod

From the repo root:

cd minecraft-mod
.\gradlew.bat build
.\gradlew.bat runClient

If runClient fails because Java 25 is not the active runtime, set JAVA_HOME to the JDK 25 installation and reopen the terminal.

One-Command Local Stack

To start the backend, dev server, and dev client together from the repo root:

python .\tools\run_local_stack.py

The launcher waits for backend/server readiness, quick-plays the client into 127.0.0.1:25565, streams logs for all three processes, and cleans them up on Ctrl+C. The backend part of that stack runs through the WSL launcher and uses Ubuntu 22.04 plus worldgen-py311.

Automated Verification

Server-only smoke test:

python .\tools\smoke_mod_server.py "gen 16 oak tree" stop

Full local end-to-end check:

python .\tools\e2e_full_stack.py

Backend-only diagnostic loop:

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

Separate Installed Server

The server at C:\Users\savet\Desktop\minecraft is a vanilla server. Install Fabric server loader there before copying the built mod jar into its mods\ directory.