From dae1498a6fb1bc270be1476e26f5396910d6afe8 Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Tue, 16 Jun 2026 22:36:13 +0200 Subject: [PATCH] docs(assets): ratify 3D asset direction (D-244); repurpose sprite-gen as 2D-artwork generator D-244 ratifies what the character architecture (D-159..D-164, runtime CharacterVisualDescriptor compositing) and the Trellis env pipeline already implied but no decision had recorded: the in-world view renders 3D objects directly; the only flattened 2D content is textures + flat 2D artwork (paintings/flags/billboards/signage). There is no per-object sprite layer. Roots out the drift: the early-spike 3D->2D sprite pipeline (#541) and the sprite-centric docs/assets/visual catalog were never cleaned out when the project went 3D, so the 2026-06-12 fable-ous audit read them as live and re-injected the dead sprite model into T-1049/T-1050. Fix: - docs/assets/visual/README.md + docs/assets/README.md re-scoped to 3D models + textures + flat artwork (dropped the sprites/tilesets-as-entities framing). - /sprite-gen + renderer/README repurposed as the 2D-artwork generator (paintings/flags/ billboards/signage), not the in-world object format; legacy 4-direction object-sprite mode flagged as retired. - T-961/T-1049/T-1050 already held in backlog pending this. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/skills/sprite-gen/SKILL.md | 72 +++++++++++++--------------- docs/assets/README.md | 14 +++--- docs/assets/visual/README.md | 30 +++++++----- governance/README.md | 1 + governance/decisions/architecture.md | 13 ++++- renderer/README.md | 13 ++++- 6 files changed, 80 insertions(+), 63 deletions(-) diff --git a/.claude/skills/sprite-gen/SKILL.md b/.claude/skills/sprite-gen/SKILL.md index be40ebf6f..63e5406f1 100644 --- a/.claude/skills/sprite-gen/SKILL.md +++ b/.claude/skills/sprite-gen/SKILL.md @@ -1,55 +1,47 @@ --- name: sprite-gen description: > - Render a 3D model to 2D sprites via the Godot render pipeline. Produces - sprites at 3 resolutions (1024, 256, 64) from 4 cardinal directions (north, - east, south, west) with outline applied at working resolution. Use when the - user says "render sprite", "render model", "run the render pipeline", - "test the pipeline", "/sprite-gen", or asks to render a specific model - (e.g., "render wall_structural"). Output: 12 PNG files in renderer/output/. + 2D-artwork generator for The Settled Reach — produces flat 2D art (paintings, + flags, billboards, signage, screen content) as PNG textures/decals applied to + flat surfaces in the otherwise-3D world (D-244). Use when the user says "render + artwork", "make a painting/flag/billboard", "2d art", "/sprite-gen", or asks to + produce flat decorative art. NOT for game objects or characters — those are 3D + (.glb via /glb-gen; characters via the Quaternius pipeline). Output: PNG files + in renderer/output/. --- +## What this is (D-244) + +Per **D-244**, the in-world view renders **3D objects directly**. The only flattened +2D content is **textures** (PBR maps on 3D surfaces) and **flat 2D artwork** — +paintings, flags, billboards, signage, screen content. This skill produces that flat +artwork via the Godot render pipeline at `renderer/`. + +**This is NOT the in-world object format.** Game objects/props are 3D `.glb` +(`/glb-gen`); characters are 3D meshes composited at runtime +(`CharacterVisualDescriptor`). This tool began as the #541 spike that rendered 3D +models to 4-direction sprites for a 2D view — that role is **retired** (D-244). It now +serves flat 2D artwork only. + ## Render Pipeline -Run the render script with the model name: - ```bash -.claude/skills/sprite-gen/scripts/render.sh +.claude/skills/sprite-gen/scripts/render.sh ``` -### Available Models +Scenes live at `renderer/models/.tscn`. The script still emits the legacy spike +layout — 12 PNGs in `renderer/output/` (4 cardinal directions × 3 resolutions: +1024/256/64). For **flat artwork** the relevant output is the single front (south) +view; the multi-direction output is legacy object-sprite behaviour. A flat-artwork +(single-view) mode for the render script is the natural follow-up. -Models live at `renderer/models/.tscn`. List them: +### After rendering -```bash -ls renderer/models/*.tscn | xargs -I{} basename {} .tscn -``` - -### Output - -12 files per model in `renderer/output/`: - -``` -_north_1024.png _north_256.png _north_64.png -_east_1024.png _east_256.png _east_64.png -_south_1024.png _south_256.png _south_64.png -_west_1024.png _west_256.png _west_64.png -``` - -### After Rendering - -1. Read the 64x64 output files to visually inspect the runtime sprites -2. Read the 256x256 files to check outline quality -3. Report: does it read as the intended object at runtime scale? +1. Inspect the output PNG — does it read as the intended artwork at in-world scale? +2. Promote the final PNG to `client/assets/` as the surface texture/decal. ### Troubleshooting -- **No output files**: Godot needs a display. If running headless, prefix with `xvfb-run`. -- **Model not found**: Check the model .tscn exists in `renderer/models/`. -- **Godot not found**: Pass path as second arg: `render.sh wall_structural /path/to/godot` - -### Adding New Models - -1. Create model scene at `renderer/models/.tscn` -2. Apply texture from `renderer/textures/` via StandardMaterial3D -3. Run: `.claude/skills/sprite-gen/scripts/render.sh ` +- **No output files:** Godot needs a display. If running headless, prefix with `xvfb-run`. +- **Scene not found:** check the `.tscn` exists in `renderer/models/`. +- **Godot not found:** pass the Godot path as the second arg: `render.sh /path/to/godot`. diff --git a/docs/assets/README.md b/docs/assets/README.md index d808c1ca7..48513aea2 100644 --- a/docs/assets/README.md +++ b/docs/assets/README.md @@ -24,7 +24,7 @@ docs/assets/ README.md # This file — master index _templates/ audio.md # Row template + detailed entry template for audio - sprite.md # Row template + detailed entry template for sprites + sprite.md # Row template for 2D artwork rows (paintings/flags/billboards — see /sprite-gen) video.md # Row template + detailed entry template for video audio/ README.md # Audio pipeline index — categories, status summary @@ -32,14 +32,14 @@ docs/assets/ ambient.md # All ambient loops (station, planet, biome, weather) sfx.md # All SFX (footsteps, doors, impacts, events) ui.md # All UI sounds (cursor, chimes, insert-tech) - visual/ + visual/ # 3D models + textures + flat artwork (D-244 — no per-object sprites) README.md # Visual pipeline index palette.md # Art direction, "the angle", color relationships - sprites.md # Entities (NPCs, player, creatures) - furniture.md # Furniture items (hundreds, by location/type) - tilesets.md # Floor/wall tiles by biome/planet - icons.md # UI icons, status indicators - effects.md # Fog shaders, particles, overlays + models.md # 3D objects/props (.glb via Trellis /glb-gen) + textures.md # PBR surface maps (BaseColor/Normal/Roughness) for 3D models + artwork.md # Flat 2D art — paintings, flags, billboards, signage (via /sprite-gen) + icons.md # UI icons, status indicators (UI layer) + effects.md # Shaders, particles, overlays video/ README.md # Video pipeline index palette.md # Motion/editing style guide diff --git a/docs/assets/visual/README.md b/docs/assets/visual/README.md index 1e5d885c0..f42bf8a6b 100644 --- a/docs/assets/visual/README.md +++ b/docs/assets/visual/README.md @@ -1,6 +1,6 @@ --- title: "Visual Asset Pipeline" -description: "Visual pipeline index covering sprites, furniture, tilesets, icons, and effects with render pipeline overview" +description: "Visual pipeline index — 3D models, textures, and flat 2D artwork (D-244)" type: design status: active --- @@ -9,28 +9,32 @@ status: active Status: **Stub** — awaiting first visual sprint. +Per **[D-244](../../../governance/decisions/architecture.md#d-244)**: the in-world view renders **3D objects directly**. The only flattened 2D content is **textures** (PBR maps on 3D surfaces) and **flat 2D artwork** (paintings, flags, billboards, signage) applied as textures/decals on flat surfaces *within* the 3D world. **There is no per-object sprite layer** — game objects are not pre-rendered to sprites. + ## Categories | Category | File | Count | Description | |----------|------|-------|-------------| -| Sprites | [sprites.md](sprites.md) | 0 | Entity sprites via 3D render pipeline | -| Furniture | [furniture.md](furniture.md) | 0 | Furniture items by location/type | -| Tilesets | [tilesets.md](tilesets.md) | 0 | Floor/wall tiles by biome/planet | -| Icons | [icons.md](icons.md) | 0 | UI icons, status indicators | -| Effects | [effects.md](effects.md) | 0 | Fog shaders, particles, overlays | +| Models | [models.md](models.md) | 0 | 3D objects/props (`.glb`) via Trellis (`/glb-gen`), promoted per [D-241] | +| Characters | — | — | 3D meshes composited at runtime via `CharacterVisualDescriptor` — see [character-asset-organization.md](../../architecture/character-asset-organization.md) | +| Textures | [textures.md](textures.md) | 0 | PBR surface maps (BaseColor / Normal / Roughness) for 3D models | +| Artwork | [artwork.md](artwork.md) | 0 | Flat 2D art — paintings, flags, billboards, signage, screen content — applied as textures/decals (via the `/sprite-gen` 2D-artwork generator) | +| Icons | [icons.md](icons.md) | 0 | UI icons, status indicators (2D, UI layer only) | +| Effects | [effects.md](effects.md) | 0 | Shaders, particles, overlays | ## Palette -See [palette.md](palette.md) for art direction, "the angle", color relationships, and render pipeline specs. +See [palette.md](palette.md) for art direction, "the angle", and colour relationships. ## Pipeline -- **3D render pipeline:** Blender model → Godot Camera3D at -72.5deg → orthographic render → outline pass → resolution downscale -- **Render skill:** `/sprite-gen` produces 12 PNGs (4 directions x 3 resolutions) -- **Art direction workshop:** `docs/workshops/art-direction-mood-board/` +- **3D objects / props:** concept image (`/image-gen`) → Trellis image→3D (`/glb-gen`) → `.glb` → promoted to `client/assets/models/`. +- **Characters:** Quaternius source meshes, segmented + rigged, composited at runtime from slots (`CharacterVisualDescriptor`); see the character-asset doc. +- **Textures:** PBR maps authored/generated for 3D surfaces. +- **2D artwork** (paintings / flags / billboards / signage): the `/sprite-gen` **2D-artwork generator** → flat PNG → applied as a texture/decal on a flat surface in the 3D world. ## Decision References -- D-019: Top-down camera, 15-20deg from vertical ("the angle") -- D-033: Entity color = relationship to player -- D-045: Environmental neutrality +- **[D-244](../../../governance/decisions/architecture.md#d-244):** 3D objects in-world; 2D limited to textures + flat artwork. +- D-159–D-164: character 3D pipeline. D-241: asset promotion. +- D-019: top-down camera, "the angle". D-033: entity colour = relationship to player. D-045: environmental neutrality. diff --git a/governance/README.md b/governance/README.md index 83569f231..77556b834 100644 --- a/governance/README.md +++ b/governance/README.md @@ -309,6 +309,7 @@ line in place — keep the Q-record for the audit trail rather than deleting it. - [D-241: Spike binary artifacts are local-only — gitignored, never tracked](decisions/process.md#d-241-spike-binary-artifacts-are-local-only--gitignored-never-tracked) — _process_ - [D-242: Corp HQ settlement model — HQs are not cities; separate from the name pool, specialization-keyed, install-baked](decisions/architecture.md#d-242-corp-hq-settlement-model--hqs-are-not-cities-separate-from-the-name-pool-specialization-keyed-install-baked) — _architecture_ - [D-243: Spatial scale ladder — nested absolute containment with a single elastic planetary seam (resolves Q-110)](decisions/architecture.md#d-243-spatial-scale-ladder--nested-absolute-containment-with-a-single-elastic-planetary-seam-resolves-q-110) — _architecture_ +- [D-244: Asset rendering — 3D objects in-world; 2D limited to textures + flat artwork](decisions/architecture.md#d-244-asset-rendering--3d-objects-in-world-2d-limited-to-textures--flat-artwork) — _architecture_ ## Open questions diff --git a/governance/decisions/architecture.md b/governance/decisions/architecture.md index 3a87c4b06..a352134ef 100644 --- a/governance/decisions/architecture.md +++ b/governance/decisions/architecture.md @@ -1842,4 +1842,15 @@ Technical foundation decisions that constrain implementation: engine, client-ser --- -*100 decisions (D-001 through D-243, excluding gaps). Last updated: 2026-06-14 (spatial scale ladder — D-243 resolves Q-110: nested absolute containment voxel→chunk→block→quarter→district→region with a single elastic region↔planet seam; region is the climate/weather lockdown scale + planetary grid, edge-fuzzed; the 1 km RegionProfile is dropped onto the district; D-201 tier-4 Region→Province; ladder recorded in CLAUDE.md).* +### D-244: Asset rendering — 3D objects in-world; 2D limited to textures + flat artwork +- **Date:** 2026-06-16 +- **Decision:** The in-world view renders **3D objects directly**. Environment and props come from the Trellis image→3D `.glb` pipeline (`/glb-gen`, promoted per [D-241](#d-241)); characters come from the Quaternius 3D-mesh pipeline composited at runtime via `CharacterVisualDescriptor` ([D-159](#d-159)–[D-164](#d-164): 11 body types, segmented regions, separate head mesh, slot system, shape keys, region tints). The **only flattened 2D content** is **(a) textures** (PBR maps on 3D surfaces) and **(b) flat 2D artwork** — paintings, flags, billboards, signage, screen content — images that live as textures/decals on flat surfaces *within* the 3D world. There is **no per-object sprite layer**: game objects are not pre-rendered to 2D sprites for display. +- **Rationale:** The character system is irreducibly 3D — runtime slot compositing across body × head × hair × clothing × skin-tone × colour-overrides × shape-keys × directions × animation-frames cannot be expressed as pre-rendered sprites without combinatorial explosion. The 3D direction was already implicit in the character architecture (the 2026-03-19 character-asset doc states "no mesh work from the spikes carries over") and the Trellis environment pipeline, but was never ratified — so the retired 2D-sprite assumption drifted on in tooling and docs. +- **What this retires / repurposes:** the early-spike **3D→2D-sprite render pipeline** (`renderer/`, the `/sprite-gen` skill, added in #541) is **not** the in-world format. It is **repurposed as the 2D-artwork generator** — producing the flat paintings/flags/billboards/signage assets in (b). The sprite-centric asset catalog (`docs/assets/visual/` sprites/tilesets framing, `_templates/sprite.md`) is re-scoped to a **3D-model + texture + artwork** catalog. +- **Root-cause note:** T-1049/T-1050 (the 2026-06-12 `fable-ous.md` audit) re-injected the dead sprite model because the retired spike scaffolding sat in the repo as live ground truth with no decision marking it dead. This record is that marker; T-961/T-1049/T-1050 are held in backlog pending re-scope. +- **Cross-reference:** [D-159](#d-159)–[D-164](#d-164) (character 3D pipeline), [D-241](#d-241) (asset promotion), [D-227](#d-227) (derive/synthesise, don't store). Phase 5 (in-world rendering) builds on this. +- **Dissent:** None + +--- + +*101 decisions (D-001 through D-244, excluding gaps). Last updated: 2026-06-16 (D-244 — asset rendering direction: 3D objects in-world (Trellis environment + Quaternius characters via CharacterVisualDescriptor); 2D limited to textures + flat artwork (paintings/flags/billboards/signage); the early-spike sprite-render pipeline is repurposed as the 2D-artwork generator, not the in-world format; re-scopes T-961/T-1049/T-1050).* diff --git a/renderer/README.md b/renderer/README.md index 1725f24ab..9b57a18b0 100644 --- a/renderer/README.md +++ b/renderer/README.md @@ -1,6 +1,15 @@ -# Settled Reach — Sprite Render Pipeline +# Settled Reach — 2D Artwork Render Pipeline -Offline Godot 4 renderer for the 3D-to-2D sprite pipeline. Produces entity and structural sprites at three resolutions from a fixed camera angle, with outlines applied at working resolution. +> **Repurposed (D-244).** This offline Godot renderer is **not** the in-world object +> format. Per [D-244] the in-world view renders 3D objects directly (props via Trellis +> `.glb` / `/glb-gen`; characters via the Quaternius pipeline + `CharacterVisualDescriptor`); +> the only flattened 2D content is **textures** and **flat 2D artwork** (paintings, flags, +> billboards, signage). This pipeline began as the #541 3D-to-2D *sprite* spike and now +> serves that flat artwork. The "render every entity/object/wall to sprites" framing below +> is **legacy** (the retired object-sprite use); the camera / lighting / resolution mechanics +> remain usable for flat-artwork rendering. + +Offline Godot 4 renderer. Produces flat 2D artwork (and, in its legacy mode, 3D-to-2D sprites) at three resolutions from a fixed camera angle, with outlines applied at working resolution. ## Camera Specification (D-019)