From f77e15d075d34cbb7854c0dd89887f6a8b80534f Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Sat, 25 Jul 2026 20:20:04 +0200 Subject: [PATCH] docs(assets): 3D-model+texture catalog, glb-gen production path, conventions (T-1050) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Instantiates the five D-244 catalog files (models/textures/artwork/icons/ effects — icons carries the 13 as-built SVGs, stance icons traced to their consumer and marked final), creates client/assets/models/{furniture,props} with a schema-documented manifest.json mirroring the character manifest, fixes glb-gen SKILL.md's stale 'path does not exist' paragraph, and authors docs/assets/visual/conventions.md: category-first model naming (araminta ruling), mask sidecars per the character convention, D-235-token-keyed texture naming, footprint_tiles as manifest metadata. Door-state and TileSet conventions are recorded as explicit deferrals (Phase-5 owned). visual/README.md carries both this ticket's count/link updates and T-1052's palette-section rewrite (shared file, committed here). Co-Authored-By: Claude Fable 5 --- .claude/skills/glb-gen/SKILL.md | 13 +- client/assets/models/furniture/.gitkeep | 0 client/assets/models/manifest.json | 24 ++++ client/assets/models/props/.gitkeep | 0 docs/assets/README.md | 3 +- docs/assets/visual/README.md | 12 +- docs/assets/visual/artwork.md | 41 ++++++ docs/assets/visual/conventions.md | 164 ++++++++++++++++++++++++ docs/assets/visual/effects.md | 41 ++++++ docs/assets/visual/icons.md | 50 ++++++++ docs/assets/visual/models.md | 48 +++++++ docs/assets/visual/textures.md | 42 ++++++ 12 files changed, 429 insertions(+), 9 deletions(-) create mode 100644 client/assets/models/furniture/.gitkeep create mode 100644 client/assets/models/manifest.json create mode 100644 client/assets/models/props/.gitkeep create mode 100644 docs/assets/visual/artwork.md create mode 100644 docs/assets/visual/conventions.md create mode 100644 docs/assets/visual/effects.md create mode 100644 docs/assets/visual/icons.md create mode 100644 docs/assets/visual/models.md create mode 100644 docs/assets/visual/textures.md diff --git a/.claude/skills/glb-gen/SKILL.md b/.claude/skills/glb-gen/SKILL.md index cc41c47e2..5d6c46930 100644 --- a/.claude/skills/glb-gen/SKILL.md +++ b/.claude/skills/glb-gen/SKILL.md @@ -95,11 +95,14 @@ Always mirror the category/subcategory path across stages so you can trace Final game-ready assets are copied to `spikes/3dpipeline/models/` for spike testing. For production, character GLBs go to `client/assets/characters/` (already in active use — see its `bodies/`, `clothing/`, `hair/`, -`skeleton/`, etc. subdirectories). `client/assets/models/` does not exist — -there is no established production path yet for non-character categories -(furniture, props); that's a Phase-5 concern (Player control & in-world -rendering, per CLAUDE.md's Development Cascade). Until then, keep -non-character output staged under `.tmp/glb-gen/postproc/`. +`skeleton/`, etc. subdirectories). Non-character categories (furniture, +props) go to `client/assets/models/{furniture,props}/` — register every +promoted asset in `client/assets/models/manifest.json` (schema documented +inline in that file; mirrors the character manifest's per-item pattern). +Promotion = repo-canonical (D-241): an asset entering the manifest AND +`client/assets/models/` **is** the promotion act — nothing stays "promoted" +in `spikes/`. Naming, mask-sidecar, and texture conventions are in +`docs/assets/visual/conventions.md`. ## Post-process in Blender diff --git a/client/assets/models/furniture/.gitkeep b/client/assets/models/furniture/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/client/assets/models/manifest.json b/client/assets/models/manifest.json new file mode 100644 index 000000000..5214e5788 --- /dev/null +++ b/client/assets/models/manifest.json @@ -0,0 +1,24 @@ +{ + "_comment": "Environment prop/furniture manifest — schema mirrors client/assets/characters/manifest.json's per-item entry pattern (see docs/architecture/character-asset-organization.md). Keyed by asset name (matches the .glb basename, no extension). One entry per asset, NOT per-body-type variant — environment props are not body-fitted (D-244). An asset entering this manifest AND client/assets/models/ IS the promotion act (D-241); nothing stays 'promoted' in spikes/. Naming/mask-sidecar/texture conventions: docs/assets/visual/conventions.md.", + "_fields": { + "name": "string — asset name, matches the manifest key and the .glb basename", + "category": "string — 'furniture' | 'props' (matches the subdirectory)", + "source_model": "string — path to the .glb under client/assets/models/, e.g. 'furniture/table_baroque.glb'", + "subdirectory": "string — 'furniture' | 'props' (same as category; kept as its own field to match the character-manifest precedent of not deriving one field from another)", + "status": "string — planned | in-progress | placeholder | final (docs/assets/README.md vocab — shared with the catalog tables so manifest and catalog never disagree)", + "footprint_tiles": "[width, height] — multi-tile sim footprint in whole tiles (1 tile = 1m, D-243). Omit (or [1, 1]) for single-tile props.", + "mask": "string, optional — path to the recolor mask sidecar, e.g. 'furniture/table_baroque_mask.png'. Omit if the asset has no tintable region." + }, + "_example_only_not_a_real_asset": { + "table_baroque": { + "category": "furniture", + "source_model": "furniture/table_baroque.glb", + "subdirectory": "furniture", + "status": "planned", + "footprint_tiles": [2, 1], + "mask": "furniture/table_baroque_mask.png" + } + }, + "furniture": {}, + "props": {} +} diff --git a/client/assets/models/props/.gitkeep b/client/assets/models/props/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/assets/README.md b/docs/assets/README.md index 991a0d03e..81f6aeec1 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 # LEGACY object-sprite row template (D-244 retired sprites; model/texture/artwork template TBD) + sprite.md # LEGACY object-sprite row template (D-244 retired sprites; model/texture/artwork rows are inline in each visual/*.md file, T-1050) video.md # Row template + detailed entry template for video audio/ README.md # Audio pipeline index — categories, status summary @@ -40,6 +40,7 @@ docs/assets/ 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 + conventions.md # Model naming, mask sidecars, D-235-keyed texture naming, footprint metadata (T-1050) 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 f42bf8a6b..c5500d3a5 100644 --- a/docs/assets/visual/README.md +++ b/docs/assets/visual/README.md @@ -7,7 +7,8 @@ status: active # Visual Asset Pipeline -Status: **Stub** — awaiting first visual sprint. +Status: **Active** — catalog structure instantiated (T-1050); awaiting first +model/texture/artwork/effects production 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. @@ -19,12 +20,17 @@ Per **[D-244](../../../governance/decisions/architecture.md#d-244)**: the in-wor | 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) | +| Icons | [icons.md](icons.md) | 13 | UI icons, status indicators (2D, UI layer only) — as-built inventory of `client/assets/icons/` | | Effects | [effects.md](effects.md) | 0 | Shaders, particles, overlays | +Naming, mask-sidecar, D-235-keyed texture, and multi-tile footprint +conventions: [conventions.md](conventions.md). + ## Palette -See [palette.md](palette.md) for art direction, "the angle", and colour relationships. +See [palette.md](palette.md) for art direction: camera (D-148 gameplay / D-019 +offline-render), the toon-vs-PBR rendering treatment for environment props, the +D-235 ObjectTag color/material register, and entity colour relationships (D-033). ## Pipeline diff --git a/docs/assets/visual/artwork.md b/docs/assets/visual/artwork.md new file mode 100644 index 000000000..f9c7a794b --- /dev/null +++ b/docs/assets/visual/artwork.md @@ -0,0 +1,41 @@ +--- +title: "Artwork — Visual Assets" +description: "Flat 2D artwork asset catalog — paintings, flags, billboards, signage, screen content" +type: design +status: active +--- + +# Artwork — Visual Assets + +Flat 2D art — paintings, flags, billboards, signage, screen content — that +lives as a texture/decal on a flat surface *within* the 3D world. This is one +of the two flattened-2D exceptions under D-244 (the other is +[textures.md](textures.md)); it is not a sprite layer. + +## Generation Approach + +Produced via the `/sprite-gen` skill's **repurposed 2D-artwork role** +(`renderer/README.md`) — the offline Godot renderer originally built for the +retired object-sprite pipeline (#541 spike), now serving flat-artwork +rendering. Camera/lighting/resolution mechanics from that pipeline are +reused; the "render every entity/object/wall to sprites" framing in +`renderer/README.md` is legacy and does not apply here. + +Output is promoted to `client/assets/artwork/` (per `renderer/README.md`'s +own note: flat-artwork output goes to `client/assets/textures` or +`client/assets/artwork`, never `client/assets/sprites/`). + +## Assets + +| ID | Filename | Status | Type | Notes | Sprint/Ticket | +|----|----------|--------|------|-------|---------------| + +No artwork has entered production yet — this table is intentionally empty at +initial creation (T-1050). + +## Cross-References + +- [conventions.md](conventions.md) +- `renderer/README.md` — repurposed 2D-artwork render pipeline +- `.claude/skills/sprite-gen/SKILL.md` +- [D-244](../../../governance/decisions/architecture.md#d-244-asset-rendering--3d-objects-in-world-2d-limited-to-textures--flat-artwork) diff --git a/docs/assets/visual/conventions.md b/docs/assets/visual/conventions.md new file mode 100644 index 000000000..5e930bbdd --- /dev/null +++ b/docs/assets/visual/conventions.md @@ -0,0 +1,164 @@ +--- +title: "Visual Asset Conventions" +description: "Model naming, mask sidecars, D-235-keyed texture naming, and multi-tile footprint metadata for the 3D asset pipeline" +type: design +status: active +--- + +# Visual Asset Conventions + +Single home for 3D-model and texture naming conventions (D-244 — the in-world +view renders 3D objects directly; there is no per-object sprite layer). This +file is the cross-link target from `.claude/skills/glb-gen/SKILL.md` and the +catalog files in `docs/assets/visual/`. + +--- + +## 1. Model naming + +Format: `_.glb` + +Examples: `table_baroque.glb`, `chair_modernist.glb`, `door_sliding.glb`. + +**Ruling (delegated to Araminta, art seat, batch-5 activation — T-1052): +category-first, not descriptor-first.** Rationale: category-first matches +the shipped, in-active-use character-asset clothing convention +(`_` — `jacket_modern.glb`, `boots_modern.glb`, +`pants_formal.glb`, all live under `client/assets/characters/clothing/`) and +gives every future asset browser/manifest a stable alphabetical grouping by +type (all tables sort together, all chairs sort together). The 3dpipeline +spike's descriptor-first naming (`baroque_table.glb`, `modernist_chair.glb`, +`spikes/3dpipeline/README.md`) was pre-convention scratch work, not a +precedent to preserve — D-241 already treats spike naming as disposable at +promotion time. **Surfaced to Jeroen for cheap veto** (lead delegation note, +T-1050). + +`category` is the subdirectory-agnostic object type (`table`, `chair`, +`door`, `lamp`, `statue`); `descriptor` distinguishes style/variant +(`baroque`, `modernist`, `sliding`). Category is not required to match the +`furniture`/`props` subdirectory name — a `statue` and a `table` can both be +`furniture` or both be `props` depending on where they land; the manifest's +`category` field, not the filename, is authoritative for that split. + +--- + +## 2. Mask sidecars + +Convention: `_mask.png`, single-channel (R-only greyscale), sitting +next to the GLB — per the character-asset convention (Section 3, +`docs/architecture/character-asset-organization.md`). White = tintable +region, black = preserve original texture (`hint_default_black`: no mask +loaded = no tinting; assets without a mask render with their original +Trellis/authored texture). + +Example: `table_baroque.glb` + `table_baroque_mask.png` (this is the existing +Trellis convention already proven in the 3dpipeline spike, just re-ordered to +category-first per Section 1's ruling). + +**Multi-region tinting.** If a single-channel mask is insufficient (an item +needs more than one independently-tintable region), follow the RGBA +channel-routed convention from `character-asset-organization.md` Section 11 +(T-1089) — R/G/B/A → four independent tints, cross-fading correctly under +bilinear filtering — rather than reinventing a greyscale-band scheme (that +approach was tried for clothing and rejected; see that doc's Section 5 +correction). This is the same mechanism, not a parallel one: environment +props reuse the clothing pipeline's multi-region shader family rather than +inventing a props-specific one. + +--- + +## 3. Texture naming (D-235 tokens) + +PBR surface maps for building-exterior and environment surfaces are named by +the ratified **ObjectTag vocabulary** (D-235 amendment, T-995, +`wiki/economics/object_tag_vocabulary.toml`), **not** the retired +`renderer/README.md` `__.png` scheme. That +scheme is direction-indexed for the retired 4-direction sprite render +(`renderer/README.md`'s now-legacy object-sprite mode) and does not apply to +PBR texture maps at all — there is no "direction" for a texture, only **map +type** (basecolor / normal / roughness). + +Format: `_.png` + +Map types: `basecolor`, `normal`, `roughness`. (`metallic` and `ao` may be +added if a material needs them; keep the same `_` +shape.) + +Examples, drawn from the D-235 ratified tags: +- `concrete_wall_basecolor.png`, `concrete_wall_normal.png`, `concrete_wall_roughness.png` +- `pitched_roof_normal.png` +- `stone_wall_basecolor.png` +- `generic_wall_basecolor.png` (fallback-terminal placeholder — D-235's + fallback hierarchy: every specific tag degrades to a `generic_*` parent + until the specific texture ships, then upgrades in place) + +The full ratified axis lists (wall/roof/facade/street + the four `generic_*` +fallback terminals) live in `wiki/economics/object_tag_vocabulary.toml` — +this doc does not duplicate that list; it names the file-naming convention +that keys off it. + +--- + +## 4. Multi-tile footprint metadata + +A table or couch spans multiple sim tiles regardless of whether it's +rendered as a sprite or a 3D model — this requirement survived the D-244 +pivot unchanged. It is **not** expressed as a filename convention (a +sprite-era assumption); it is a `manifest.json` field: + +```json +"footprint_tiles": [2, 1] +``` + +`[width, height]` in whole tiles (1 tile = 1m, D-243's voxel unit). Single +Sunday-tile props omit the field or set it to `[1, 1]`. See +`client/assets/models/manifest.json`'s `_fields` block for the authoritative +field definition alongside the rest of the per-asset schema. + +--- + +## 5. Deferred — door state handling (NOT authored here) + +**Do not port a state-frame suffix convention** (e.g. `door_open.glb` / +`door_closed.glb`). An earlier draft of this ticket (2026-06-16, since +superseded) proposed exactly that — baked open/closed GLB variants — which is +sprite-era thinking (baked state = baked frame) carried over from the retired +object-sprite model. + +For a 3D object, the door's open/closed/locked/sealed state (T-979/T-998's +`DoorSpec`: `Open` / `Closed` / `TemporalWindow` / `Locked` / `Sealed`) is a +**runtime transform/animation on one door `.glb`**, not separate baked +models. The actual mechanism — `AnimationPlayer` swing vs. procedural hinge +rotation vs. a door-model convention with a named "open" bone — is a +**Phase-5 rendering decision** (player control + in-world rendering, per the +cascade), not a Phase-4 asset-catalog concern. + +This doc records only the negative constraint above (no state-frame suffix +files). The positive mechanism is deferred to whichever Phase-5 ticket +handles door rendering — do not invent a runtime convention here. + +--- + +## 6. Deferred — Godot TileSet resource organization (OUT OF SCOPE) + +A `/.tres` convention is **out of scope for this doc and +this phase**, removed from the ticket that spawned this file. Reason: +`client/scripts/rendering/tile_renderer.gd`'s `TileSet` is an +explicitly-labeled placeholder ("programmatic TileSet with placeholder +colored rectangles," D-014), and the cascade rule (`CLAUDE.md`) states the +current in-world rendering code is "left as-is until Phase 5 — do not build +on it or rip it out before then." Authoring a `.tres` resource-organization +convention now would mean building on Phase-5-owned code from Phase 4. This +section is intentionally not written; a future Phase-5 ticket owns it. + +--- + +## Cross-References + +- [D-244](../../../governance/decisions/architecture.md#d-244-asset-rendering--3d-objects-in-world-2d-limited-to-textures--flat-artwork) — 3D objects in-world; 2D limited to textures + flat artwork. +- [D-241](../../../governance/decisions/process.md#d-241-spike-binary-artifacts-are-local-only--gitignored-never-tracked) — spike binaries local-only; promotion = repo-canonical. +- [D-235](../../../governance/decisions/architecture.md#d-235-building-exterior-visual-grammar-and-material-vocabulary) — ObjectTag vocabulary, ratified in `wiki/economics/object_tag_vocabulary.toml` (T-995). +- [D-243](../../../governance/decisions/architecture.md#d-243) — spatial scale ladder (1m voxel/tile unit for `footprint_tiles`). +- `docs/architecture/character-asset-organization.md` — Sections 3, 5, 11 (mask sidecar precedent, multi-region RGBA convention). +- `client/assets/models/manifest.json` — the schema this doc's naming/metadata conventions feed. +- `.claude/skills/glb-gen/SKILL.md` — the production pipeline that writes to `client/assets/models/`. diff --git a/docs/assets/visual/effects.md b/docs/assets/visual/effects.md new file mode 100644 index 000000000..3f2dee7e5 --- /dev/null +++ b/docs/assets/visual/effects.md @@ -0,0 +1,41 @@ +--- +title: "Effects — Visual Assets" +description: "Shader, particle, and overlay asset catalog" +type: design +status: active +--- + +# Effects — Visual Assets + +Shaders, particles, and overlays — the visual-effects layer distinct from +models/textures/artwork/icons. Includes both 3D-scene shaders (toon, +recolor-mask, outline) and 2D `CanvasLayer` overlays (fog, cognitive-delay +cues). + +## Generation Approach + +Hand-authored GDShader files, proven in the 3dpipeline and quaternius- +aesthetic spikes (`toon.gdshader`, `toon_masked.gdshader`, +`outline.gdshader`, `toon_garment.gdshader` — see +`docs/architecture/character-asset-organization.md` Sections 2 and 11 for +the shader family already in production use under +`client/assets/characters/shaders/`). New effects (particles, screen-space +overlays) are authored per-need; there is no generation pipeline analogous to +`/glb-gen`/`/sprite-gen` for this category. + +## Assets + +| ID | Filename | Status | Type | Notes | Sprint/Ticket | +|----|----------|--------|------|-------|---------------| + +This table intentionally excludes the character shader family already +tracked and documented in `character-asset-organization.md` (`toon.gdshader`, +`toon_masked.gdshader`, `outline.gdshader`, `toon_garment.gdshader`) — that +doc is their canonical home. This file catalogs effects/particles/overlays +that don't already have a home elsewhere; none exist yet (T-1050 initial +creation). + +## Cross-References + +- `docs/architecture/character-asset-organization.md` — character shader family (canonical home, not duplicated here) +- [D-244](../../../governance/decisions/architecture.md#d-244-asset-rendering--3d-objects-in-world-2d-limited-to-textures--flat-artwork) diff --git a/docs/assets/visual/icons.md b/docs/assets/visual/icons.md new file mode 100644 index 000000000..982831d88 --- /dev/null +++ b/docs/assets/visual/icons.md @@ -0,0 +1,50 @@ +--- +title: "Icons — Visual Assets" +description: "UI icon asset catalog — as-built inventory of client/assets/icons/" +type: design +status: active +--- + +# Icons — Visual Assets + +UI icons and status indicators. 2D, UI layer only — not part of the D-244 3D +in-world pivot (icons render on `CanvasLayer`, not in the 3D scene). + +## Generation Approach + +Hand-authored SVGs, tinted at runtime via `res://shaders/icon_tint.gdshader` +(see `client/ui/stance_indicator.gd` for the tint-shader integration +pattern). + +## Assets + +13 SVGs already exist in `client/assets/icons/` — this is the as-built +inventory, not a zero-start table. + +| ID | Filename | Status | Category | Notes | Sprint/Ticket | +|----|----------|--------|----------|-------|---------------| +| ICO-001 | `icon_stance_walk.svg` | final | Stance | Wired into `client/ui/stance_indicator.gd` (`StanceIndicator` icon map), tinted via `icon_tint.gdshader`. | — | +| ICO-002 | `icon_stance_sprint.svg` | final | Stance | Wired into `stance_indicator.gd`. | — | +| ICO-003 | `icon_stance_careful.svg` | final | Stance | Wired into `stance_indicator.gd`. | — | +| ICO-004 | `icon_stance_crouch.svg` | final | Stance | Wired into `stance_indicator.gd`. | — | +| ICO-005 | `icon_action_examine.svg` | placeholder | Action | SVG exists; not yet wired into a script/scene. | — | +| ICO-006 | `icon_action_follow.svg` | placeholder | Action | SVG exists; not yet wired into a script/scene. | — | +| ICO-007 | `icon_action_observe.svg` | placeholder | Action | SVG exists; not yet wired into a script/scene. | — | +| ICO-008 | `icon_action_talk.svg` | placeholder | Action | SVG exists; not yet wired into a script/scene. | — | +| ICO-009 | `icon_item_access_token.svg` | placeholder | Item | SVG exists; not yet wired into a script/scene. | — | +| ICO-010 | `icon_item_comm_log.svg` | placeholder | Item | SVG exists; not yet wired into a script/scene. | — | +| ICO-011 | `icon_item_manifest.svg` | placeholder | Item | SVG exists; not yet wired into a script/scene. | — | +| ICO-012 | `icon_status_health.svg` | placeholder | Status | SVG exists; not yet wired into a script/scene. | — | +| ICO-013 | `icon_status_perception.svg` | placeholder | Status | SVG exists; not yet wired into a script/scene. | — | + +`Status` here follows the shared vocab (`docs/assets/README.md`): +`final` = shipped and wired into a consuming script/scene; `placeholder` = +asset exists on disk but has no confirmed runtime consumer yet. If a +teammate wires one of the placeholder icons into a script, flip its row to +`final` and note the consumer, matching the `icon_stance_*` rows above. + +## Cross-References + +- `client/assets/icons/` — the SVG files this table catalogs +- `client/ui/stance_indicator.gd` — the one confirmed consumer (stance icons) +- `res://shaders/icon_tint.gdshader` — runtime tint shader diff --git a/docs/assets/visual/models.md b/docs/assets/visual/models.md new file mode 100644 index 000000000..03ef17a5e --- /dev/null +++ b/docs/assets/visual/models.md @@ -0,0 +1,48 @@ +--- +title: "Models — Visual Assets" +description: "3D object/furniture/prop asset catalog — status table for the Trellis glb-gen pipeline" +type: design +status: active +--- + +# Models — Visual Assets + +3D objects and furniture/props rendered directly in-world as `.glb` meshes +(D-244 — no per-object sprite layer). Produced via the Trellis image→3D +pipeline (`/glb-gen`), promoted per D-241 into `client/assets/models/`. + +## Generation Approach + +- **Concept image:** `/image-gen` produces a concept PNG (square, plain dark + background, single object centered, 3/4 front view — see + `.claude/skills/glb-gen/SKILL.md` "Input Requirements"). +- **Image → 3D:** Trellis (`tower-of-joy:11510`) converts the concept image + to a raw `.glb` (`/glb-gen`). +- **Post-process:** Blender normalizes scale, centers the mesh, generates the + recolor mask sidecar, and sets up materials for toon rendering + (`.claude/skills/glb-gen/scripts/postprocess_glb.py`). +- **Promotion:** the finished `.glb` (+ mask, if tintable) lands in + `client/assets/models/{furniture,props}/` and is registered in + `client/assets/models/manifest.json` — that registration + placement act + **is** the promotion (D-241); it does not stay a "promoted" spike artifact. + +Naming, mask-sidecar, and multi-tile footprint conventions: +[conventions.md](conventions.md). + +## Assets + +| ID | Filename | Status | Category | Footprint | Notes | Sprint/Ticket | +|----|----------|--------|----------|-----------|-------|---------------| + +No models have entered production yet — this table is intentionally empty at +initial creation (T-1050). Rows are added as assets are promoted into +`client/assets/models/manifest.json`; keep this table's `Status` column in +sync with the manifest's `status` field (shared vocab: planned / +in-progress / placeholder / final, `docs/assets/README.md`). + +## Cross-References + +- [conventions.md](conventions.md) — naming, mask sidecars, footprint metadata +- `client/assets/models/manifest.json` — the machine-readable per-asset registry +- `.claude/skills/glb-gen/SKILL.md` — production pipeline +- [D-244](../../../governance/decisions/architecture.md#d-244-asset-rendering--3d-objects-in-world-2d-limited-to-textures--flat-artwork), [D-241](../../../governance/decisions/process.md#d-241-spike-binary-artifacts-are-local-only--gitignored-never-tracked) diff --git a/docs/assets/visual/textures.md b/docs/assets/visual/textures.md new file mode 100644 index 000000000..3ea1a6e29 --- /dev/null +++ b/docs/assets/visual/textures.md @@ -0,0 +1,42 @@ +--- +title: "Textures — Visual Assets" +description: "PBR surface map asset catalog for 3D model and building-exterior surfaces" +type: design +status: active +--- + +# Textures — Visual Assets + +PBR surface maps (BaseColor / Normal / Roughness) applied to 3D model and +building-exterior surfaces. The only flattened 2D content besides flat +artwork (D-244) — a texture has no "direction," only map type. + +## Generation Approach + +- **Building-exterior surfaces:** named by the ratified ObjectTag vocabulary + (D-235 amendment, T-995, `wiki/economics/object_tag_vocabulary.toml`) — see + [conventions.md](conventions.md) §3 for the naming convention and the + fallback-hierarchy note (every specific tag degrades to a `generic_*` + parent until its specific texture ships). +- **Model surfaces:** Trellis bakes a texture atlas directly onto the mesh + during `/glb-gen` (no separate texture-authoring step for most + furniture/props) — see [models.md](models.md). This file tracks + **standalone** PBR maps: building-exterior materials and any surface asset + authored or generated independent of a specific model. + +## Assets + +| ID | Filename | Status | Map Type | ObjectTag | Notes | Sprint/Ticket | +|----|----------|--------|----------|-----------|-------|---------------| + +No textures have entered production yet — this table is intentionally empty +at initial creation (T-1050). Per D-235, the texture library itself is +Phase 5+/post-launch work (behind the fallback chain); this file exists now +so the catalog structure is in place ahead of that work landing. + +## Cross-References + +- [conventions.md](conventions.md) — D-235-keyed texture naming +- [models.md](models.md) — model-baked textures (Trellis atlas bakes) +- [D-235](../../../governance/decisions/architecture.md#d-235-building-exterior-visual-grammar-and-material-vocabulary) — ObjectTag vocabulary + fallback hierarchy +- `wiki/economics/object_tag_vocabulary.toml` — the ratified tag registry