jpmschweitzer/settled-reach
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(assets): PR #211 review fixes — ratified glazing tokens, D-257, manifest skip contract

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
jpmschweitzer
2026-07-25 20:36:47 +02:00
co-authored by Claude Fable 5
parent 7d5a774fa5
commit 2ca70d0228
7 changed files with 37 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
client/assets/models/manifest.json
+1 -1
View File
@@ -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)",
docs/assets/README.md
+1 -1
View File
@@ -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
docs/assets/visual/conventions.md
+1 -1
View File
@@ -45,7 +45,7 @@ T-1050).
## 2. Mask sidecars
Convention: `<model>_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
docs/assets/visual/palette.md
+17 -11
View File
@@ -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. |
docs/workshops/art-direction-mood-board/workshop-outcomes.md
+2 -2
View File
@@ -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
governance/README.md
+1
View File
@@ -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
governance/decisions/architecture.md
+14
View File
@@ -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).*