docs: update monorepo README and AGENTS for TerrainGen and VibeGame

Document TerrainGen, terrain/LOD-related workflows, and installer notes.

Made-with: Cursor

Author: maikramer

AGENTS.md

@@ -320,15 +320,15 @@ VibeGame has its own CI workflow in `VibeGame/.github/workflows/` (Bun + TypeScr
 
 ## Learned Workspace Facts
 
-- Terreno tipo voxel em exemplos VibeGame: amostragem multi-ponto ou suavização costuma ser necessária para alinhar props ao chão; árvores a flutuar/enterrar ligam-se em grande parte a GLB com origem ao centro do mesh — preferir origem na base na pipeline (Text3D/GameAssets), com pivô ao centro só quando fizer sentido para o tipo de asset.
+- Terreno em exemplos VibeGame pode parecer voxel/escadinha; amostragem de altura/normal com um único ponto tende a falhar — estratégias multi-amostra ou suavização costumam ser necessárias para alinhar props ao chão. Problemas de árvores a flutuar ou enterrar foram atribuídos em grande parte a pivô/origem do GLB no centro do mesh em vez da base; o utilizador espera que a pipeline Text3D/GameAssets posicione a origem na base por omissão, com pivô ao centro só quando explicitamente adequado ao tipo de asset. No recipe `<Terrain>`, muitos campos do componente `Terrain` são configuráveis por atributos XML em kebab-case (defaults do plugin); `collision-resolution` (32/64/128) é aplicado ao `TerrainLOD`/`three-terrain-lod` sem ser sobrescrito pela `resolution` da malha do chunk.
 - O comando `gameassets mesh reorigin-feet` repõe a origem de GLBs estáticos nos pés/base; modelos rigged com animação podem precisar de correção de orientação de root (ex. rotação) antes de centrar o pivô — não aplicar só `reorigin-feet` sem validar o resultado.
+- Text3D / Hunyuan3D (marching cubes): saídas costumam ter paredes grossas/duplas e rachas minúsculas; no repair convém merge/manifold e fechar só buracos muito pequenos antes de watertight, para solidificar a caixa sem tratar a abertura grande da base (ex. crate após remover pedestal) como defeito a tapar em bloco.
 - O comando `vibegame run` foi concebido para rebuild/atualização da engine face a exemplos que usam `file:vibegame`; em Windows podem ocorrer falhas de cópia/cache (`ENOENT` no pacote `vibegame`) e é preciso alvo/cwd coerente com a raiz da engine ou exemplo com `dev` ligado à engine.
-- O modelo HF Flux-LoRA-Equirectangular-v3 devolve imagens em resolução errada (1024×768 em vez do pedido 2048×1024) e com os polos ao centro vertical em vez das bordas; Skymap2D `generator.py` faz auto-resize e shift vertical de 50% para corrigir.
-- Equirect e PMREM no Three.js: o `PMREMGenerator` ignora `texture.offset`/`repeat` — ajustar UV no bitmap antes de `fromEquirectangular()`. Convenção: `u = atan(dir.z, dir.x)`, `v = asin(dir.y)`; texturas em retrato ou com eixos trocados podem causar artefactos «pilares» — normalizar para 2:1 em paisagem antes do PMREM quando necessário.
+- Skymap2D e equirect/PMREM: o modelo HF Flux-LoRA-Equirectangular-v3 devolve imagens em resolução errada (1024×768 em vez do pedido 2048×1024) e com os polos ao centro vertical em vez das bordas; Skymap2D `generator.py` faz auto-resize e shift vertical de 50% para corrigir. O `PMREMGenerator` do Three.js ignora `texture.offset`/`repeat` no shader interno — para ajustar UV de texturas equirect antes de `fromEquirectangular()` é necessário manipular o bitmap a nível de píxeis (canvas). Convenção equirect Three.js: `u = atan(dir.z, dir.x)`, `v = asin(dir.y)` — centro da imagem = horizonte, topo = zénite, fundo = nadir. Texturas equirect em **retrato** (altura > largura) ou com eixos trocados podem mapear o azimute ao eixo vertical do bitmap e produzir artefactos tipo «pilares» no céu; convém normalizar para panorama 2:1 em paisagem antes do PMREM quando isso ocorrer.
 - Dependências de screen-space / pós-processamento (ex. `screen-space-reflections`) podem importar símbolos removidos ou renomeados no Three.js (ex. `WebGLMultipleRenderTargets`), falhando no Vite com «No matching export» até alinhar versões do Three ou substituir o efeito. Em áudio Web, `AudioContext` bloqueado ou `listener.positionX` indisponível costuma ligar-se a autoplay sem gesto do utilizador e/ou à ausência de cadeia válida `AudioListener` + câmera principal.
 - O conteúdo sob `<Scene>` no VibeGame é injetado como HTML (`innerHTML`); a tag nativa **`<script>`** não serve para marcar módulos TS do motor — usar atributo `script` nos recipes ou um nome de elemento que não colida com HTML.
-- No recipe `<Terrain>`, muitos campos do componente `Terrain` são configuráveis por atributos XML em kebab-case (defaults do plugin); `collision-resolution` (32/64/128) é aplicado ao `TerrainLOD`/`three-terrain-lod` sem ser sobrescrito pela `resolution` da malha do chunk.
-- Corpos dinâmicos GLTF no VibeGame podem ter colisor desalinhado do mesh visível se o centro do AABB não coincidir com a origem da entidade; é necessário definir `Collider.posOffset*` a partir do delta AABB→Transform em espaço local.
-- No plugin de partículas (`three.quarks`), o simulador usa o emissor interno `ParticleSystem.emitter`; adicionar à cena um wrapper `ParticleEmitter` novo em vez desse nó faz o batch descartar o sistema no update e as partículas deixam de aparecer — integrar com `ps.emitter` diretamente.
+- Sem URL de heightmap no terreno, `TerrainLOD` / `@interverse/three-terrain-lod` pode gerar um heightmap procedural internamente; os ficheiros exportados pelo TerrainGen (`terrain.json`, `heightmap.png`, etc.) só têm efeito se o recipe/plugin apontar para eles — atributos XML não suportados podem ser ignorados em silêncio.
+- OpenCode (`opencode.json` no repositório): entradas MCP locais devem declarar `type: "local"` e `command` como array de strings com executável e argumentos (não o par `command` + `args` usado noutras ferramentas).
+- VibeGame: corpos dinâmicos GLTF podem ter colisor desalinhado do mesh se o centro do AABB não coincidir com a origem da entidade — definir `Collider.posOffset*` a partir do delta AABB→Transform em espaço local. No plugin de partículas (`three.quarks`), usar o emissor interno `ParticleSystem.emitter`; um wrapper `ParticleEmitter` à parte faz o batch descartar o sistema no update e as partículas deixam de aparecer.
 - No PyPI, `bpy==5.1.0` exige Python 3.13; o Rigging3D (inferência UniRig) fixa Python 3.11 com `bpy==5.0.1` e `open3d` porque não há combinação estável Open3D + `bpy` 5.1 no mesmo venv. O **Animator3D** usa stack **3.13 + `bpy==5.1.0`** em paralelo — não assumir um único Python/`bpy` para todo o monorepo.
 - O **Part3D** expõe quantização do DiT (modo `auto` ou bitsandbytes int8/int4) para reduzir VRAM na fase que mais pesa; `--no-quantize-dit` desliga essa optimização quando se quer precisão máxima.

README.md

@@ -27,6 +27,7 @@ Monorepo for **text-to-image**, **text-to-3D**, **text-to-audio**, **textures an
 | [**Animator3D**](Animator3D/) | **animator3d** — **bpy** 5.1; Python **3.13**; procedural clips, **`game-pack`** (humanoid/creature/flying presets), GLB export after rigging. |
 | [**Materialize**](Materialize/) | **PBR maps** CLI (Rust/wgpu): normal, AO, metallic, smoothness from a diffuse texture. |
 | [**GameDevLab**](GameDevLab/) | **Lab CLI**: debug 3D, quantization benches, profiling, pipeline optimization. |
+| [**TerrainGen**](TerrainGen/) | **terraingen** — Procedural terrain generation: heightmaps, erosion, rivers, lakes (Python 3.10+). |
 | [**VibeGame**](VibeGame/) | **vibegame** — TypeScript 3D engine (ECS, Three.js, declarative XML); **Bun** + **Vite**. See [VibeGame/README.md](VibeGame/README.md). |
 
 Each project has its own `README`, setup, requirements, and license. Portuguese: [`README_PT.md`](README_PT.md) (root) and per-package `README_PT.md` where provided.
@@ -47,6 +48,7 @@ GameDev/
   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
+  TerrainGen/        ← terraingen (pip) — depends on Shared; procedural terrain generation
   Materialize/       ← materialize-cli (cargo) — Python installer uses Shared
   VibeGame/          ← vibegame (npm/Bun + Vite) — browser 3D engine; standalone, not pip
 ```
@@ -96,6 +98,7 @@ The monorepo includes a unified installer for every registered tool:
 ./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 terraingen                 # TerrainGen (procedural terrain; no GPU)
 ./install.sh all                        # Install everything present
 
 # Windows PowerShell (recommended on Windows: script detects `python` and passes it to the installer)
@@ -112,6 +115,7 @@ The monorepo includes a unified installer for every registered tool:
 .\install.ps1 rigging3d
 .\install.ps1 animator3d
 .\install.ps1 gamedevlab
+.\install.ps1 terraingen
 .\install.ps1 all
 
 # Windows CMD (same: `install.bat` passes the interpreter to the installer)
@@ -183,6 +187,9 @@ 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. TerrainGen (procedural terrain; no GPU required)
+cd ../TerrainGen && python -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]" && terraingen --help
 ```
 
 Full instructions: [docs/INSTALLING.md](docs/INSTALLING.md), [docs/NEW_TOOLS.md](docs/NEW_TOOLS.md) (registering new tools), [Shared/README.md](Shared/README.md), and each package README.
@@ -191,7 +198,7 @@ Full instructions: [docs/INSTALLING.md](docs/INSTALLING.md), [docs/NEW_TOOLS.md]
 
 | Component | License | Note |
 |-----------|---------|------|
-| Monorepo code (Text2D, Text3D, Part3D, Paint3D, Texture2D, Skymap2D, Text2Sound, Rigging3D, Animator3D, GameAssets, GameDevLab, Shared) | MIT | See `LICENSE` in each folder |
+| Monorepo code (Text2D, Text3D, Part3D, Paint3D, Texture2D, Skymap2D, Text2Sound, Rigging3D, Animator3D, GameAssets, GameDevLab, TerrainGen, Shared) | MIT | See `LICENSE` in each folder |
 | Materialize CLI (Rust) | MIT | [Materialize/LICENSE](Materialize/LICENSE) |
 | FLUX.2 Klein 4B (official, BF16) | Apache 2.0 | [black-forest-labs/FLUX.2-klein-4B](https://huggingface.co/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](https://huggingface.co/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 |
@@ -216,6 +223,7 @@ The monorepo uses environment variables to locate binaries and configure behavio
 | `TEXT2SOUND_BIN` | GameAssets | Path to `text2sound` |
 | `MATERIALIZE_BIN` | GameAssets, Text3D | Path to `materialize` |
 | `GAMEDEVLAB_BIN` | GameAssets | Path to `gamedev-lab` |
+| `TERRAINGEN_BIN` | GameAssets | Path to `terraingen` |
 | `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 |
@@ -254,6 +262,7 @@ 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-terraingen # Pytest TerrainGen only
 make typecheck       # MyPy on Shared/src
 make check           # lint + fmt-check + typecheck + test (full CI)
 make clean           # Remove __pycache__, caches, builds

README_PT.md

@@ -27,6 +27,7 @@ Monorepo com ferramentas de **texto→imagem**, **texto→3D**, **texto→áudio
 | [**Animator3D**](Animator3D/) | **animator3d** — **bpy** 5.1; Python **3.13**; clips procedimentais, **`game-pack`** (presets humanoid/creature/flying), export GLB após rigging. |
 | [**Materialize**](Materialize/) | CLI **PBR maps** (Rust/wgpu): gera normal, AO, metallic, smoothness a partir de textura difusa. |
 | [**GameDevLab**](GameDevLab/) | **Lab CLI**: debug 3D, bancos de quantização, profiling, otimização de pipeline. |
+| [**TerrainGen**](TerrainGen/) | **terraingen** — Geração procedural de terreno: heightmaps, erosão, rios, lagos (Python 3.10+). |
 | [**VibeGame**](VibeGame/) | **vibegame** — motor 3D em TypeScript (ECS, Three.js, XML declarativo); **Bun** + **Vite**. Ver [VibeGame/README.md](VibeGame/README.md). |
 
 Cada projeto tem o seu próprio `README`, `setup`, requisitos e licença.
@@ -47,6 +48,7 @@ GameDev/
   Rigging3D/         ← rigging3d (pip) — Shared; inferência Py 3.11 + bpy 5.0.x
   Animator3D/        ← animator3d (pip) — Shared; Py 3.13 + bpy 5.1 (animação)
   GameDevLab/        ← gamedev-lab (pip) — depende de Shared; debug 3D, benches, profiling
+  TerrainGen/        ← terraingen (pip) — depende de Shared; geração procedural de terreno
   Materialize/       ← materialize-cli (cargo) — instalador Python usa Shared
   VibeGame/          ← vibegame (npm/Bun + Vite) — motor 3D no browser; standalone, não é pip
 ```
@@ -95,6 +97,7 @@ O monorepo inclui um instalador unificado que instala qualquer ferramenta regist
 ./install.sh paint3d                    # Paint3D (textura + nvdiffrast)
 ./install.sh rigging3d                  # Rigging3D (UniRig empacotado + PyTorch/CUDA via instalador)
 ./install.sh animator3d                 # Animator3D (bpy / animação; sem PyTorch)
+./install.sh terraingen                 # TerrainGen (terreno procedural; sem GPU)
 ./install.sh all                        # Instalar tudo
 
 # Windows PowerShell (recomendado no Windows: o script detecta `python` e passa-o ao instalador)
@@ -110,6 +113,7 @@ O monorepo inclui um instalador unificado que instala qualquer ferramenta regist
 .\install.ps1 paint3d
 .\install.ps1 rigging3d
 .\install.ps1 animator3d
+.\install.ps1 terraingen
 .\install.ps1 all
 
 # Windows CMD (idem: `install.bat` passa o interpretador ao instalador)
@@ -186,7 +190,7 @@ Instruções completas: [docs/INSTALLING_PT.md](docs/INSTALLING_PT.md), [docs/NE
 
 | Componente | Licença | Nota |
 |-----------|---------|------|
-| Código do monorepo (Text2D, Text3D, Part3D, Paint3D, Texture2D, Skymap2D, Text2Sound, Rigging3D, Animator3D, GameAssets, Shared) | MIT | Ver `LICENSE` em cada pasta |
+| Código do monorepo (Text2D, Text3D, Part3D, Paint3D, Texture2D, Skymap2D, Text2Sound, Rigging3D, Animator3D, GameAssets, GameDevLab, TerrainGen, Shared) | MIT | Ver `LICENSE` em cada pasta |
 | Materialize CLI (Rust) | MIT | [Materialize/LICENSE](Materialize/LICENSE) |
 | FLUX.2 Klein 4B (oficial, BF16) | Apache 2.0 | [black-forest-labs/FLUX.2-klein-4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B) — uso comercial permitido segundo o model card; mais VRAM que o SDNQ |
 | FLUX.2 Klein 4B SDNQ (default Text2D) | FLUX Non-Commercial (metadata HF) | [Disty0/FLUX.2-klein-4B-SDNQ-4bit-dynamic](https://huggingface.co/Disty0/FLUX.2-klein-4B-SDNQ-4bit-dynamic) declara `flux-non-commercial-license`; **não** é o mesmo regime que o checkpoint oficial Apache 2.0. Para produto comercial, prefira `TEXT2D_MODEL_ID=black-forest-labs/FLUX.2-klein-4B` ou acordo com a BFL |
@@ -210,6 +214,7 @@ O monorepo usa variáveis de ambiente para localizar binários e configurar comp
 | `TEXTURE2D_BIN` | GameAssets | Caminho para o binário `texture2d` |
 | `TEXT2SOUND_BIN` | GameAssets | Caminho para o binário `text2sound` |
 | `MATERIALIZE_BIN` | GameAssets, Text3D | Caminho para o binário `materialize` |
+| `TERRAINGEN_BIN` | GameAssets | Caminho para o binário `terraingen` |
 | `TEXT2D_MODEL_ID` | Text2D | Override do modelo HF para Text2D |
 | `TEXTURE2D_MODEL_ID` | Texture2D | Override do modelo HF para Texture2D |
 | `SKYMAP2D_MODEL_ID` | Skymap2D | Override do modelo HF para Skymap2D |