From 2ca70d0228dad7bfcdab888461df00244f91d4cc Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Sat, 25 Jul 2026 20:36:47 +0200 Subject: [PATCH] =?UTF-8?q?docs(assets):=20PR=20#211=20review=20fixes=20?= =?UTF-8?q?=E2=80=94=20ratified=20glazing=20tokens,=20D-257,=20manifest=20?= =?UTF-8?q?skip=20contract?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review round (Hoshe + Tyre, both REQUEST_CHANGES) fully addressed: palette.md's glass carve-out re-keyed from retired never-shipped tokens (precision_glass/smart_facade) to the ratified glass_curtain_wall (wall) + industrial_glazing (facade); the toon/PBR treatment promoted from a docs-only ruling to D-257 (architecture, cross-refs D-235/D-244/D-043/ D-044/D-033) with palette.md §2 now citing it as authority; D-149 + D-257 added to decision_refs; manifest.json _comment gains the explicit underscore-prefix loader skip contract; master pipeline table Visual row Stub -> Active; conventions.md mask pointer Section 3 -> 5; pre-existing broken D-066 links in the mood-board transcript repaired (leave-cleaner). Co-Authored-By: Claude Fable 5 --- client/assets/models/manifest.json | 2 +- docs/assets/README.md | 2 +- docs/assets/visual/conventions.md | 2 +- docs/assets/visual/palette.md | 28 +++++++++++-------- .../workshop-outcomes.md | 4 +-- governance/README.md | 1 + governance/decisions/architecture.md | 14 ++++++++++ 7 files changed, 37 insertions(+), 16 deletions(-) diff --git a/client/assets/models/manifest.json b/client/assets/models/manifest.json index 5214e5788..c88b88f5a 100644 --- a/client/assets/models/manifest.json +++ b/client/assets/models/manifest.json @@ -1,5 +1,5 @@ { - "_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.", + "_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. CONTRACT: any top-level key prefixed with '_' (this key, '_fields', '_example_only_not_a_real_asset') is metadata/documentation, not an asset category — loaders MUST skip '_'-prefixed keys and must not iterate them as if they were real category/asset entries.", "_fields": { "name": "string — asset name, matches the manifest key and the .glb basename", "category": "string — 'furniture' | 'props' (matches the subdirectory)", diff --git a/docs/assets/README.md b/docs/assets/README.md index 81f6aeec1..eca4af308 100644 --- a/docs/assets/README.md +++ b/docs/assets/README.md @@ -14,7 +14,7 @@ Centralized tracking for all production assets across pipelines. Each pipeline h | Pipeline | Index | Palette | Status | |----------|-------|---------|--------| | [Audio](audio/README.md) | [audio/README.md](audio/README.md) | [audio/palette.md](audio/palette.md) | Active — Sprint 7 | -| [Visual](visual/README.md) | [visual/README.md](visual/README.md) | [visual/palette.md](visual/palette.md) | Stub | +| [Visual](visual/README.md) | [visual/README.md](visual/README.md) | [visual/palette.md](visual/palette.md) | Active — catalog + style bible instantiated (T-1050/T-1052) | | [Video](video/README.md) | [video/README.md](video/README.md) | [video/palette.md](video/palette.md) | Stub | ## Structure diff --git a/docs/assets/visual/conventions.md b/docs/assets/visual/conventions.md index 5e930bbdd..0e30b17ed 100644 --- a/docs/assets/visual/conventions.md +++ b/docs/assets/visual/conventions.md @@ -45,7 +45,7 @@ T-1050). ## 2. Mask sidecars Convention: `_mask.png`, single-channel (R-only greyscale), sitting -next to the GLB — per the character-asset convention (Section 3, +next to the GLB — per the character-asset convention (Section 5, `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 diff --git a/docs/assets/visual/palette.md b/docs/assets/visual/palette.md index 6bb9cb177..7454384d9 100644 --- a/docs/assets/visual/palette.md +++ b/docs/assets/visual/palette.md @@ -3,7 +3,7 @@ title: "Visual Palette" description: "Phase-4 visual style bible — camera, entity colours, environmental neutrality, D-235 material register, toon/PBR rendering treatment" type: design status: active -decision_refs: [D-019, D-033, D-045, D-148, D-217, D-232, D-235, D-244] +decision_refs: [D-019, D-033, D-045, D-148, D-149, D-217, D-232, D-235, D-244, D-257] author: "Araminta" updated: 2026-07-25 --- @@ -42,10 +42,13 @@ sentence is what this document is correcting. --- -## 2. Rendering Treatment — Toon vs. PBR (delegated ruling) +## 2. Rendering Treatment — Toon vs. PBR -**Ruling (Araminta, delegated by team lead this batch — surfaced to Jeroen for -veto in the batch report):** +**Authority: [D-257](../../../governance/decisions/architecture.md#d-257)** +(environment props share the character toon shading treatment; minimal-PBR +carve-out for glazing). This section is the practical guidance derived from +that record — the binding decision and its full rationale live in D-257, not +here. **Environment props and furniture share the character toon treatment.** One shader family, one look, across the whole in-world scene — with a single, @@ -70,10 +73,11 @@ the flat toon response. vocabulary's bulk. These are flat-lit like characters; PBR specular highlights on a stucco wall or a wooden table would read as wet/glossy and contradict the toon language players already learn from characters. -- **Exception — glass and polished/mirror metal:** `precision_glass`/ - `glass_curtain_wall` (facade), `smart_facade`, and any deliberately - reflective/polished metal prop (chrome fixture, mirror, glossy display - case) get a **separate minimal-PBR material**: `roughness` in the 0.05–0.2 +- **Exception — glass and polished/mirror metal:** the ratified D-235 glazing + tokens — `glass_curtain_wall` (wall axis) and `industrial_glazing` (facade + axis) — and any deliberately reflective/polished metal prop (chrome + fixture, mirror, glossy display case) get a **separate minimal-PBR + material**: `roughness` in the 0.05–0.2 range and non-zero `specular`/`metallic` as appropriate, layered so the toon shadow-band lighting model still governs the base surface response but a specular highlight and partial reflection are allowed through. This is not @@ -101,8 +105,8 @@ the flat toon response. grey panel, which actively misleads the player about sightlines (can I see through this?) in a game whose core mechanic is occlusion-based perception. Where "can the player see through/into this" is gameplay-load-bearing - (`glass_curtain_wall`, `precision_glass`, shop windows, interior partitions), - the material needs to look transparent/reflective enough to answer that + (`glass_curtain_wall`, `industrial_glazing`, shop windows, interior + partitions), the material needs to look transparent/reflective enough to answer that question at a glance. This is a narrow, named carve-out — it does not reopen "should props be PBR," it closes the one case where toon-only actively lies to the player. @@ -284,7 +288,9 @@ authored separately under T-1050). | D-033 | Entity color = relationship to player. Unchanged, still the primary information-bearing color system. | | D-045 | Environmental neutrality — strict zero shift. Governs how the D-235 material register (§3) may and may not respond to game state. | | D-148 | 30° low-angle gameplay `Camera3D`, supersedes D-019 for gameplay. | +| D-149 | 3D characters rendered live in scene, not pre-rendered sprites. Backing precedent for §1's camera reasoning (no more sprites to render "at the angle" during play) and for §2's shared-shader-family argument (characters and environment props come off the same live-3D pipeline). | | D-217 | Tile condition thresholds (prosperity_score bands) — the weathering-baseline mechanism referenced throughout §3. | | D-232 | Trait-template catalog — era reframed as maintenance/wear + past-vogue holdover, not a material-tech ladder. Backing rationale for retiring the Era 1/2/3 ladder in §5. | -| D-235 | Building exterior visual grammar + ratified ObjectTag vocabulary (`object_tag_vocabulary.toml`). §3 is this document's rendered-look layer on top of D-235's logical tokens. | +| D-235 | Building exterior visual grammar + ratified ObjectTag vocabulary (`object_tag_vocabulary.toml`). §3 is this document's rendered-look layer on top of D-235's logical tokens; §2's glazing carve-out names its ratified `glass_curtain_wall`/`industrial_glazing` tokens. | | D-244 | 3D objects in-world; 2D limited to textures + flat artwork. Establishes the toon-shader-family context for §2 and retires the sprite catalog framing this document used to have. | +| D-257 | Environment props share the character toon shading treatment; minimal-PBR carve-out for glazing. The binding authority for §2 — this document states the practical guidance, D-257 is the decision record. | diff --git a/docs/workshops/art-direction-mood-board/workshop-outcomes.md b/docs/workshops/art-direction-mood-board/workshop-outcomes.md index e183f2109..4ccbb7b88 100644 --- a/docs/workshops/art-direction-mood-board/workshop-outcomes.md +++ b/docs/workshops/art-direction-mood-board/workshop-outcomes.md @@ -90,7 +90,7 @@ Each participant's one-sentence answer to "What is this game's visual identity?" ### 1.3 World Composition — Tile-Based -**Dual-scale grid: 0.5m sim tiles, 1m visual tiles (2x retina factor, [D-066](../../decisions/architecture.md#d-066-dual-scale-grid--05m-simulation-1m-visual-2x-retina-factor)). Visual tiles are 64x64px.** +**Dual-scale grid: 0.5m sim tiles, 1m visual tiles (2x retina factor, [D-066](../../../governance/decisions/architecture.md#d-066-dual-scale-grid--05m-simulation-1m-visual-2x-retina-factor)). Visual tiles are 64x64px.** - Structural tiles (walls, floors, doors): 64x64px per visual tile (= 2x2 sim tiles), muted, minimal outlines, zone palette + era differentiation - Object tiles (furniture, equipment, containers): 64x64px per visual tile, medium outline (1px), Rimworld object detail as target. All world geometry is 2x2 sim tile minimum. @@ -119,7 +119,7 @@ Each participant's one-sentence answer to "What is this game's visual identity?" ### 1.5 Entity System -**24x32 pixel footprint within 64x64px visual tiles. Entities occupy 1x1 sim tiles (0.5m) but render across a 2x2 sim tile sprite footprint per [D-066](../../decisions/architecture.md#d-066-dual-scale-grid--05m-simulation-1m-visual-2x-retina-factor).** +**24x32 pixel footprint within 64x64px visual tiles. Entities occupy 1x1 sim tiles (0.5m) but render across a 2x2 sim tile sprite footprint per [D-066](../../../governance/decisions/architecture.md#d-066-dual-scale-grid--05m-simulation-1m-visual-2x-retina-factor).** - Entity smaller than visual tile = clear figure-ground relationship - D-033 color as primary information signal diff --git a/governance/README.md b/governance/README.md index 48c27a505..14e9e6ae1 100644 --- a/governance/README.md +++ b/governance/README.md @@ -322,6 +322,7 @@ line in place — keep the Q-record for the audit trail rather than deleting it. - [D-254: Standalone Atlas companion app — `make atlas`, dual-connection reader](decisions/architecture.md#d-254-standalone-atlas-companion-app--make-atlas-dual-connection-reader) — _architecture_ - [D-255: Body Map Viewer — stepped Atlas render architecture (supersedes the T-1143 continuous-ladder mechanism)](decisions/architecture.md#d-255-body-map-viewer--stepped-atlas-render-architecture-supersedes-the-t-1143-continuous-ladder-mechanism) — _architecture_ - [D-256: Canonical sampling convention — one absolute-metre derive core; the batch layer is a survey raster](decisions/architecture.md#d-256-canonical-sampling-convention--one-absolute-metre-derive-core-the-batch-layer-is-a-survey-raster) — _architecture_ +- [D-257: Environment props share the character toon shading treatment; minimal-PBR carve-out for glazing](decisions/architecture.md#d-257-environment-props-share-the-character-toon-shading-treatment-minimal-pbr-carve-out-for-glazing) — _architecture_ ## Open questions diff --git a/governance/decisions/architecture.md b/governance/decisions/architecture.md index d887d467b..a98cd2cf7 100644 --- a/governance/decisions/architecture.md +++ b/governance/decisions/architecture.md @@ -2313,4 +2313,18 @@ Technical foundation decisions that constrain implementation: engine, client-ser --- +### D-257: Environment props share the character toon shading treatment; minimal-PBR carve-out for glazing + +- **Date:** 2026-07-25 +- **Decision:** Environment props and furniture (the D-235 ObjectTag vocabulary's rendered assets — walls, roofs, facades, street furniture, and freestanding furniture/prop `.glb`s produced via `/glb-gen`) render with the **same toon shader family already used for characters** (`toon.gdshader` / `toon_masked.gdshader`, per `client/assets/characters/shaders/`), not a distinct PBR material response. The glb-gen postprocess convention of forcing `roughness=1.0`/`specular=0.0` ("for toon compatibility," `postprocess_glb.py::setup_materials()`) is confirmed as the correct default for this vocabulary's bulk. + - **Named carve-out — glass and polished/mirror metal.** The ratified glazing tokens — **`glass_curtain_wall`** (D-235 wall axis) and **`industrial_glazing`** (D-235 facade axis) — plus any deliberately reflective/polished-metal prop (chrome fixture, mirror, glossy display case), get a **minimal-PBR material** layered over the toon base: `roughness` in the 0.05–0.2 range with non-zero `specular`/`metallic`, not a full PBR stack (no environment-map reflections, no fresnel-driven rim lighting). The toon shadow-band lighting model still governs the base surface response; only a controlled specular/transparency term is added. + - This binds all future environment-shader and glb-gen-postprocess work; it is not a per-asset style suggestion. +- **Rationale:** Consistency compounds — a station built from one shader family reads as one coherent object; mixing a toon character against a PBR-lit room breaks the "one world" read the instant the player looks at their own hands next to a table (D-043/D-044 visual-hierarchy principles: entities and objects share one legible material language, distinguished by outline weight and saturation tier, not by rendering technology). The postprocess default already assumes this — `setup_materials()`'s "for toon compatibility" comment was written against the one Trellis pipeline that produces both character and environment `.glb`s, so sharing the treatment requires no new postprocess fork. The glazing carve-out is functionally forced, not a taste call: a flat-lit `roughness=1.0` glass pane reads as a frosted grey panel, which actively misleads the player about sightlines in a game whose core mechanic is occlusion-based perception (D-033's asymmetric-information model depends on the player correctly judging what they can and cannot see through). The carve-out is narrow and named — it closes only the case where toon-only actively lies to the player about transparency, and does not reopen "should props be PBR" generally. +- **Raised by:** Araminta (T-1052, delegated art-direction ruling), reviewed by Tyre (PR #211 — flagged the original carve-out's use of retired pre-amendment example tokens `precision_glass`/`smart_facade`, corrected here to the ratified D-235 tokens). +- **Implementation:** `docs/assets/visual/palette.md` §2 (practical guidance, cites this record as authority). Applies to all environment-prop material setup from Phase 4 asset production onward; no existing shipped assets to migrate as of this record's date. +- **Cross-reference:** [D-235](#d-235) (ratified ObjectTag vocabulary — `glass_curtain_wall`/`industrial_glazing` are its tokens, not this record's invention), [D-244](#d-244) (3D objects in-world; establishes the shared Trellis/glb-gen pipeline this record's postprocess argument depends on), [D-043/D-044](perception.md#d-043-art-direction--visual-style-functional-warmth) (visual-hierarchy/"functional warmth" rationale — entity/object/structure share one material language), [D-033](perception.md#d-033-entity-color--relationship-to-player) (the occlusion/asymmetric-information rationale for the glazing carve-out). +- **Dissent:** None. + +--- + *110 decisions (D-001 through D-256, excluding gaps). Last updated: 2026-07-24 (D-256 — canonical sampling convention: one absolute-metre derive core (`derive_at_metres` family), batch pseudo-grid re-scoped as `SurveyCellPos` survey raster (real newtype), thin-wrapper unification fixing the three-latitude inconsistency and the region-(0,0) climate collapse, exact-position feature judgments, step-canvas fencing; discharges the T-1174 blocker on D-255's T-1181 envelope).*