AiGameKit

Docs: English · Português (README_PT.md)

Monorepo for text-to-image, text-to-3D, text-to-audio, seamless textures (local GPU) and skymaps (local GPU), PBR texturing, rigging, animation, asset batching, and browser 3D engine, sharing the same foundation (aigamekit-shared), unified installer, and documentation.

All GPU tools support multi-GPU (--gpu-ids 0,1) and quality presets (--quality fast|low|medium|high|highest).

Pipeline

The tools form a modular generation pipeline — use them individually or let GameAssets orchestrate the full flow:

  Text2D (image) ──→ Text3D (mesh) ──→ Paint3D (texture) ──→ Rigging3D (rig) ──→ Animator3D (animate)
       │                                        │                                  │
       ▼                                        ▼                                  ▼
  Texture2D (seamless)                   Materialize (PBR)                      GameAssets (batch)
       │                                                                               ──→ VibeGame (browser)
  Skymap2D (sky)
  Text2Sound (audio)
  Terrain3D (terrain)

One-command idea-to-game

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 run

What 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 → animate → sky → terrain), handoffs assets to Vite public dir, and scaffolds a playable project. Stages are auto-detected; use --no-animate, --no-rig, or --no-3d to opt out.

Source: GameAssets/src/gameassets/dream/.

VibeGame integration

Generated assets flow into the VibeGame browser engine via handoff and declarative XML scenes:

gameassets handoff --public-dir public/    # copies GLBs (prefers animated) + manifest.json

Scene 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.

Projects

Each project has its own README, setup, requirements, and license. Portuguese: README_PT.md (root) and per-package README_PT.md where provided.

Quality presets & multi-GPU

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 texturing

Detected automatically via NVML (aigamekit_shared.gpu.detect_gpu_ids, dep nvidia-ml-py; fallback nvidia-smi) when omitted. GameAssets batch/resume propagates --gpu-ids to all sub-tools.

Architecture

AiGameKit/
  Shared/           ← aigamekit-shared (pip): logging, GPU, subprocess, env, installers
  Text2D/           ← text2d (pip) — depends on Shared
  Text3D/           ← text3d (pip) — depends on Shared + Text2D; texture via Paint3D (optional)
  Paint3D/           ← paint3d (pip) — depends on Shared; Hunyuan3D-2.1 hy3dpaint + Materialize PBR + upscale
  Part3D/            ← part3d (pip) — depends on Shared; Hunyuan3D-Part (P3-SAM + X-Part)
  GameAssets/        ← gameassets (pip) — depends on Shared; calls text2d/texture2d/text3d via subprocess
  Texture2D/         ← texture2d (pip) — depende de Shared; pattern-diffusion local + PBR via Materialize
  Skymap2D/          ← skymap2d (pip) — depends on Shared; equirectangular skymaps (local FLUX.1-dev + LoRA)
  Text2Sound/        ← text2sound (pip) — depends on Shared; Stable Audio 3 Small (music/sfx)
  Rigging3D/         ← rigging3d (pip) — Shared; SkinTokens Py 3.13 + bpy 5.2 LTS
  Animator3D/        ← animator3d (pip) — Shared; Py 3.13 + bpy 5.2 LTS (animation)
  AiGameKitLab/        ← aigamekit-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

General requirements

• Python: all tools require 3.13 (each pyproject.toml pins >=3.13,<3.14); bpy>=5.2.0 (LTS) for mesh tools. See each folder's README.
• VibeGame uses Bun and Node-compatible tooling (see VibeGame/package.json); run make test-vibegame from the repo root after installing Bun.
• GPU optional for Text2D; for Text3D/Paint3D/Rigging3D, CUDA with enough VRAM is recommended for reasonable runtimes. Texture2D runs locally on a CUDA GPU (pattern-diffusion). Skymap2D runs locally on a CUDA GPU (FLUX.1-dev + LoRA). 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,1 to 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.

Quick start

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.

Hunyuan shape / repair / Part3D lessons (faces vs X-Part, elephant feet, welded thins): docs/HUNYUAN_MESH_AND_PARTS_LESSONS.md · Português.

Model findings hub (VRAM, SDNQ, kernels, Omni, vramd, paint/sky/mesh): docs/MODEL_FINDINGS.md · docs/findings/ · Omni docs/OMNI_SHAPE_FINDINGS.md · benches docs/KERNEL_OPTS_BENCH.md.

GLB compression (KTX2 + meshopt, text3d finish): docs/GLB_FINISH_COMPRESSION.md.

vramd batch waves (GameAssets shape/paint + optional GPU tools): docs/GAMEASSETS_UMS_BATCH.md.

Mission / premises (ease, automate, agent-first, VRAM-as-infra): docs/mission/ · summary in AGENTS.md.

File logging (all Python tools + vramd → ~/.cache/aigamekit/logs/): docs/LOGGING.md · Português.

Testing (coverage floor ≥100/tool, suite naming, CPU-first rules): docs/TESTING.md · Português.

Zero-to-game with AI (generative tools + orchestration + agents): docs/ZERO_TO_GAME_AI.md · Português.

Installation options

Useful variable: PYTHON_CMD (or --python on the installer) to force the interpreter.

One-liner (Clified / no clone)

Install the Clified engine and a AiGameKit tool in one step (~/.local/bin wrappers; repo public on GitHub):

Linux / macOS:

# Examples — replace <tool> with text2d, text3d, materialize, gameassets, vibegame, all, …
curl -fsSL https://raw.githubusercontent.com/maikramer/clified/main/install.sh | bash -s -- --get text2d
curl -fsSL https://raw.githubusercontent.com/maikramer/clified/main/install.sh | bash -s -- --get materialize
curl -fsSL https://raw.githubusercontent.com/maikramer/clified/main/install.sh | bash -s -- --catalog   # list all

Windows (PowerShell):

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/maikramer/clified/main/install.ps1))) --get text2d
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/maikramer/clified/main/install.ps1))) --get materialize

Catalog keys match tools.yaml entries: text2d, text3d, texture2d, skymap2d, text2sound, terrain3d, rocks3d, gameassets, aigamekitlab, paint3d, part3d, rigging3d, animator3d, materialize, vibegame, or all for every tool in the checkout.

Installer via Clified (from clone)

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 paint3d                    # Paint3D (texturing + nvdiffrast)
./install.sh rigging3d                  # Rigging3D (SkinTokens + PyTorch/CUDA via installer)
./install.sh animator3d                 # Animator3D (bpy / animation; no PyTorch)
./install.sh aigamekitlab                 # AiGameKitLab (debug 3D, benches, profiling)
./install.sh terrain3d                  # Terrain3D (AI terrain; CUDA GPU)
./install.sh rocks3d                    # Rocks3D (procedural rocks)
./install.sh vibegame                   # VibeGame (Bun + Vite 3D engine)
./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 paint3d
.\install.ps1 rigging3d
.\install.ps1 animator3d
.\install.ps1 aigamekitlab
.\install.ps1 terrain3d
.\install.ps1 rocks3d
.\install.ps1 vibegame
.\install.ps1 all

# Windows CMD (same: `install.bat` passes the interpreter to the installer)
install.bat materialize

Equivalent with Shared installed: aigamekit-install text2d, aigamekit-install all, etc. (list: aigamekit-install --list).

Unified installer options:

Manual installation

# 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. 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

# 5. 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

# 6. Texture2D (seamless textures via pattern-diffusion; local GPU + PBR via Materialize)
cd ../Texture2D && chmod +x scripts/setup.sh && ./scripts/setup.sh && source .venv/bin/activate && texture2d --help

# 7. Skymap2D (equirectangular 360° skymaps; local FLUX.1-dev + LoRA)
cd ../Skymap2D && chmod +x scripts/setup.sh && ./scripts/setup.sh && source .venv/bin/activate && skymap2d --help

# 8. Text2Sound (text-to-audio; Stable Audio 3 Small music/sfx; needs CUDA)
cd ../Text2Sound && chmod +x scripts/setup.sh && ./scripts/setup.sh && source .venv/bin/activate && text2sound --help

# 9. Rigging3D (CUDA GPU; Python 3.13; SkinTokens — prefer ./install.sh rigging3d)
cd ../Rigging3D && pip install -e ".[inference,dev]" && rigging3d --help

# 10. 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

# 11. Materialize (Rust — needs cargo)
cd ../Materialize && ./install.sh

# 12. AiGameKitLab (debug 3D, benches, profiling; no PyTorch required)
cd ../AiGameKitLab && python -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]" && aigamekit-lab --help

# 13. Terrain3D (AI terrain; CUDA GPU)
cd ../Terrain3D && python -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]" && terrain3d --help

Full instructions: docs/INSTALLING.md (incl. registering new tools via tools.yaml), Shared/README.md, and each package README.

Licenses

Note: weights have their own licenses. 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.

Environment variables

The monorepo uses environment variables to locate binaries and configure behavior:

Logs: ~/.cache/aigamekit/logs/<tool>-YYYY-MM-DD.log (vramd → vramd-….log). Console stays Rich/ANSI; file is plain text with UTC timestamps. Full guide: docs/LOGGING.md.

Unified Model Server (vramd)

Every GPU tool (Text2D, Text2Icon, Text3D, Paint3D, Part3D, Texture2D, Skymap2D, Text2Sound, Terrain3D) delegates generation to the Unified Model Server — a single supervisor process that owns the machine's VRAM. One socket (~/.cache/aigamekit/model-server.sock), one process, global model inventory, no per-tool servers.

How it works:

1. Tool CLIs call delegate_to_vramd before any in-process GPU prep; the vramd auto-starts on first generate (disable with VRAMD_AUTO_START=0).
2. Jobs go through JobQueue → AffinityScheduler → WorkerPool (MAX_INFLIGHT=1 — one generation at a time).
3. Each backend is a persistent subprocess worker in the tool's own venv (JSONL stdin/stdout) — after editing tool code, vramd respawn <backend> reloads it without restarting the supervisor.
4. Queue priority: interactive (CLI) > batch (GameAssets sets VRAMD_PRIORITY=batch). VRAM-affinity skips cold backends (≤3 cuts), then weight + LRU eviction keeps VRAM inside safe margins.
5. hw-auto fills peak signals (SDNQ preset, memory-efficient) in the vramd payload — no operator --low-vram flag.

vramd start | stop | status | submit | queue | wait | cancel | flush | backends | preload | evict | reap | respawn | zero | stats | debug | bench | doctor
vramd status                    # backends + HOLDING/QUEUE
vramd queue                     # jobs + timings
vramd wait <job_id>             # block until a job finishes
vramd respawn <backend>         # reload edited tool code in the worker

Tool flags: --vramd-priority interactive|batch, --no-vramd, --vramd-stream. WAL: ~/.cache/aigamekit/vramd-jobs.jsonl. Full guide: Vramd/README.md.

Models & HF gates

Gated models require accepting terms on the Hugging Face Hub (and HF_TOKEN set) before the weights download. Everything runs locally — the Hub is only a weight source, never an inference API.

Development

Quality tooling

Makefile (GNU Make)

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-aigamekitlab # Pytest AiGameKitLab 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 hooks

Windows: requires GNU Make (Git Bash, MSYS2, or WSL).

Dev setup

# 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 fmt

pyproject.toml

Each Python package has a pyproject.toml (PEP 621) with metadata, dependencies, and pytest config. Existing setup.py files remain for legacy installer compatibility.

References

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): 3D engine own package aigamekit-vibegame. See VibeGame/README.md.

Contributing

• Prefer small commits and Conventional Commits-style messages.
• Virtual environments and caches are ignored: root .gitignore aligns with subfolders.
• Run make check before opening PRs.
• Each tool has [project.optional-dependencies] dev in pyproject.toml — use pip install -e ".[dev]" before running tests.
• Documentation: keep README.md (English) and optional README_PT.md, and docs/ when present, up to date.