Docs: English · Português (README_PT.md)
Monorepo for text-to-image, text-to-3D, text-to-audio, textures and skymaps (Hugging Face Inference API), PBR texturing, part decomposition, rigging, animation, asset batching, and browser 3D engine, sharing the same foundation (gamedev-shared), unified installer, and documentation.
All GPU tools support multi-GPU (--gpu-ids 0,1) and quality presets (--quality fast|low|medium|high|highest).
The tools form a modular generation pipeline — use them individually or let GameAssets orchestrate the full flow:
Text2D (image) ──→ Text3D (mesh) ──→ Paint3D (texture) ──→ Part3D (parts) ──→ Rigging3D (rig) ──→ Animator3D (animate)
│ │ │
▼ ▼ ▼
Texture2D (seamless) Materialize (PBR) GameAssets (batch)
│ ──→ VibeGame (browser)
Skymap2D (sky)
Text2Sound (audio)
Terrain3D (terrain)
The flagship workflow — describe your game and let the pipeline generate everything:
gameassets dream "A dark fantasy RPG with skeletons and treasure chests" --dry-run # preview plan
gameassets dream "A dark fantasy RPG with skeletons and treasure chests" # full runWhat dream does: plans assets via an LLM (--llm-provider openai|huggingface|stdin), generates game.yaml / manifest.csv / world.xml, runs the full pipeline (batch → rig → parts → animate → sky → terrain), handoffs assets to Vite public dir, and scaffolds a playable project. Stages are auto-detected; use --no-animate, --no-rig, --no-parts, or --no-3d to opt out.
Source: GameAssets/src/gameassets/dream/.
Generated assets flow into the VibeGame browser engine via handoff and declarative XML scenes:
gameassets handoff --public-dir public/ # copies GLBs (prefers animated) + manifest.jsonScene description via world.xml using VibeGame recipes:
<PlayerGLTF pos="0 0 0" model-url="/assets/models/hero.glb"></PlayerGLTF>
<GLTFLoader pos="5 0 0" model-url="/assets/models/skeleton.glb"></GLTFLoader>
<Terrain heightmap-url="/assets/heightmap.png" resolution="128"></Terrain>Key APIs: gltf-bridge.ts (loadGltfToScene, loadGltfAnimated), gltf-animator.ts (GltfAnimator), sky-env.ts (applyEquirectSkyEnvironment). See docs/MONOREPO_GAME_PIPELINE.md and VibeGame/README.md.
| Folder | Description |
|---|---|
| Shared | Shared library (gamedev-shared): logging, GPU, subprocess, installers, CLI. |
| Text2D | Text-to-image CLI with FLUX (SDNQ quantization), aimed at modest GPUs. |
| Text3D | Text-to-3D pipeline: 2D image (via Text2D) → GLB mesh with Hunyuan3D-2.1 (SDNQ INT4). Texturing via Paint3D (optional). |
| Part3D | Semantic 3D parts: Hunyuan3D-Part (segmentation / mesh parts). |
| Paint3D | 3D texturing: Hunyuan3D-Paint 2.1 (multiview PBR) + Materialize PBR + AI upscale (Real-ESRGAN). Standalone or via Text3D. |
| GameAssets | Prompt/asset batching: profile + CSV → text2d or texture2d + optional text3d, rig, Animator3D (auto-detected), gameassets dream (idea → Vite scaffold). |
| Texture2D | Seamless 2D textures (tileable) via HF Inference API — no local GPU required. |
| Skymap2D | Equirectangular 360° skymaps via HF Inference API — skyboxes for game dev, no local GPU. |
| Text2Sound | Text-to-audio CLI with Stable Audio Open 1.0: stereo 44.1 kHz, game-dev presets. |
| Rigging3D | rigging3d — 3D auto-rigging with UniRig (skeleton + skinning + merge); CUDA GPU; Python 3.11, bpy 5.0.x (Open3D). |
| Animator3D | animator3d — bpy 5.1; Python 3.13; procedural clips, game-pack (humanoid/creature/flying presets), GLB export after rigging. |
| Materialize | PBR maps CLI (Rust/wgpu): normal, AO, metallic, smoothness from a diffuse texture. |
| GameDevLab | Lab CLI: debug 3D, quantization benches, profiling, pipeline optimization. |
| Terrain3D | terrain3d — AI terrain generation via diffusion models (terrain-diffusion; CUDA GPU). |
| VibeGame | vibegame — TypeScript 3D engine (ECS, Three.js, declarative XML); Bun + Vite. See VibeGame/README.md. |
Each project has its own README, setup, requirements, and license. Portuguese: README_PT.md (root) and per-package README_PT.md where provided.
All generation tools support a unified quality system (--quality fast|low|medium|high|highest) with sensible defaults per tool and asset category. See docs/superpowers/specs/2026-04-30-quality-presets-design.md.
Multi-GPU support (via accelerate dispatch) is available across most GPU tools:
text3d generate "a dragon" --gpu-ids 0,1 # Split weights across GPU 0 and 1
paint3d texture dragon.glb --gpu-ids 0,1 # Multi-GPU texturingDetected automatically via nvidia-smi when omitted. GameAssets batch/resume propagates --gpu-ids to all sub-tools.
GameDev/
Shared/ ← gamedev-shared (pip): logging, GPU, subprocess, env, installers
Text2D/ ← text2d (pip) — depends on Shared
Text3D/ ← text3d (pip) — depends on Shared + Text2D; texture via Paint3D (optional)
Part3D/ ← part3d (pip) — Shared; Hunyuan3D-Part (torch-scatter/cluster)
Paint3D/ ← paint3d (pip) — depends on Shared; Hunyuan3D-2.1 hy3dpaint + Materialize PBR + upscale
GameAssets/ ← gameassets (pip) — depends on Shared; calls text2d/texture2d/text3d via subprocess
Texture2D/ ← texture2d (pip) — depends on Shared; HF inference in the cloud
Skymap2D/ ← skymap2d (pip) — depends on Shared; equirectangular skymaps via HF
Text2Sound/ ← text2sound (pip) — depends on Shared; Stable Audio Open 1.0
Rigging3D/ ← rigging3d (pip) — Shared; inference Py 3.11 + bpy 5.0.x
Animator3D/ ← animator3d (pip) — Shared; Py 3.13 + bpy 5.1 (animation)
GameDevLab/ ← gamedev-lab (pip) — depends on Shared; debug 3D, benches, profiling
Terrain3D/ ← terrain3d (pip) — depends on Shared; AI terrain generation via diffusion
Materialize/ ← materialize-cli (cargo) — Python installer uses Shared
VibeGame/ ← vibegame (npm/Bun + Vite) — browser 3D engine; standalone, not pip
- Python: most tools require 3.10+; exceptions: Rigging3D (3.11), Animator3D (3.13 +
bpy5.1). See each folder's README. - VibeGame uses Bun and Node-compatible tooling (see
VibeGame/package.json); runmake test-vibegamefrom the repo root after installing Bun. - GPU optional for Text2D; for Text3D/Paint3D/Part3D/Rigging3D, CUDA with enough VRAM is recommended for reasonable runtimes. Texture2D and Skymap2D do not need a local GPU (Hugging Face API). GameAssets only needs a GPU if the profile/row invokes local tools (e.g. text2d, text3d). Multi-GPU: most GPU tools accept
--gpu-ids 0,1to split model weights across multiple NVIDIA GPUs via accelerate dispatch. - Model weights (Hugging Face, etc.) have their own licenses — read the model cards before shipping or using in production.
Full guide (tool table, minimum Python per CLI, repo root vs Project/scripts/): docs/INSTALLING.md · Português.
Game pipeline (GameAssets → Vite / VibeGame, folder layout, GLB handoff): docs/MONOREPO_GAME_PIPELINE.md.
Zero-to-game with AI (generative tools + orchestration + agents): docs/ZERO_TO_GAME_AI.md · Português.
| Method | When to use |
|---|---|
Root scripts (./install.sh, .\install.ps1, install.bat) |
Recommended: Clified via PyPI using tools.yaml in this repo. |
gamedev-install |
Mesmo fluxo via ponte gamedev_shared.installer (instala clified via PyPI se necessário). |
Project-local installer (<Project>/scripts/install.sh or python scripts/installer.py) |
Shortcut when you are already inside the project folder; do not confuse with GameDev/install.sh at the repo root (see docs/INSTALLING.md). |
| Manual / pipelines | python -m venv .venv + pip install -e . per folder; see READMEs and "Manual" sections — for debugging or CI without the unified wrapper. |
Useful variable: PYTHON_CMD (or --python on the installer) to force the interpreter (default python3 on Unix, python on Windows in the scripts).
Installation is driven by tools.yaml and Clified on PyPI (installed automatically by the root scripts):
# Linux/macOS
./install.sh --list # List available tools
./install.sh materialize # Install Materialize (Rust)
./install.sh text2d # Creates Text2D/.venv if needed; installs into project venv
./install.sh texture2d # Same (Texture2D/.venv)
./install.sh skymap2d # Skymap2D (equirectangular skymaps; no GPU)
./install.sh text2sound # Text2Sound (needs CUDA; installs PyTorch)
./install.sh text3d # Text3D (Text2D + Hunyuan; nvdiffrast for Paint)
./install.sh gameassets # GameAssets (batch; orchestrates other CLIs)
./install.sh part3d # Part3D (Hunyuan3D-Part; torch-scatter/cluster)
./install.sh paint3d # Paint3D (texturing + nvdiffrast)
./install.sh rigging3d # Rigging3D (bundled UniRig + PyTorch/CUDA via installer)
./install.sh animator3d # Animator3D (bpy / animation; no PyTorch)
./install.sh gamedevlab # GameDevLab (debug 3D, benches, profiling)
./install.sh terrain3d # Terrain3D (AI terrain; CUDA GPU)
./install.sh all # Install everything present
# Windows PowerShell (recommended on Windows: script detects `python` and passes it to the installer)
.\install.ps1 --list
.\install.ps1 materialize
.\install.ps1 text2d
.\install.ps1 texture2d
.\install.ps1 skymap2d
.\install.ps1 text2sound
.\install.ps1 text3d
.\install.ps1 gameassets
.\install.ps1 part3d
.\install.ps1 paint3d
.\install.ps1 rigging3d
.\install.ps1 animator3d
.\install.ps1 gamedevlab
.\install.ps1 terrain3d
.\install.ps1 all
# Windows CMD (same: `install.bat` passes the interpreter to the installer)
install.bat materializeEquivalent with Shared installed: gamedev-install text2d, gamedev-install all, etc. (list: gamedev-install --list).
Unified installer options:
| Option | Description |
|---|---|
--action {install,uninstall,reinstall} |
Action (default: install) |
--use-venv |
Legacy (optional); the installer always creates project/.venv if missing and installs there |
--skip-deps |
Skip system dependencies |
--skip-models |
Skip model/weight setup |
--force |
Force reinstall |
--prefix PATH |
Install prefix (default: ~/.local) |
--python CMD |
Python command (default: python3) |
--list |
List available tools |
--skip-env-config |
Text3D: do not write ~/.config/text3d/env.sh (or env.bat on Windows) |
# 1. Install Shared (required for all Python projects)
cd Shared && pip install -e . && cd ..
# 2. Text2D (image)
cd Text2D && ./scripts/setup.sh && source .venv/bin/activate && text2d --help
# 3. Text3D (3D; depends on Text2D as a local package — see Text3D/README)
cd ../Text3D
python -m venv .venv && source .venv/bin/activate
pip install -r config/requirements.txt && pip install -e .
text3d --help
# 4. Part3D (semantic parts; torch-scatter/cluster after PyTorch — see Part3D/README)
cd ../Part3D && python -m venv .venv && source .venv/bin/activate && pip install -e . && part3d --help
# 5. Paint3D (Hunyuan3D-Paint 2.1; vendored code in Paint3D/src/paint3d/hy3dpaint/ + nvdiffrast — see Paint3D/docs/PAINT_SETUP.md)
cd ../Paint3D
python -m venv .venv && source .venv/bin/activate
pip install torch torchvision
pip install -r config/requirements.txt && pip install -e .
pip install git+https://github.com/NVlabs/nvdiffrast.git --no-build-isolation
paint3d --help
# 6. GameAssets (batch; Text2D/Text3D on PATH or TEXT2D_BIN/TEXT3D_BIN; Texture2D optional TEXTURE2D_BIN; Materialize optional MATERIALIZE_BIN)
cd ../GameAssets && chmod +x scripts/setup.sh && ./scripts/setup.sh && source .venv/bin/activate && gameassets --help
# 7. Texture2D (seamless textures via HF API; no local PyTorch)
cd ../Texture2D && chmod +x scripts/setup.sh && ./scripts/setup.sh && source .venv/bin/activate && texture2d --help
# 8. Skymap2D (equirectangular 360° skymaps via HF API; no local PyTorch)
cd ../Skymap2D && chmod +x scripts/setup.sh && ./scripts/setup.sh && source .venv/bin/activate && skymap2d --help
# 9. Text2Sound (text-to-audio; Stable Audio Open 1.0; needs CUDA)
cd ../Text2Sound && chmod +x scripts/setup.sh && ./scripts/setup.sh && source .venv/bin/activate && text2sound --help
# 10. Rigging3D (CUDA GPU; Python 3.11; heavy deps — prefer ./install.sh rigging3d)
cd ../Rigging3D && pip install -e ".[inference,dev]" && rigging3d --help
# 11. Animator3D (animation; venv with Python 3.13 + bpy — see Animator3D/README; Windows: py -3.13 -m venv .venv)
cd ../Animator3D && python3.13 -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]" && animator3d --help
# 12. Materialize (Rust — needs cargo)
cd ../Materialize && ./install.sh
# 13. GameDevLab (debug 3D, benches, profiling; no PyTorch required)
cd ../GameDevLab && python -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]" && gamedev-lab --help
# 14. Terrain3D (AI terrain; CUDA GPU)
cd ../Terrain3D && python -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]" && terrain3d --helpFull instructions: docs/INSTALLING.md, docs/NEW_TOOLS.md (registering new tools), Shared/README.md, and each package README.
| Component | License | Note |
|---|---|---|
| Monorepo code (Text2D, Text3D, Part3D, Paint3D, Texture2D, Skymap2D, Text2Sound, Rigging3D, Animator3D, GameAssets, GameDevLab, Terrain3D, Shared) | MIT | See LICENSE in each folder |
| Materialize CLI (Rust) | MIT | Materialize/LICENSE |
| FLUX.2 Klein 4B (official, BF16) | Apache 2.0 | black-forest-labs/FLUX.2-klein-4B — commercial use allowed per model card; more VRAM than SDNQ |
| FLUX.2 Klein 4B SDNQ (Text2D default) | FLUX Non-Commercial (HF metadata) | Disty0/FLUX.2-klein-4B-SDNQ-4bit-dynamic declares flux-non-commercial-license; not the same as the official Apache 2.0 checkpoint. For commercial products prefer TEXT2D_MODEL_ID=black-forest-labs/FLUX.2-klein-4B or a BFL agreement |
| Hunyuan3D-2.1 (shape + paint, Text3D + Paint3D) | Tencent Hunyuan Community License | tencent/Hunyuan3D-2.1 — read repo LICENSE: territory restrictions (e.g. EU, UK, South Korea), acceptable use, downstream obligations. Code: Hunyuan3D-2.1; shape weights hunyuan3d-dit-v2-1 (SDNQ INT4), paint weights hunyuan3d-paintpbr-v2-1 |
| Stable Audio Open 1.0 / Open Small (Text2Sound) | Stability AI Community License | stabilityai/stable-audio-open-1.0, stabilityai/stable-audio-open-small — gated models (accept on Hub); free commercial use with annual revenue cap (see repo LICENSE.md, currently ~USD 1M; changes: stability.ai/license) |
| Flux-Seamless-Texture-LoRA (Texture2D) | Apache 2.0 (HF metadata) | gokaygokay/Flux-Seamless-Texture-LoRA — LoRA on FLUX.1-dev: also comply with base model and Inference API terms |
| Flux-LoRA-Equirectangular-v3 (Skymap2D) | FLUX.1 [dev] base (NCL) + HF card | MultiTrickFox/Flux-LoRA-Equirectangular-v3 — no SPDX in README; base FLUX.1-dev is BFL non-commercial; Civitai origin on card |
UniRig (code under Rigging3D/…/unirig/) |
MIT | VAST-AI-Research/UniRig · THIRD_PARTY.md |
| UniRig (HF weights) | MIT (many mirrors list MIT) | VAST-AI/UniRig — confirm in README/LICENSE of the snapshot you use; example with MIT LICENSE |
Note: weights have their own licenses. Inference API (Texture2D, Skymap2D): besides the model, Hugging Face terms and API policies apply. Do not redistribute checkpoints without complying with the author's license and attribution. Shap-E (
openai/shap-e) in legacy Text3D scripts requires accepting Hub terms.
The monorepo uses environment variables to locate binaries and configure behavior:
| Variable | Used by | Description |
|---|---|---|
TEXT2D_BIN |
GameAssets | Path to text2d (if not on PATH) |
TEXT3D_BIN |
GameAssets | Path to text3d |
TEXTURE2D_BIN |
GameAssets | Path to texture2d |
TEXT2SOUND_BIN |
GameAssets | Path to text2sound |
MATERIALIZE_BIN |
GameAssets, Text3D | Path to materialize |
GAMEDEVLAB_BIN |
GameAssets | Path to gamedev-lab |
TERRAIN3D_BIN |
GameAssets | Path to terrain3d |
TEXT2D_MODEL_ID |
Text2D | HF model override for Text2D |
TEXTURE2D_MODEL_ID |
Texture2D | HF model override for Texture2D |
SKYMAP2D_MODEL_ID |
Skymap2D | HF model override for Skymap2D |
HF_TOKEN |
Text2Sound, Texture2D, Skymap2D | Hugging Face token for authenticated APIs |
HF_HOME |
All (Python) | Hugging Face cache directory (default: ~/.cache/huggingface) |
PYTORCH_CUDA_ALLOC_CONF |
Text2D, Text3D, GameAssets | CUDA allocator config (auto-set if empty) |
TEXT3D_ALLOW_SHARED_GPU |
Text3D | Allow GPU sharing with other processes |
TEXT3D_GPU_KILL_OTHERS |
Text3D | Control termination of competing GPU processes |
TEXT3D_EXPORT_ROTATION_X_DEG |
Text3D | X rotation when exporting mesh (degrees) |
PAINT3D_ALLOW_SHARED_GPU |
Paint3D | Allow GPU sharing with other processes |
PAINT3D_GPU_KILL_OTHERS |
Paint3D | Control termination of competing GPU processes |
PAINT3D_MULTI_GPU |
Paint3D | Deprecated — use --gpu-ids 0,1 instead. Legacy env var to split VAE across GPUs |
RIGGING3D_ROOT |
Rigging3D | Inference tree root (default: bundled package) |
RIGGING3D_PYTHON |
Rigging3D | Python interpreter for the inference environment |
| Tool | Scope | Config |
|---|---|---|
| Ruff | Lint + format (Python) | ruff.toml (root) |
| MyPy | Type-checking (Python) | mypy.ini (root) |
| Pytest + pytest-cov | Tests + coverage | pyproject.toml per package |
| Cargo Clippy | Lint (Rust) | via Makefile |
| Pre-commit | Pre-commit hooks | .pre-commit-config.yaml |
| GitHub Actions | CI (lint + test + clippy) | .github/workflows/ci.yml |
make help # List targets
make lint # Ruff check + Cargo clippy
make fmt # Ruff format + Cargo fmt
make fmt-check # Check formatting without writing
make test # Pytest all packages + Cargo test
make test-shared # Pytest Shared only
make test-text2d # Pytest Text2D only
make test-gamedevlab # Pytest GameDevLab only
make test-terrain3d # Pytest Terrain3D only
make typecheck # MyPy on Shared/src
make check # lint + fmt-check + typecheck + test (full CI)
make clean # Remove __pycache__, caches, builds
make install-hooks # Install pre-commit hooksWindows: requires GNU Make (Git Bash, MSYS2, or WSL).
# 1. Pre-commit hooks
pip install pre-commit
make install-hooks
# 2. Dev deps for a package (example: Shared)
cd Shared && pip install -e ".[dev]" && cd ..
# 3. Run tests
make test-shared
# 4. Lint and format
make lint
make fmtEach Python package has a pyproject.toml (PEP 621) with metadata, dependencies, and pytest config.
Existing setup.py files remain for legacy installer compatibility.
Some components trace their design to external projects:
- Materialize (Rust CLI): inspired by the original Materialize from Bounding Box Software (Unity/Windows). See
Materialize/README.md. - VibeGame (TypeScript engine): upstream project dylanebert/VibeGame. See
VibeGame/README.md.
- Prefer small commits and Conventional Commits-style messages.
- Virtual environments and caches are ignored: root
.gitignorealigns with subfolders. - Run
make checkbefore opening PRs. - Each tool has
[project.optional-dependencies] devinpyproject.toml— usepip install -e ".[dev]"before running tests. - Documentation: keep
README.md(English) and optionalREADME_PT.md, anddocs/when present, up to date.