Reorganize docs into category folders and drop the retired head-review page
Group the top-level docs into docs/project, docs/design, docs/assets and docs/process, each with its own README index. Delete the superseded docs/screens/head-review page and sheets. Rewrite every markdown link, absolute docs path and tool/test reference to the new locations, fix the pre-existing broken anchors and remove the dead Joke Shop photo-board link. check_docs OK, Python tooling 167/167.
This commit is contained in:
zwitschi committed
1 parent
045ed2a58f
commit
2ba40f3578
57 files changed
+406
-414
No files matched your search
@@ -24,7 +24,7 @@ The project contract and measured gates override any generic Blender advice.
|
||||
Blender MCP is optional interactive tooling; the headless flatpak CLI remains
|
||||
authoritative and CI never needs Blender or MCP. The `blender-skills` pack is
|
||||
optional, local guidance only, and gitignored. Setup and safety are in
|
||||
`docs/asset-tooling.md#optional-interactive-blender-mcp`.
|
||||
`docs/assets/asset-tooling.md#optional-interactive-blender-mcp`.
|
||||
|
||||
## Read first
|
||||
|
||||
@@ -33,11 +33,11 @@ skill alone:
|
||||
|
||||
1. `AGENTS.md` — required workflow and verification.
|
||||
2. `TODO.md` and `MEMORY.md` — current track, claimed tasks, known gotchas.
|
||||
3. `docs/blender-assets.md` — library contract and command reference.
|
||||
4. `docs/asset-tooling.md` — exact rebuild/bake/capture commands.
|
||||
5. `docs/npc-model-sourcing.md` and `docs/3d-model-review.md` — accepted limits,
|
||||
3. `docs/assets/blender-assets.md` — library contract and command reference.
|
||||
4. `docs/assets/asset-tooling.md` — exact rebuild/bake/capture commands.
|
||||
5. `docs/assets/npc-model-sourcing.md` and `docs/assets/3d-model-review.md` — accepted limits,
|
||||
scorecards and known blockers.
|
||||
6. `docs/known-limitations.md` — limits that must not be silently “fixed” into
|
||||
6. `docs/design/known-limitations.md` — limits that must not be silently “fixed” into
|
||||
contract changes.
|
||||
|
||||
The contract lives in code and docs, not in this skill. If they disagree, stop
|
||||
@@ -114,7 +114,7 @@ only the specialists the task needs:
|
||||
- budget/LOD/collision: `asset-optimization`, `lod-pipeline`, `collision-proxy`
|
||||
- final review: `qa-review`
|
||||
|
||||
If MCP is available, use it for interactive part exploration only; mirror the result into a scripted change or local `.blend`, then re-export and run the CLI audit/fit gates. Never make the build, CI, tests or runtime depend on MCP. Setup: `docs/asset-tooling.md#optional-interactive-blender-mcp`.
|
||||
If MCP is available, use it for interactive part exploration only; mirror the result into a scripted change or local `.blend`, then re-export and run the CLI audit/fit gates. Never make the build, CI, tests or runtime depend on MCP. Setup: `docs/assets/asset-tooling.md#optional-interactive-blender-mcp`.
|
||||
|
||||
### 4. Build or bake
|
||||
|
||||
@@ -185,7 +185,7 @@ gates run, and any accepted limit.
|
||||
- **Empty or stale captures** — close modals/pause, check the capture script's
|
||||
settle frames, and remove stale output directories before re-running.
|
||||
- **Pose harness mismatch** — the current `capture_npc_pose.gd` is blocked per
|
||||
`docs/3d-model-review.md`; do not use its frames as pose evidence until the
|
||||
`docs/assets/3d-model-review.md`; do not use its frames as pose evidence until the
|
||||
recipe is fixed.
|
||||
- **Asset test fails after import** — re-run audit/fit first, then import; if the
|
||||
manifest or AO path changed, rebuild the affected asset rather than editing
|
||||
@@ -197,7 +197,7 @@ gates run, and any accepted limit.
|
||||
|
||||
- [`references/asset-contract.md`](references/asset-contract.md) — full contract,
|
||||
inventory, file locations and provenance rules.
|
||||
- `docs/asset-tooling.md#optional-interactive-blender-mcp` — optional MCP installation, connection, safety and
|
||||
- `docs/assets/asset-tooling.md#optional-interactive-blender-mcp` — optional MCP installation, connection, safety and
|
||||
part-workflow instructions.
|
||||
- [`references/verification.md`](references/verification.md) — command matrix,
|
||||
capture gates, expected results and acceptance criteria.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Asset Contract Reference
|
||||
|
||||
This is a working summary. The authoritative sources remain
|
||||
`docs/blender-assets.md`, `docs/asset-tooling.md`, ADR-0013, the tests in
|
||||
`docs/assets/blender-assets.md`, `docs/assets/asset-tooling.md`, ADR-0013, the tests in
|
||||
`src/test/tests/` and the constants in `tools/blender_assets.py` /
|
||||
`tools/npc_pipeline.py`.
|
||||
|
||||
|
||||
@@ -113,8 +113,8 @@ For each changed variant, inspect at least:
|
||||
- Day and night/LATE final-context frames.
|
||||
- Front, three-quarter and profile for a shape change.
|
||||
|
||||
Accepted stylized limits are in `docs/3d-model-review.md` and
|
||||
`docs/known-limitations.md`. Do not turn an accepted limit into an unreviewed
|
||||
Accepted stylized limits are in `docs/assets/3d-model-review.md` and
|
||||
`docs/design/known-limitations.md`. Do not turn an accepted limit into an unreviewed
|
||||
contract change.
|
||||
|
||||
## Final diff review
|
||||
|
||||
@@ -19,9 +19,9 @@ publishing, and the full visual/QA gate. For a Blender/asset rebuild, use
|
||||
|
||||
1. `AGENTS.md` — release procedure and verification rules.
|
||||
2. `TODO.md` — current milestone, blockers and release exit criteria.
|
||||
3. `docs/RELEASING.md` — build/publish commands, artifact list, macOS policy.
|
||||
4. `docs/release-qa.md` — manual QA matrix and balance protocol.
|
||||
5. `docs/development-status.md`, `CHANGELOG.md`, `README.md` — current claims.
|
||||
3. `docs/process/RELEASING.md` — build/publish commands, artifact list, macOS policy.
|
||||
4. `docs/process/release-qa.md` — manual QA matrix and balance protocol.
|
||||
5. `docs/project/development-status.md`, `CHANGELOG.md`, `README.md` — current claims.
|
||||
6. `MEMORY.md` — release gotchas, especially the clean-worktree rule.
|
||||
|
||||
A release is not just a tag. It includes a version bump, changelog, clean build,
|
||||
@@ -58,8 +58,8 @@ Update:
|
||||
|
||||
1. `project.godot` `config/version`.
|
||||
2. `CHANGELOG.md` with a dated entry.
|
||||
3. `README.md`, `PLAN.md`, `docs/architecture.md`,
|
||||
`docs/development-status.md`, `TODO.md`/`DONE.md` and `MEMORY.md` as needed.
|
||||
3. `README.md`, `PLAN.md`, `docs/project/architecture.md`,
|
||||
`docs/project/development-status.md`, `TODO.md`/`DONE.md` and `MEMORY.md` as needed.
|
||||
|
||||
For a release candidate, use a prerelease version only if the project policy
|
||||
allows it and never present it as the final release.
|
||||
@@ -213,7 +213,7 @@ The default `RETAIN_RELEASES=0` never prunes.
|
||||
|
||||
### 7. Post-release record
|
||||
|
||||
Update `README.md`, `docs/development-status.md`, `MEMORY.md`, `CHANGELOG.md`,
|
||||
Update `README.md`, `docs/project/development-status.md`, `MEMORY.md`, `CHANGELOG.md`,
|
||||
`TODO.md`/`DONE.md` and the release page with the built/CI result. Commit the
|
||||
release record and push. Record any skipped check and the reason; never leave a
|
||||
tag with unreported missing verification.
|
||||
|
||||
@@ -93,7 +93,7 @@ python3 tools/screen_designs.py judge --model auto
|
||||
```
|
||||
|
||||
Record model, confidence/verdict summary, `diff` count and any manual review.
|
||||
`docs/ui-copy.md#screen-design-judge-report` is the durable record.
|
||||
`docs/design/ui-copy.md#screen-design-judge-report` is the durable record.
|
||||
|
||||
## 6. Realism judge (when visual assets/lighting changed)
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Release Runbook
|
||||
|
||||
Authoritative source: `AGENTS.md` (Release Procedure), `docs/RELEASING.md`.
|
||||
Authoritative source: `AGENTS.md` (Release Procedure), `docs/process/RELEASING.md`.
|
||||
This runbook is the operational checklist; if it conflicts with those, they win.
|
||||
|
||||
## 0. Decide the release
|
||||
@@ -29,8 +29,8 @@ Files to update:
|
||||
| `project.godot` | `config/version="X.Y.Z"` |
|
||||
| `CHANGELOG.md` | dated `## [X.Y.Z] — YYYY-MM-DD` entry |
|
||||
| `README.md` | latest/current version and summary |
|
||||
| `PLAN.md` / `docs/architecture.md` | current version reference |
|
||||
| `docs/development-status.md` | shipped capability/release result |
|
||||
| `PLAN.md` / `docs/project/architecture.md` | current version reference |
|
||||
| `docs/project/development-status.md` | shipped capability/release result |
|
||||
| `TODO.md` / `DONE.md` | close/move milestone when complete |
|
||||
| `MEMORY.md` | release state and gotchas |
|
||||
|
||||
|
||||
@@ -15,15 +15,15 @@ The project should be developed in small, reviewable steps. Agents must keep pla
|
||||
- `README.md` — Root-level documentation for the project. It should explain what the game is, how to work on it, how to run it, and where to find project information.
|
||||
- `AGENTS.md` — This collaboration and agent workflow guide.
|
||||
- `CHANGELOG.md` — The version history of user-facing changes. Keep an entry for each patch, minor, and major version.
|
||||
- `docs/development-status.md` — The implemented-features list and what is not yet implemented. Update it whenever a feature lands, is renamed, or is removed.
|
||||
- `docs/architecture.md` — The arc42-style architecture documentation (goals, constraints, building blocks, runtime views, decisions, risks).
|
||||
- `docs/gameplay.md` — Gameplay systems, tutorial, venues and the escalation model.
|
||||
- `docs/venues.md` — Real-site evidence, game mapping and venue simplifications.
|
||||
- `docs/asset-tooling.md` — Asset pipelines, model tools, optional Blender MCP and screenshot gates.
|
||||
- `docs/blender-assets.md` — Blender library operation and asset roles.
|
||||
- `docs/npc-model-sourcing.md` — Character-source evaluation, licence rules and the character-development plan.
|
||||
- `docs/getting-started.md` — Setup, run/test commands, and the controls table.
|
||||
- `docs/release-qa.md` — The manual smoke checklist and balance-acceptance protocol.
|
||||
- `docs/project/development-status.md` — The implemented-features list and what is not yet implemented. Update it whenever a feature lands, is renamed, or is removed.
|
||||
- `docs/project/architecture.md` — The arc42-style architecture documentation (goals, constraints, building blocks, runtime views, decisions, risks).
|
||||
- `docs/design/gameplay.md` — Gameplay systems, tutorial, venues and the escalation model.
|
||||
- `docs/design/venues.md` — Real-site evidence, game mapping and venue simplifications.
|
||||
- `docs/assets/asset-tooling.md` — Asset pipelines, model tools, optional Blender MCP and screenshot gates.
|
||||
- `docs/assets/blender-assets.md` — Blender library operation and asset roles.
|
||||
- `docs/assets/npc-model-sourcing.md` — Character-source evaluation, licence rules and the character-development plan.
|
||||
- `docs/process/getting-started.md` — Setup, run/test commands, and the controls table.
|
||||
- `docs/process/release-qa.md` — The manual smoke checklist and balance-acceptance protocol.
|
||||
- `docs/adr/` — Architecture Decision Records.
|
||||
|
||||
## Priority and Versioning
|
||||
@@ -102,7 +102,7 @@ specialists the task needs:
|
||||
the change is explicitly planned and the contract, tests and docs are updated together.
|
||||
2. **Blender MCP is optional interactive tooling.** The headless flatpak scripts
|
||||
(`tools/blender_assets.py`, `tools/npc_pipeline.py`) remain authoritative. MCP may be used
|
||||
for local part exploration; setup and safety are in [`docs/asset-tooling.md#optional-interactive-blender-mcp`](docs/asset-tooling.md#optional-interactive-blender-mcp).
|
||||
for local part exploration; setup and safety are in [`docs/assets/asset-tooling.md#optional-interactive-blender-mcp`](docs/assets/asset-tooling.md#optional-interactive-blender-mcp).
|
||||
Never add an MCP dependency to the build, CI, tests or runtime, and always re-run the CLI
|
||||
audit/fit gates on anything MCP touched.
|
||||
3. **CI stays offline and skill-free.** Skills are local guidance only; every gate must still
|
||||
@@ -110,7 +110,7 @@ specialists the task needs:
|
||||
4. **No new asset source without the licence gate.** Skills may suggest reference packs or
|
||||
generated meshes; ADR-0017 (the CC0 Quaternius NPC base) supersedes the generator-first
|
||||
decision in ADR-0015, and the CC0/CC-BY rule in ADR-0015 (attribution in `CREDITS.md`) plus
|
||||
the provenance rules in `docs/npc-model-sourcing.md` still apply to any new source.
|
||||
the provenance rules in `docs/assets/npc-model-sourcing.md` still apply to any new source.
|
||||
5. **Evidence, not vibes.** After a skill-informed change, run `blender_assets.py inspect`,
|
||||
`audit` and `fit` plus the relevant capture/smoke gates, and say in the handoff which
|
||||
skills informed the change and what the measurements were.
|
||||
@@ -196,7 +196,7 @@ first, then versioned milestones in version order, then future/deferred work.
|
||||
level-3 section to `DONE.md`.
|
||||
2. **Level-2 milestone/theme:** it is complete only when its direct checkboxes and **all** of its
|
||||
level-3 workstreams are complete. Verify the whole milestone, record its capabilities in
|
||||
`docs/development-status.md` when it represents shipped functionality, and write the matching
|
||||
`docs/project/development-status.md` when it represents shipped functionality, and write the matching
|
||||
`CHANGELOG.md` entry.
|
||||
3. Move the **entire level-2 section**, including all level-3 headings and checklists, to
|
||||
`DONE.md`. Remove it from `TODO.md` and add a completion date/note.
|
||||
@@ -207,7 +207,7 @@ first, then versioned milestones in version order, then future/deferred work.
|
||||
complete, or split the unfinished work into a new smaller level-2 milestone first.
|
||||
|
||||
When a completed milestone represents shipped functionality, also record the new capability in
|
||||
`docs/development-status.md` so the implemented-features list stays accurate, and write a matching
|
||||
`docs/project/development-status.md` so the implemented-features list stays accurate, and write a matching
|
||||
entry in `CHANGELOG.md` (see "Maintain `CHANGELOG.md`" below).
|
||||
|
||||
### 4. Maintain `MEMORY.md`
|
||||
@@ -217,7 +217,7 @@ Use `MEMORY.md` for information that should persist between sessions but does no
|
||||
Record items such as:
|
||||
|
||||
- Important design and architecture decisions
|
||||
- Notable implementation state and gotchas (the canonical implemented-features list lives in `docs/development-status.md`, not here)
|
||||
- Notable implementation state and gotchas (the canonical implemented-features list lives in `docs/project/development-status.md`, not here)
|
||||
- Known bugs and workarounds
|
||||
- Commands needed to run, test, or build the project
|
||||
- Decisions that future agents should not revisit unnecessarily
|
||||
@@ -267,7 +267,7 @@ The root-level `README.md` is the project’s public-facing technical and projec
|
||||
- Links to `PLAN.md`, `TODO.md`, `DONE.md`, `MEMORY.md`, and this file where appropriate
|
||||
- Known limitations and contribution guidance
|
||||
|
||||
Update `README.md` whenever setup instructions, commands, project structure, or user-facing behavior changes. The README is intentionally concise and links to the `docs/` files; keep `docs/development-status.md` (and the other docs it links to) synchronized with the implementation rather than pasting detail back into the README.
|
||||
Update `README.md` whenever setup instructions, commands, project structure, or user-facing behavior changes. The README is intentionally concise and links to the `docs/` files; keep `docs/project/development-status.md` (and the other docs it links to) synchronized with the implementation rather than pasting detail back into the README.
|
||||
|
||||
### 7. Maintain `CHANGELOG.md`
|
||||
|
||||
@@ -297,7 +297,7 @@ For each task:
|
||||
2. Inspect the relevant files and dependencies.
|
||||
3. Make the smallest coherent change that completes the task.
|
||||
4. Run the relevant tests, checks, or manual verification.
|
||||
5. Update documentation if the change creates lasting context: add features to `docs/development-status.md`, adjust the README links or other `docs/` files as needed, and record decisions/gotchas in `MEMORY.md`.
|
||||
5. Update documentation if the change creates lasting context: add features to `docs/project/development-status.md`, adjust the README links or other `docs/` files as needed, and record decisions/gotchas in `MEMORY.md`.
|
||||
6. Mark the task complete.
|
||||
7. Keep completed level-3 workstreams in place until the parent milestone is complete; then move the entire level-2 milestone to `DONE.md` after recording its `CHANGELOG.md` entry.
|
||||
8. Commit each coherent, verified change as it is completed. Do not wait until a whole
|
||||
|
||||
+4
-4
@@ -16,7 +16,7 @@ been cleared for public distribution.
|
||||
## 3D characters, gear and props
|
||||
|
||||
The local MakeHuman head prototype uses the CC0 MakeHuman/MPFB base mesh
|
||||
(see [`docs/makehuman-head-review.md`](docs/makehuman-head-review.md)); it is a
|
||||
(see [`docs/assets/makehuman-head-review.md`](docs/assets/makehuman-head-review.md)); it is a
|
||||
development prototype, not a shipped character.
|
||||
|
||||
The character, gear and prop library is generated by project-owned scripts
|
||||
@@ -53,7 +53,7 @@ CC0 1.0). It is cut, retopologised and re-weighted by project scripts; the expor
|
||||
character GLBs remain project assets. The development source files were removed
|
||||
from `tmp/` after the 2026-11-05 pivot to Quaternius. The head is retained as a
|
||||
tested fallback, not the active NPC base. See ADR-0017 and
|
||||
`docs/npc-model-sourcing.md`.
|
||||
`docs/assets/npc-model-sourcing.md`.
|
||||
|
||||
### Quaternius NPC base source
|
||||
|
||||
@@ -61,7 +61,7 @@ The active NPC base migration uses **Quaternius Ultimate Modular Characters** an
|
||||
**Ultimate Modular Women** (CC0 1.0, <https://quaternius.com/>). The three
|
||||
researched GLBs are development inputs and are not shipped directly; the baked,
|
||||
retargeted character GLBs are project assets. See ADR-0017 and
|
||||
`docs/npc-model-sourcing.md` for the decision, source hashes and rollout status.
|
||||
`docs/assets/npc-model-sourcing.md` for the decision, source hashes and rollout status.
|
||||
|
||||
The venue geometry is authored procedurally in `src/game/world_builder.gd` as a
|
||||
stylized reconstruction. The Joke Shop is a fictional stand-in for the real
|
||||
@@ -118,7 +118,7 @@ reference more directly, its attribution and licence must be added here.
|
||||
|
||||
All runtime audio is procedural (crowd bed, radio crackle and interface cues).
|
||||
There are no external audio files, so there is no separate music/SFX licence to
|
||||
clear. See `docs/accessibility.md` for caption and volume behaviour.
|
||||
clear. See `docs/design/accessibility.md` for caption and volume behaviour.
|
||||
|
||||
## Third-party names
|
||||
|
||||
|
||||
@@ -137,7 +137,7 @@ Completed task sections moved from `TODO.md`. Sections are moved only when every
|
||||
|
||||
- [x] Commit `export_presets.cfg` with Linux, Windows, and macOS desktop presets.
|
||||
- [x] Add `tools/build_releases.sh` for headless release exports.
|
||||
- [x] Add `docs/RELEASING.md` with template installation, build, and Gitea release steps.
|
||||
- [x] Add `docs/process/RELEASING.md` with template installation, build, and Gitea release steps.
|
||||
- [x] Add a prominent **Downloads** section at the top of `README.md` linking to the release page.
|
||||
- [x] Add `tools/publish_release.sh` (Gitea API release + asset upload, requires `GITEA_TOKEN`).
|
||||
|
||||
@@ -149,7 +149,7 @@ Completed task sections moved from `TODO.md`. Sections are moved only when every
|
||||
- [x] Tag builds automatically publish the Gitea release via `tools/publish_release.sh` using
|
||||
the `GITEA_TOKEN` secret.
|
||||
- [x] Remove the old `.github/workflows/ci.yml` to avoid double runs on hosts scanning both paths.
|
||||
- [x] Document the CI flow in `docs/RELEASING.md`.
|
||||
- [x] Document the CI flow in `docs/process/RELEASING.md`.
|
||||
|
||||
## Gameplay — Venue selection
|
||||
|
||||
@@ -249,7 +249,7 @@ Completed task sections moved from `TODO.md`. Sections are moved only when every
|
||||
service; ~2 min of retry timeouts per run; Godot import is fast without it).
|
||||
- [x] Add `GODOT_SILENCE_ROOT_WARNING=1` to both jobs.
|
||||
- [x] Confirmed in run 1090: zero `CacheService` lines, 54/54 tests pass, job succeeds.
|
||||
- [x] Document the cache situation and re-enable path in `docs/RELEASING.md`.
|
||||
- [x] Document the cache situation and re-enable path in `docs/process/RELEASING.md`.
|
||||
- [x] Ignore runner logs in `.gitignore` (`.gitea/logs/`).
|
||||
|
||||
## Gameplay — Venue door-staff dialogue
|
||||
@@ -660,7 +660,7 @@ produces a 63 MB static bundle and it serves locally with HTTP 200s for html/was
|
||||
- [x] Publish the web zip with the desktop artifacts (`tools/publish_release.sh`).
|
||||
- [x] Cover the preset, the non-threaded choice, and the release wiring in
|
||||
`src/test/tests/test_web_export.gd`.
|
||||
- [x] Document the artifact in `docs/RELEASING.md`, the README gallery/status, and `PLAN.md`.
|
||||
- [x] Document the artifact in `docs/process/RELEASING.md`, the README gallery/status, and `PLAN.md`.
|
||||
|
||||
## Prop Texture Atlas
|
||||
|
||||
@@ -909,7 +909,7 @@ Goal: replace the outdated flat skyline backdrop (`assets/textures/skyline.png`,
|
||||
with dot windows) and the flat-looking surface tiles with AI-generated, more realistic
|
||||
backgrounds and textures. Add a larger set of example 3D scene images as art direction, and
|
||||
measure the in-game result against that target with the screenshot tools. Plan:
|
||||
[`PLAN.md` → Visual Quality Direction → Realism pass](PLAN.md#realism-pass).
|
||||
[`PLAN.md` → Visual Quality Direction → Realism pass](PLAN.md#presentation-and-controls).
|
||||
|
||||
**Rule for every step: never overwrite an existing image.** New outputs get new paths. When a
|
||||
path is taken, the tools pick the next free `-vN` suffix. Raw AI output stays on disk under
|
||||
@@ -1047,7 +1047,7 @@ reports to `docs/screens/realism/<run>/`.
|
||||
`docs/screens/realism/2026-11-01-adopt/` (3 judge repeats per shot) gives a like-for-like
|
||||
improvement on every sub-score: overall 0.8→1.0, lighting 0.8→1.0, materials 0.8→1.0,
|
||||
texture 0.8→1.0, backdrop 0.6→1.6, and the Pillow metric gap 0.444→0.348.
|
||||
- [x] Update `README.md` (tool usage + gallery), `MEMORY.md` and `docs/architecture.md`.
|
||||
- [x] Update `README.md` (tool usage + gallery), `MEMORY.md` and `docs/project/architecture.md`.
|
||||
|
||||
## Realism Follow-ups — Lighting, Flashlight, NPC Detail
|
||||
|
||||
@@ -1087,7 +1087,7 @@ Completed 2026-11-01. The follow-ups left over after the texture/skyline adoptio
|
||||
bridge and tip, ears with lobes, and split upper/lower lips. Hands have four fingers plus a
|
||||
thumb, and every sleeve ends in a cuff ring.
|
||||
- [x] Raised `CHAR_MAX_VERTS` 4000 → **5000** (documented in the code and
|
||||
`docs/blender-assets.md`) after measuring 16 avatars at ~6.9 ms of a 50 ms frame on a single
|
||||
`docs/assets/blender-assets.md`) after measuring 16 avatars at ~6.9 ms of a 50 ms frame on a single
|
||||
skinned mesh, so `npc_coat` fits at 4807 vertices; the character range is now 3,974–5,026
|
||||
triangles and 3,744–4,807 vertices. Body decimation 0.36 → 0.26.
|
||||
- [x] Rebuilt all 8 variants and re-baked their AO maps (`assets/models/blender/npc/*_ao.png`),
|
||||
@@ -1114,14 +1114,14 @@ Completed 2026-11-01.
|
||||
- [x] Decide the canonical runtime image root (`assets/images/` for UI/scene art): recorded in
|
||||
`MEMORY.md` and [ADR-0014](docs/adr/0014-runtime-image-root.md).
|
||||
- [x] Move the reference mockups from `docs/screens/designs/` into the runtime root (keep `docs/screens/designs/` as a docs-only copy or replace it with the new path).
|
||||
- [x] Document one convention for game vs reference vs development images across `assets/textures/`, `assets/images/`, `assets/models/generated/`, `docs/screenshots/`, and `docs/screens/designs/` (in `docs/architecture.md`, ADR-0014).
|
||||
- [x] Document one convention for game vs reference vs development images across `assets/textures/`, `assets/images/`, `assets/models/generated/`, `docs/screenshots/`, and `docs/screens/designs/` (in `docs/project/architecture.md`, ADR-0014).
|
||||
- [x] Re-run `godot --headless --path . --import` to regenerate `.import` sidecars after any move.
|
||||
- [x] Confirm `.gitignore` still excludes development-only outputs (concepts, Blender sources, raw AI fabrics) under the new layout; Blender `.blend` sources are now untracked and ignored.
|
||||
|
||||
### Documentation path updates
|
||||
|
||||
- [x] Update `README.md` paths (screen-designs section, confirmed-assets links, the `assets/images/scenes` resize example).
|
||||
- [x] Update `docs/architecture.md`, `PLAN.md`, and ADR references: docs/screens/designs/ is now explicitly the reference-only snapshot; runtime art lives in assets/images/ (ADR-0014).
|
||||
- [x] Update `docs/project/architecture.md`, `PLAN.md`, and ADR references: docs/screens/designs/ is now explicitly the reference-only snapshot; runtime art lives in assets/images/ (ADR-0014).
|
||||
- [x] Update `tools/screen_designs.py` docstrings and mark the old paths in `DONE.md` as historical.
|
||||
|
||||
### Code path updates
|
||||
@@ -1188,7 +1188,7 @@ architecture's version, runtime-art loader, asset/tooling blocks, Gitea CI/build
|
||||
Web deployment and release artifact list were brought up to date. `MEMORY.md` was cleaned of
|
||||
obsolete uncommitted/active-pass claims and now points at the current follow-ups.
|
||||
|
||||
- [x] Re-check `PLAN.md`/`MEMORY.md` against the current build, update `README.md` and `docs/architecture.md`, and compact the historical PLAN sections.
|
||||
- [x] Re-check `PLAN.md`/`MEMORY.md` against the current build, update `README.md` and `docs/project/architecture.md`, and compact the historical PLAN sections.
|
||||
|
||||
## NPC gear fit (v0.6.1)
|
||||
|
||||
@@ -1197,7 +1197,7 @@ Completed 2026-11-01. Eyes, bag and helmet now fit the measured body silhouette;
|
||||
The 2026-11-01 detail pass fixed the bodies but not the props worn on them. In the portrait
|
||||
capture (`--stages=day,portrait`, see the report in `docs/screens/realism/2026-11-01-npc/`) the
|
||||
sunglasses span the whole upper face and the shoulder bag cuts through `npc_coat`'s skirt. Blender sources for gear
|
||||
live in `tools/blender_assets.py` (`_build_gear()`), the contract in `docs/blender-assets.md`
|
||||
live in `tools/blender_assets.py` (`_build_gear()`), the contract in `docs/assets/blender-assets.md`
|
||||
(gear budget 1500 tris, `GEAR_ATTACH` points in `NpcAvatar`).
|
||||
|
||||
- [x] Measure the fit in Blender, not by eye: `python3 tools/blender_assets.py fit` prints each
|
||||
@@ -1270,7 +1270,7 @@ have no stage in the committed `docs/screenshots/` gallery, only in `capture_rea
|
||||
`src/test/capture_screenshots.gd` (`12-joke-shop.png`, `13-studio-arrival.png`) reuse the
|
||||
existing `joke_shop_queue` / `studio_arrival` designs. `check_screenshots.sh` is **13 good /
|
||||
0 bad**; the new screenshots are 18.2 / 32.6 MAE against their references.
|
||||
- [-] Update `docs/architecture.md` (venue geometry), `README.md` (gallery) and the screenshot
|
||||
- [-] Update `docs/project/architecture.md` (venue geometry), `README.md` (gallery) and the screenshot
|
||||
table when the stages land.
|
||||
|
||||
## Forward+ desktop preset and a volumetric flashlight (v0.7.1)
|
||||
@@ -1296,7 +1296,7 @@ path.
|
||||
dirs) and record the diff in `docs/screens/realism/2026-11-01-forward-plus/`: entrance
|
||||
metric gap 1.568 → 1.187, two-shot mean 0.907 → 0.723. Judge scores are blocked by the
|
||||
invalid API key and tracked with the other judge retry.
|
||||
- [x] Add the preset to `tools/build_releases.sh` and `docs/RELEASING.md` as an optional
|
||||
- [x] Add the preset to `tools/build_releases.sh` and `docs/process/RELEASING.md` as an optional
|
||||
"desktop HQ" artifact, and note the runtime requirement (Vulkan driver) in `README.md`.
|
||||
`gig-line-desktop-hq-<version>.zip` packages the Linux/Windows binaries, override.cfg and
|
||||
README; `publish_release.sh` uploads it when present.
|
||||
@@ -1327,7 +1327,7 @@ back when a provider rejects a request.
|
||||
- [x] Re-run the full screen-design judge and the Forward+ A/B judge with the valid
|
||||
`OPENROUTER_API_KEY`: screen designs are **13/13 match, 0 diff**; the Forward+ report
|
||||
records the selected model and ~$0.006 spend.
|
||||
- [x] Update `docs/asset-tooling.md`, `MEMORY.md`, `README.md` and `CHANGELOG.md`; the
|
||||
- [x] Update `docs/assets/asset-tooling.md`, `MEMORY.md`, `README.md` and `CHANGELOG.md`; the
|
||||
public catalogue picks the cheapest image+JSON model (`z-ai/glm-5.3-flash` at run time).
|
||||
|
||||
## Milestone 0.8.0 — First hour and content depth
|
||||
@@ -1343,7 +1343,7 @@ venues, and see enough authored variety that a second shift does not feel like a
|
||||
- [x] Write the tutorial beat sheet: menu → movement/look → focus and target cycling → action
|
||||
wheel → access inspection → polite direction → formal warning/body camera → radio →
|
||||
shift review. Eight beats and a safe compliant visitor are specified in
|
||||
[`docs/gameplay.md#first-shift-tutorial`](docs/gameplay.md#first-shift-tutorial).
|
||||
[`docs/design/gameplay.md#first-shift-tutorial`](docs/design/gameplay.md#first-shift-tutorial).
|
||||
- [x] Add a tutorial state machine independent of the normal shift FSM. `Tutorial` in
|
||||
`src/game/tutorial.gd` owns the eight beats, accepts only the current beat's action,
|
||||
supports skip/restart and has deterministic headless tests. GameManager/UI wiring starts
|
||||
@@ -1544,7 +1544,7 @@ and supported by a stable CI/release baseline.
|
||||
|
||||
- [x] Existing scenario-content, tutorial and campaign smokes cover the venue/action/review paths;
|
||||
the 0.9.5 release candidate adds the external first-hour pass.
|
||||
- [x] `docs/getting-started.md` and `docs/release-qa.md#manual-smoke-checklist` list tutorial, campaign/checkpoint,
|
||||
- [x] `docs/process/getting-started.md` and `docs/process/release-qa.md#manual-smoke-checklist` list tutorial, campaign/checkpoint,
|
||||
session, scenario, audio, crowd, emergency, movement and performance smokes.
|
||||
- [x] Current gallery/judge baselines are green; the 0.9.5 release candidate refreshes the final
|
||||
gallery after content lock.
|
||||
@@ -1560,7 +1560,7 @@ and supported by a stable CI/release baseline.
|
||||
smoke requirement. This explicit matrix is documented.
|
||||
- [x] No project-wide upgrade in 0.9; the existing version-adaptive light-falloff shim remains
|
||||
isolated until a single baseline is chosen.
|
||||
- [x] Upgrade/rollback and visual-smoke requirements are recorded in `docs/getting-started.md`
|
||||
- [x] Upgrade/rollback and visual-smoke requirements are recorded in `docs/process/getting-started.md`
|
||||
and `MEMORY.md`.
|
||||
- [ ] Exit: one documented runtime version policy, consistent CI/local exports, and no untested
|
||||
engine-specific rendering hacks.
|
||||
@@ -1589,7 +1589,7 @@ Goal: streamline the maps, refactor geometry to match the images in `docs/screen
|
||||
- [x] Remove unnecessary or hidden geometry to improve performance.
|
||||
- [x] Ensure texture and material consistency across the map.
|
||||
|
||||
Completed: the Hollywood venue is rebuilt from the real 6840 Hollywood Blvd references (six-column Masonic/El Capitan facade, eight steps, neighbours, Ovation arcade, Walk of Fame, four-lane street). The map-budget test measures 58,884 triangles across 409 meshes; Day/Night menu variants start in `EARLY`/`LATE`; the realism judge gaps are 0.148 (day) and 0.278 (late). See `docs/venues.md#hollywood-boulevard`.
|
||||
Completed: the Hollywood venue is rebuilt from the real 6840 Hollywood Blvd references (six-column Masonic/El Capitan facade, eight steps, neighbours, Ovation arcade, Walk of Fame, four-lane street). The map-budget test measures 58,884 triangles across 409 meshes; Day/Night menu variants start in `EARLY`/`LATE`; the realism judge gaps are 0.148 (day) and 0.278 (late). See `docs/design/venues.md#hollywood-boulevard`.
|
||||
|
||||
### Map 2 — Joke Shop
|
||||
|
||||
@@ -1601,7 +1601,7 @@ Completed: the Hollywood venue is rebuilt from the real 6840 Hollywood Blvd refe
|
||||
- [x] Remove unnecessary or hidden geometry to improve performance.
|
||||
- [x] Ensure texture and material consistency across the map.
|
||||
|
||||
Completed 2026-11-02: the Joke Shop is rebuilt from the real Comedy Store block at 8433 Sunset Blvd (27 m black hall, signature canopy, circular blade sign, red curtains, west entrance, low-rise neighbours, dry hillside and opposite frontage). The map-budget test measures 22,680 triangles across 454 meshes. The day/late captures and real-site notes are in `docs/venues.md#the-joke-shop` and `docs/screens/concepts/joke_shop/`; the final gallery passed 13 good / 0 bad and the screen-design judge (13/13 match, 0 diff), with a 0.454 realism gap on the photoreal night reference.
|
||||
Completed 2026-11-02: the Joke Shop is rebuilt from the real Comedy Store block at 8433 Sunset Blvd (27 m black hall, signature canopy, circular blade sign, red curtains, west entrance, low-rise neighbours, dry hillside and opposite frontage). The map-budget test measures 22,680 triangles across 454 meshes. The day/late captures and real-site notes are in `docs/design/venues.md#the-joke-shop` and `docs/screens/concepts/joke_shop/`; the final gallery passed 13 good / 0 bad and the screen-design judge (13/13 match, 0 diff), with a 0.454 realism gap on the photoreal night reference.
|
||||
|
||||
### Scenery Change (Day/Night) for Hollywood Boulevard
|
||||
|
||||
@@ -1646,7 +1646,7 @@ redesign.
|
||||
|
||||
- [x] Do not run the release build, bump a release version or tag until the map exit criteria and
|
||||
this NPC revisit are both signed off.
|
||||
- [x] Record the sign-off in `docs/development-status.md` and `MEMORY.md`, then hand off to the
|
||||
- [x] Record the sign-off in `docs/project/development-status.md` and `MEMORY.md`, then hand off to the
|
||||
postponed integration/build milestone.
|
||||
|
||||
**Exit:** the final maps and lighting still present the NPCs clearly; no untriaged NPC regression
|
||||
@@ -1663,20 +1663,20 @@ screen-design judge before any model/texture changes. No gameplay rules change.
|
||||
|
||||
- [x] Inventory every screen/panel: start menu, venue menu, tutorial, HUD, pause,
|
||||
settings, Help, inspection, wand, radio/emergency, wheel, shift review,
|
||||
timeline and campaign/continue screens. Recorded in `docs/ui-copy.md`.
|
||||
timeline and campaign/continue screens. Recorded in `docs/design/ui-copy.md`.
|
||||
- [x] Record the canonical terms for admit/refuse, warning/blocking,
|
||||
assistance/emergency, body camera, shift review and campaign; the current
|
||||
inspection/wand/radio/review labels use them (see `docs/ui-copy.md`).
|
||||
inspection/wand/radio/review labels use them (see `docs/design/ui-copy.md`).
|
||||
- [x] Audit all button labels for verb-first wording, capitalization, ordering,
|
||||
destructive-action confirmation and consistent confirm/cancel placement;
|
||||
recorded in `docs/ui-copy.md` and fixed Quit/Apply wording.
|
||||
recorded in `docs/design/ui-copy.md` and fixed Quit/Apply wording.
|
||||
- [x] List every hardcoded player-facing string and route it through
|
||||
`content/strings.en.json`; remaining UI literals are numeric/debug-only or
|
||||
dynamic data. Placeholder validation covers the new keys.
|
||||
- [x] Review NPC/door-staff/radio/tutorial/help/review/campaign dialogue for
|
||||
repetition, ambiguity, tone and localization length. (Reason contexts,
|
||||
door-staff lines, radio/tutorial/help copy and length findings recorded in
|
||||
`docs/ui-copy.md`; longest dialogue line is 56 characters.)
|
||||
`docs/design/ui-copy.md`; longest dialogue line is 56 characters.)
|
||||
|
||||
### Button and panel behavior
|
||||
|
||||
@@ -1684,15 +1684,15 @@ screen-design judge before any model/texture changes. No gameplay rules change.
|
||||
tutorial skip, venue continue, settings apply/cancel/reset, judge/review,
|
||||
radio send/emergency hold and Help close. (Shared `UiStyles` states applied;
|
||||
timeline boundary disabling and the keyboard-only F1 skip are documented in
|
||||
`docs/ui-copy.md`.)
|
||||
`docs/design/ui-copy.md`.)
|
||||
- [x] Verify keyboard-only and gamepad-only navigation: focus order, wrapping,
|
||||
default focus, confirm/cancel behavior and no focus traps. (Focus rings,
|
||||
gamepad A/B UI bindings, default focus and per-modal cancel behavior are
|
||||
recorded in `docs/ui-copy.md`.)
|
||||
recorded in `docs/design/ui-copy.md`.)
|
||||
- [x] Verify every modal closes with Esc/right-click where documented, recaptures
|
||||
the mouse, and does not leave the guard frozen or the menu visible. (Single
|
||||
top-modal close path, menu/settings return handling and pointer recapture are
|
||||
recorded in `docs/ui-copy.md`; session smoke covers menu Settings, Help
|
||||
recorded in `docs/design/ui-copy.md`; session smoke covers menu Settings, Help
|
||||
right-click and pause Settings.)
|
||||
- [x] Test buttons at minimum/maximum HUD font scale and with 1.5–2× longer
|
||||
strings; fix clipping, overflow and overlapping layouts. (Target chip now
|
||||
@@ -1720,9 +1720,9 @@ screen-design judge before any model/texture changes. No gameplay rules change.
|
||||
- [x] Ran `tools/check_screenshots.sh` and `screen_designs.py compare`: 21 good,
|
||||
0 bad.
|
||||
- [x] Ran the judge with automatic model selection: 21/21 match, 0 review, 0 diff.
|
||||
- [x] Recorded the judge model and result in `docs/ui-copy.md#screen-design-judge-report`; the
|
||||
- [x] Recorded the judge model and result in `docs/design/ui-copy.md#screen-design-judge-report`; the
|
||||
generated captures remain local/gitignored.
|
||||
- [x] Add a short UI copy/button checklist to `docs/release-qa.md#manual-smoke-checklist`.
|
||||
- [x] Add a short UI copy/button checklist to `docs/process/release-qa.md#manual-smoke-checklist`.
|
||||
- [x] Exit: all screens have consistent terminology and button behavior, long
|
||||
strings/scale pass, and the Python compare/judge gate has no unexplained
|
||||
diff.
|
||||
@@ -1755,7 +1755,7 @@ fallback behavior.
|
||||
the side-by-side after sheet without overwriting it.)
|
||||
|
||||
Completed 2026-11-02: 48-frame neutral studio baseline, eight criteria, current fit and
|
||||
triangle/vertex measurements, and ranked P1/P2 gaps are in `docs/3d-model-review.md`. The
|
||||
triangle/vertex measurements, and ranked P1/P2 gaps are in `docs/assets/3d-model-review.md`. The
|
||||
baseline itself changed no character models; the first P1 gear fixes are recorded under Gear
|
||||
and equipment fit.
|
||||
|
||||
@@ -1768,7 +1768,7 @@ and equipment fit.
|
||||
|
||||
- [x] Audit all variants against a shared human proportion guide (head height, shoulder width,
|
||||
torso length, hip width, limb length, foot length) and correct the worst outliers.
|
||||
(`tools/npc_proportions.py` + `docs/3d-model-review.md#character-measurements`: all eight pass; no skeleton or
|
||||
(`tools/npc_proportions.py` + `docs/assets/3d-model-review.md#character-measurements`: all eight pass; no skeleton or
|
||||
mesh rescue was needed. Head and broad-build silhouettes are nearest their upper bounds.)
|
||||
- [x] Improve the neck and shoulder transition so the silhouette reads as one body rather than a
|
||||
thin post on a hanger. (Fuller neck base/top, lower shoulder root, degenerate-face cleanup;
|
||||
@@ -1857,7 +1857,7 @@ and equipment fit.
|
||||
`blender_assets.py audit`, `fit`, character imports and the full Godot test suite.
|
||||
- [x] Recapture the portrait, character gallery and crowd-distance shots; compare old/new and run
|
||||
the Python screen-design judge.
|
||||
- [x] Update `docs/blender-assets.md`, architecture/status, `MEMORY.md` and the changelog with the
|
||||
- [x] Update `docs/assets/blender-assets.md`, architecture/status, `MEMORY.md` and the changelog with the
|
||||
new budgets, limitations and rebuild commands.
|
||||
- [x] Exit: all eight variants pass the portrait/readability criteria, gear and hems no longer
|
||||
clip in normal play, the 24-NPC budget remains green, and the visual judge has no unexplained
|
||||
@@ -2007,7 +2007,7 @@ target paths and leave a clean release-candidate handoff.
|
||||
final patch-level results and any remaining gaps. (README/PLAN/architecture
|
||||
now point at 0.9.6; the changelog and development status record the
|
||||
integration build, performance numbers, judge results and the clean-worktree
|
||||
export rule; `docs/RELEASING.md` documents the ignored-folder trap.)
|
||||
export rule; `docs/process/RELEASING.md` documents the ignored-folder trap.)
|
||||
- [x] Tag/version or otherwise freeze `0.9.6` as the integration checkpoint before
|
||||
the `0.10.0` release candidate. (Tag `v0.9.6` on `4bb2896`; Gitea run 1296
|
||||
passed checks and the full build and published seven assets.)
|
||||
@@ -2050,7 +2050,7 @@ must inherit the reviewed face/hand/gear baseline instead of multiplying whateve
|
||||
the existing Blender contract. (Measured Quaternius CC0, Kenney CC0, Khronos
|
||||
CesiumMan/RiggedFigure CC-BY and the MakeHuman CC0 base mesh; none is a drop-in.
|
||||
Results, local preview sheet and SHA-256 provenance are in
|
||||
`docs/npc-model-sourcing.md`.)
|
||||
`docs/assets/npc-model-sourcing.md`.)
|
||||
- [x] Review the sourcing research with the project owner and choose Option A (procedural),
|
||||
Option B (Quaternius CC0 intake) or Option C (MakeHuman/MPFB body pipeline); record the
|
||||
decision in an ADR and in `MEMORY.md`. (2026-11-03: extend the procedural generator as the
|
||||
@@ -2127,7 +2127,7 @@ must inherit the reviewed face/hand/gear baseline instead of multiplying whateve
|
||||
- [x] Gates with the expanded library: 24-NPC budget smoke 152,464 tris / 168 meshes / 6.94 ms
|
||||
(under 50 ms), portrait baseline 12 variants × 6 views, `fit` clean, Godot 277/277, Python
|
||||
160/160. No release build is created for this unversioned track.
|
||||
- [x] Docs: `docs/development-status.md`, `docs/3d-model-review.md` and the baseline sheet updated;
|
||||
- [x] Docs: `docs/project/development-status.md`, `docs/assets/3d-model-review.md` and the baseline sheet updated;
|
||||
`CREDITS.md` needs no change (the crowd variants are procedural, no new source). Accepted
|
||||
visual limits: the crowd accessories (umbrella canopy, cup, sunglasses, beard) read at
|
||||
full-body distance but not in the head-only portrait framing.
|
||||
@@ -2154,7 +2154,7 @@ Goal: `src/test/capture_npc_pose.gd` reports a pose but saves rest frames; the r
|
||||
narrowed to the skinned mesh ignoring its `Rig` parent transform. Fixing it unblocks the
|
||||
weights/pose column of the 3D review; the evidence now feeds the Quaternius base bake.
|
||||
|
||||
*Skill route: `rigging`; evidence in `docs/3d-model-review.md` §"Pose evidence is blocked".*
|
||||
*Skill route: `rigging`; evidence in `docs/assets/3d-model-review.md` §"Pose evidence is blocked".*
|
||||
|
||||
- [x] Root cause found (2026-11-04): the harness never disabled the avatar's `_physics_process`,
|
||||
so `_advance_fsm` + `_move_toward_target` ran every tick and reset `arrived`/velocity, which
|
||||
@@ -2205,8 +2205,8 @@ player-facing system. The 0.10.0 minor is reserved for the release gates (see be
|
||||
blocked rig can no longer block the whole release.
|
||||
|
||||
**Completed 2026-11-06.** Shipped as `v0.9.9` (tagged, local release build with checksums)
|
||||
and accepted by the owner after the follow-up fixes. Durable evidence: `docs/3d-model-review.md`,
|
||||
`docs/blender-assets.md`, `docs/adr/0018-quaternius-stage2-runtime-rig.md`.
|
||||
and accepted by the owner after the follow-up fixes. Durable evidence: `docs/assets/3d-model-review.md`,
|
||||
`docs/assets/blender-assets.md`, `docs/adr/0018-quaternius-stage2-runtime-rig.md`.
|
||||
|
||||
### Rig and export correction
|
||||
|
||||
@@ -2264,7 +2264,7 @@ and accepted by the owner after the follow-up fixes. Durable evidence: `docs/3d-
|
||||
`npc_proportions`).
|
||||
- [x] Owner visual signoff obtained (2026-11-06) on the roster, the faces, the head gear and the
|
||||
hand/back gear. The review page and its sheets were retired after acceptance; the measurements
|
||||
live on in `docs/3d-model-review.md` and `docs/blender-assets.md`.
|
||||
live on in `docs/assets/3d-model-review.md` and `docs/assets/blender-assets.md`.
|
||||
- [x] Face-fidelity comparison was made and the full swap chosen; the comparison sheets were
|
||||
retired with the review pages, and the decision is recorded in the follow-up section of
|
||||
[`docs/adr/0018-quaternius-stage2-runtime-rig.md`](docs/adr/0018-quaternius-stage2-runtime-rig.md).
|
||||
@@ -2272,7 +2272,7 @@ and accepted by the owner after the follow-up fixes. Durable evidence: `docs/3d-
|
||||
baked from the three Quaternius sources inside 24,000 tris / 24,000 glTF vertices
|
||||
(`a6ccd86`), and the gate was re-run.
|
||||
- [x] Record the decision and its consequence in `MEMORY.md`,
|
||||
`docs/npc-model-sourcing.md#shipped-roster-099-owner-chose-the-full-swap` and the
|
||||
`docs/assets/npc-model-sourcing.md#shipped-roster-099-owner-chose-the-full-swap` and the
|
||||
follow-up decision section of
|
||||
[`docs/adr/0018-quaternius-stage2-runtime-rig.md`](docs/adr/0018-quaternius-stage2-runtime-rig.md).
|
||||
- [x] Owner visual signoff on the shipped roster (2026-11-06): accepted.
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
Session memory for durable decisions, gotchas, and commands. Implementation history lives in
|
||||
`DONE.md`, user-facing changes in `CHANGELOG.md`, the live task list in `TODO.md`, and the
|
||||
canonical implemented-features list in `docs/development-status.md`.
|
||||
canonical implemented-features list in `docs/project/development-status.md`.
|
||||
|
||||
## Decisions
|
||||
|
||||
@@ -13,8 +13,8 @@ canonical implemented-features list in `docs/development-status.md`.
|
||||
- **AI-assisted asset review loop (2026-11-04):** head/face shape decisions use a concept +
|
||||
judge loop — generate a target concept (`generate_textures.generate_image`, Seedream) and use
|
||||
`tools/describe_image.py` as the vision judge, iterating until the judge's specific fixes
|
||||
converge. Review pages: `docs/screens/head-review/README.md`, `docs/3d-model-review.md`
|
||||
§AI-driven head rework.
|
||||
converge. Durable evidence: `docs/assets/3d-model-review.md` §AI-driven head rework; the
|
||||
retired head-review page was removed in the 2026-11-06 docs restructure.
|
||||
- **Project agent skills (2026-11-03):** two tracked skills live in `.agents/skills/`:
|
||||
`gig-line-blender-asset-contract` and `gig-line-release-qa`. They are guidance only,
|
||||
add no runtime dependency and are referenced from `tools/README.md`. The third-party
|
||||
@@ -24,7 +24,7 @@ canonical implemented-features list in `docs/development-status.md`.
|
||||
restaged for a late-night arrival. `VENUE_SPECS["tv_studio"]` is a 30.0 m variant of the 29.6 m
|
||||
Hollywood facade. One reference board serves both venues; never create a separate TV Studio board.
|
||||
- **Jimmy Kimmel Live = starting point:** the Hollywood first shift and the TV Studio arrival both
|
||||
begin at the El Capitan block. Stated in `docs/venues.md#hollywood-boulevard` and `docs/gameplay.md`.
|
||||
begin at the El Capitan block. Stated in `docs/design/venues.md#hollywood-boulevard` and `docs/design/gameplay.md`.
|
||||
- **Street-view limitation:** Google Street View panoramas need a Google API key or manual browser
|
||||
capture, so the local reference sets use DDG street-level photos instead.
|
||||
- **Image-recitation filter:** Gemini image models reject well-known branded facades (Comedy Store
|
||||
@@ -54,12 +54,12 @@ canonical implemented-features list in `docs/development-status.md`.
|
||||
privacy, Compatibility/Web cost and mesh collision. Accepted photo channels: team captures,
|
||||
permissioned user/volunteer photos, clearly licensed downloads; every set needs a
|
||||
provenance/consent sidecar. No runtime splat dependency in 0.10.0.
|
||||
- **0.10.0 balance protocol:** `docs/release-qa.md#balance-acceptance` defines targets/denominators for the
|
||||
- **0.10.0 balance protocol:** `docs/process/release-qa.md#balance-acceptance` defines targets/denominators for the
|
||||
36 venue/difficulty/phase cells, seeds 1–100, and access/emergency error rates. Gotcha:
|
||||
`_read_npc_truth()` is type-derived, not behaviour-derived; the emergency-fairness review must
|
||||
account for that oracle mismatch.
|
||||
- **Blender MCP is optional (2026-11-04):** setup and safe part workflow are in
|
||||
`docs/asset-tooling.md#optional-interactive-blender-mcp`. The headless flatpak scripts remain authoritative; MCP is
|
||||
`docs/assets/asset-tooling.md#optional-interactive-blender-mcp`. The headless flatpak scripts remain authoritative; MCP is
|
||||
never a build/CI/test/runtime dependency, and anything MCP touched must pass the
|
||||
CLI audit/fit gates.
|
||||
- **Character mesh cap (2026-11-05):** all characters use 24,000 tris / 24,000 glTF vertices
|
||||
@@ -108,7 +108,7 @@ canonical implemented-features list in `docs/development-status.md`.
|
||||
avatars. Head-turn offsets use `+basis.z` for the same reason.
|
||||
- **Release blockers (still open):** macOS unsigned, AI image provider terms/commercial rights not
|
||||
cleared, storefront/rating approval pending, external playtests and full hardware matrix pending.
|
||||
Recorded in `CREDITS.md`, `PRIVACY.md`, `docs/accessibility.md`, `docs/known-limitations.md`.
|
||||
Recorded in `CREDITS.md`, `PRIVACY.md`, `docs/design/accessibility.md`, `docs/design/known-limitations.md`.
|
||||
|
||||
- **Release roadmap (2026-11-05, owner):** `0.9.9` Quaternius pilot base (rig/export fix,
|
||||
rest-relative pose math, owner face/silhouette gate), `0.9.10` 12-role roster, `0.9.11`
|
||||
@@ -345,7 +345,7 @@ canonical implemented-features list in `docs/development-status.md`.
|
||||
|
||||
## Current State
|
||||
|
||||
v0.9.8 is published. The build covers the three venues, the shift loop, tutorial/campaign/
|
||||
v0.9.9 is published. The build covers the three venues, the shift loop, tutorial/campaign/
|
||||
checkpoints, the 0.9.3–0.9.8 polish/texture/integration/character passes and the Blender +
|
||||
realism asset pipeline (see `DONE.md` and `CHANGELOG.md`). The 12-character procedural library
|
||||
(realistic face + four crowd variants) and the Comedy Store map rebuild are complete.
|
||||
@@ -363,7 +363,7 @@ body defects (holes, unibrow, missing eyes) and the head-gear seating are fixed,
|
||||
the firefighter helmet is removed, and every head has an authored mouth. Gates: `audit` 12/12,
|
||||
`inspect` clean, `fit` OK, 24-NPC budget 174,976 tris / 0.85 ms, Godot 278/278, Python 167/167.
|
||||
The owner **accepted the roster on 2026-11-06** and the review page plus its sheets were then
|
||||
retired; durable evidence lives in `docs/3d-model-review.md` and `docs/blender-assets.md`. Release
|
||||
retired; durable evidence lives in `docs/assets/3d-model-review.md` and `docs/assets/blender-assets.md`. Release
|
||||
packaging was fixed the same day:
|
||||
excluding `tmp/`, `build/`, `docs/`, `tools/`, `src/test/` and `.agents/` from the export presets
|
||||
cut the Linux binary from 426 MB to 273 MB, and `tools/build_releases.sh` writes a SHA256SUMS file.
|
||||
@@ -381,6 +381,12 @@ code on the 62-joint rig, and the procedural rigs are visually unchanged. Verifi
|
||||
0.82 ms avg frame). The face/silhouette gate sheet and the three options are in
|
||||
the face-gate decision (owner chose the full swap).
|
||||
|
||||
Test counts as of 2026-11-05: Python 167/167, Godot 278/278, `check_docs` OK.
|
||||
Test counts as of 2026-11-06: Python 167/167, Godot 278/278, `check_docs` OK.
|
||||
|
||||
**Docs layout (2026-11-06):** `docs/` is grouped into `project/`, `design/`, `assets/` and
|
||||
`process/`; `adr/`, `screens/`, `screenshots/` and `blender_previews/` are unchanged.
|
||||
`docs/README.md` is the index and every category folder has a README (required by
|
||||
`tools/check_docs.py`). The retired `docs/screens/head-review/` page and its sheets were deleted;
|
||||
the MakeHuman fallback head is documented in `docs/assets/makehuman-head-review.md`.
|
||||
|
||||
<!-- b64: RWFzdGVyIGVnZzogYSByYXJlIHJhZGlvIHRyYW5zbWlzc2lvbiAiwr9Ew7NuZGUgZXN0w6EgbGEgbW90YT8iIGZpcmVzIHZpYSBHYW1lTWFuYWdlci5fbWF5YmVfcmFkaW9fZWFzdGVyX2VnZyAoMi41JSBjaGFuY2UgYWZ0ZXIgYSBzdWNjZXNzZnVsIHJhZGlvIGNhbGwpLiBTdHJpbmcga2V5IHJhZGlvLmVhc3Rlcl9lZ2cgaW4gY29udGVudC9zdHJpbmdzLmVuLmpzb24uIERvIG5vdCByZW1vdmUu -->
|
||||
@@ -265,7 +265,7 @@ Primary decisions: [ADR-0007](docs/adr/0007-locomotion-and-input-layers.md), [AD
|
||||
|
||||
## Versioning and Delivery
|
||||
|
||||
`config/version` in `project.godot` is the single version source (currently `0.9.8`). Releases are tagged `v<version>`; the CI pipeline builds and publishes the standard artifacts plus the optional Desktop HQ zip. Version bumps follow [Semantic Versioning](https://semver.org/): every major, minor and patch increment needs a changelog entry, a local `tools/build_releases.sh` build, and artifact/checksum verification before tagging. Unversioned development tracks do not receive a version until their scope enters a release. See [`docs/RELEASING.md`](docs/RELEASING.md) and [`README.md`](README.md) for commands.
|
||||
`config/version` in `project.godot` is the single version source (currently `0.9.9`). Releases are tagged `v<version>`; the CI pipeline builds and publishes the standard artifacts plus the optional Desktop HQ zip. Version bumps follow [Semantic Versioning](https://semver.org/): every major, minor and patch increment needs a changelog entry, a local `tools/build_releases.sh` build, and artifact/checksum verification before tagging. Unversioned development tracks do not receive a version until their scope enters a release. See [`docs/process/RELEASING.md`](docs/process/RELEASING.md) and [`README.md`](README.md) for commands.
|
||||
|
||||
## Gap Analysis
|
||||
|
||||
|
||||
+1
-1
@@ -14,7 +14,7 @@ Player data is written only to Godot's local `user://` directory:
|
||||
|
||||
Those files stay on the player's machine unless the player copies them. Deleting
|
||||
the files (or the `Gig Line` user directory) resets the profile. See
|
||||
[`docs/getting-started.md`](docs/getting-started.md#save-data-and-migration) for
|
||||
[`docs/process/getting-started.md`](docs/process/getting-started.md#save-data) for
|
||||
locations, migration and rollback instructions.
|
||||
|
||||
The repository's development tools can call OpenRouter when a developer supplies
|
||||
|
||||
@@ -46,13 +46,13 @@ Versions are assigned only when a track's scope is accepted into a release. Ever
|
||||
> development track remains gated on the Quaternius NPC rollout, local-map work
|
||||
> and release approvals.
|
||||
> Releases are built automatically when a `vX.Y.Z` tag is pushed
|
||||
> (see [`docs/RELEASING.md`](docs/RELEASING.md)); manual builds use
|
||||
> (see [`docs/process/RELEASING.md`](docs/process/RELEASING.md)); manual builds use
|
||||
> `./tools/build_releases.sh`. Installer/AppImage packaging runs in the same pipeline
|
||||
> (NSIS + appimagetool) and uploads with the portable binaries.
|
||||
>
|
||||
> macOS builds are unsigned: right-click → Open, or clear the quarantine with
|
||||
> `xattr -dr com.apple.quarantine gig-line-macos.zip`. Build instructions and
|
||||
> the release pipeline live in [`docs/RELEASING.md`](docs/RELEASING.md).
|
||||
> the release pipeline live in [`docs/process/RELEASING.md`](docs/process/RELEASING.md).
|
||||
|
||||
If you are here to develop or test locally instead of downloading, jump to
|
||||
[Setup and Run](#setup-and-run) below.
|
||||
@@ -112,7 +112,7 @@ current library and will be replaced after the 12 × 6 baseline review.
|
||||
|  | **Crowd variety prototypes.** Four approved looks (bun/slim, bald/broad, coat/umbrella, hood/cup) queued for the roster build. |
|
||||
|
||||
More sheets and the review criteria are in [`docs/blender_previews/`](docs/blender_previews/README.md)
|
||||
and [`docs/3d-model-review.md`](docs/3d-model-review.md).
|
||||
and [`docs/assets/3d-model-review.md`](docs/assets/3d-model-review.md).
|
||||
|
||||
## Game Overview
|
||||
|
||||
@@ -122,7 +122,7 @@ tickets or credentials, and escalate only when necessary. The game rewards calm
|
||||
resolution over force. The venue menu splits Hollywood Boulevard into Day and
|
||||
Night rows; the full mechanics — the three venues, the six-level
|
||||
escalation model, and the core systems — are in
|
||||
[`docs/gameplay.md`](docs/gameplay.md); the design rationale lives in
|
||||
[`docs/design/gameplay.md`](docs/design/gameplay.md); the design rationale lives in
|
||||
[`PLAN.md`](PLAN.md).
|
||||
|
||||
## Architecture
|
||||
@@ -130,8 +130,8 @@ escalation model, and the core systems — are in
|
||||
A venue-driven simulation: shared systems (movement, perception, interaction,
|
||||
access verification, escalation, radio, crowd, reputation, evidence, shift
|
||||
review) driven by per-venue scenario data, on Godot 4 + GDScript. The full
|
||||
arc42-style document is [`docs/architecture.md`](docs/architecture.md);
|
||||
decisions are recorded as ADRs in [`docs/adr/`](docs/adr/).
|
||||
arc42-style document is [`docs/project/architecture.md`](docs/project/architecture.md);
|
||||
decisions are recorded as ADRs in [`docs/adr/`](docs/adr).
|
||||
|
||||
## Tech Stack
|
||||
|
||||
@@ -144,7 +144,7 @@ decisions are recorded as ADRs in [`docs/adr/`](docs/adr/).
|
||||
- **Targets:** Windows, Linux, macOS, Web
|
||||
|
||||
The asset pipelines, model tools, and screenshot gates are documented in
|
||||
[`docs/asset-tooling.md`](docs/asset-tooling.md).
|
||||
[`docs/assets/asset-tooling.md`](docs/assets/asset-tooling.md).
|
||||
|
||||
## Setup and Run
|
||||
|
||||
@@ -157,36 +157,36 @@ godot --headless --path . --script res://src/test/test_runner.gd # run all tes
|
||||
```
|
||||
|
||||
Full setup, every run/test/smoke command, and the controls table are in
|
||||
[`docs/getting-started.md`](docs/getting-started.md).
|
||||
[`docs/process/getting-started.md`](docs/process/getting-started.md).
|
||||
|
||||
## Project Documentation
|
||||
|
||||
- [`PLAN.md`](PLAN.md) — Game design plan, development priorities and scenario details.
|
||||
- [`TODO.md`](TODO.md) — Priority-ordered tasks: character and local-map development, release milestones, and future work.
|
||||
- [`docs/README.md`](docs/README.md) — Documentation index, current priorities and visual previews.
|
||||
- [`docs/npc-model-sourcing.md`](docs/npc-model-sourcing.md) — Character-source evaluation, licence rules and the character-development plan.
|
||||
- [`docs/makehuman-head-review.md`](docs/makehuman-head-review.md) — Local MakeHuman head prototype, provenance and review verdict.
|
||||
- [`docs/assets/npc-model-sourcing.md`](docs/assets/npc-model-sourcing.md) — Character-source evaluation, licence rules and the character-development plan.
|
||||
- [`docs/assets/makehuman-head-review.md`](docs/assets/makehuman-head-review.md) — Local MakeHuman head prototype, provenance and review verdict.
|
||||
- [`AGENTS.md`](AGENTS.md) — Development, commit, build and collaboration workflow.
|
||||
- [`DONE.md`](DONE.md) — Completed task sections.
|
||||
- [`MEMORY.md`](MEMORY.md) — Persistent session notes.
|
||||
- [`CHANGELOG.md`](CHANGELOG.md) — User-facing changes by version.
|
||||
- [`docs/architecture.md`](docs/architecture.md) — arc42-style architecture documentation.
|
||||
- [`docs/gameplay.md`](docs/gameplay.md) — Gameplay systems, venues, and the escalation model.
|
||||
- [`docs/venues.md`](docs/venues.md) — Real-site references, game mapping and limitations for Hollywood, the Joke Shop and the TV Studio.
|
||||
- [`docs/asset-tooling.md`](docs/asset-tooling.md) — Asset pipelines, model tools, and screenshot gates.
|
||||
- [`docs/project/architecture.md`](docs/project/architecture.md) — arc42-style architecture documentation.
|
||||
- [`docs/design/gameplay.md`](docs/design/gameplay.md) — Gameplay systems, venues, and the escalation model.
|
||||
- [`docs/design/venues.md`](docs/design/venues.md) — Real-site references, game mapping and limitations for Hollywood, the Joke Shop and the TV Studio.
|
||||
- [`docs/assets/asset-tooling.md`](docs/assets/asset-tooling.md) — Asset pipelines, model tools, and screenshot gates.
|
||||
- [`tools/README.md`](tools/README.md) — Tool inventory, categories, test commands and AI-skill evaluation.
|
||||
- [`.agents/skills/gig-line-blender-asset-contract`](.agents/skills/gig-line-blender-asset-contract/SKILL.md) — tracked AI skill for Blender/NPC/gear asset work.
|
||||
- [`.agents/skills/gig-line-release-qa`](.agents/skills/gig-line-release-qa/SKILL.md) — tracked AI skill for release and visual-QA work.
|
||||
- [`docs/getting-started.md`](docs/getting-started.md) — Setup, run/test commands, and controls.
|
||||
- [`docs/development-status.md`](docs/development-status.md) — Implemented features and what's next.
|
||||
- [`docs/accessibility.md`](docs/accessibility.md) — Accessibility features, known gaps and statement.
|
||||
- [`docs/known-limitations.md`](docs/known-limitations.md) — Release-candidate blockers and accepted limitations.
|
||||
- [`docs/release-qa.md`](docs/release-qa.md) — Manual smoke checklist and release-candidate balance protocol.
|
||||
- [`docs/process/getting-started.md`](docs/process/getting-started.md) — Setup, run/test commands, and controls.
|
||||
- [`docs/project/development-status.md`](docs/project/development-status.md) — Implemented features and what's next.
|
||||
- [`docs/design/accessibility.md`](docs/design/accessibility.md) — Accessibility features, known gaps and statement.
|
||||
- [`docs/design/known-limitations.md`](docs/design/known-limitations.md) — Release-candidate blockers and accepted limitations.
|
||||
- [`docs/process/release-qa.md`](docs/process/release-qa.md) — Manual smoke checklist and release-candidate balance protocol.
|
||||
- [`CREDITS.md`](CREDITS.md) — Credits, AI/reference provenance and licensing notes.
|
||||
- [`PRIVACY.md`](PRIVACY.md) — Local-only data, save files and development API use.
|
||||
- [`docs/blender-assets.md`](docs/blender-assets.md) — Blender asset library: characters, gear, props, attach points.
|
||||
- [`docs/npc-model-sourcing.md`](docs/npc-model-sourcing.md) — character sources, the shipped roster table and the build steps; 0.9.5 texture comparison is in [`docs/blender_previews/sheet_texture_refinement_0.9.5.jpg`](docs/blender_previews/sheet_texture_refinement_0.9.5.jpg).
|
||||
- [`docs/adr/`](docs/adr/) — Architecture Decision Records.
|
||||
- [`docs/assets/blender-assets.md`](docs/assets/blender-assets.md) — Blender asset library: characters, gear, props, attach points.
|
||||
- [`docs/assets/npc-model-sourcing.md`](docs/assets/npc-model-sourcing.md) — character sources, the shipped roster table and the build steps; 0.9.5 texture comparison is in [`docs/blender_previews/sheet_texture_refinement_0.9.5.jpg`](docs/blender_previews/sheet_texture_refinement_0.9.5.jpg).
|
||||
- [`docs/adr/`](docs/adr) — Architecture Decision Records.
|
||||
|
||||
## Development Status
|
||||
|
||||
@@ -198,9 +198,9 @@ UI/accessibility polish, 0.9.2 Hollywood/Joke Shop maps and the 0.9.x engine
|
||||
baseline. The active work is the `0.9.9`–`0.9.12` patch line (Quaternius NPC
|
||||
base, roster, venue/asset polish, performance) followed by the `0.10.0`
|
||||
public-readiness minor. See
|
||||
[`docs/development-status.md`](docs/development-status.md) for the implemented list
|
||||
[`docs/project/development-status.md`](docs/project/development-status.md) for the implemented list
|
||||
and [`TODO.md`](TODO.md) for the priority-ordered roadmap. Manual verification uses
|
||||
[`docs/release-qa.md`](docs/release-qa.md).
|
||||
[`docs/process/release-qa.md`](docs/process/release-qa.md).
|
||||
|
||||
## Credits, Privacy and Accessibility
|
||||
|
||||
@@ -209,8 +209,8 @@ network service, and saves stay in Godot's local `user://` folder. The
|
||||
body-camera overlay is simulated. Asset provenance, AI-assisted image usage and
|
||||
credits are recorded in [`CREDITS.md`](CREDITS.md); the local-data policy is in
|
||||
[`PRIVACY.md`](PRIVACY.md); accessibility features and gaps are in
|
||||
[`docs/accessibility.md`](docs/accessibility.md); and release-candidate blockers
|
||||
are listed in [`docs/known-limitations.md`](docs/known-limitations.md).
|
||||
[`docs/design/accessibility.md`](docs/design/accessibility.md); and release-candidate blockers
|
||||
are listed in [`docs/design/known-limitations.md`](docs/design/known-limitations.md).
|
||||
|
||||
## Development Workflow
|
||||
|
||||
|
||||
@@ -74,7 +74,7 @@ pieces, 20 library props, 6 generated props and the three venue families — plu
|
||||
pipeline that re-evaluates those venues (OSM data/licensing, reference imagery, the photoreal
|
||||
facade kit, AI-assisted composing, Gaussian-splatting evaluation and map QA).
|
||||
|
||||
**Exit (asset review, A–G):** `docs/3d-model-review.md` scores every catalogue asset; every P0/P1
|
||||
**Exit (asset review, A–G):** `docs/assets/3d-model-review.md` scores every catalogue asset; every P0/P1
|
||||
is fixed or explicitly accepted with a measurement; `inspect`/`audit`/`fit`/proportions, the
|
||||
24-NPC budget and the capture gates are green; no runtime contract, dependency or release artifact
|
||||
changed except the rebuilt assets themselves.
|
||||
@@ -111,16 +111,16 @@ licence-free zone only.
|
||||
(`elcapitan`, `hollywood-block`, `jimmy-kimmel-stage`, `jimmy-kimmel-entrance`,
|
||||
`comedy-store`).
|
||||
- [x] Record which local frames changed a decision: added the frame→decision mapping to
|
||||
`docs/venues.md#hollywood-boulevard` (recent `elcapitan-2026` geosearch → 2009 frame stays the
|
||||
`docs/design/venues.md#hollywood-boulevard` (recent `elcapitan-2026` geosearch → 2009 frame stays the
|
||||
geometry reference; `jimmy-kimmel-entrance/07.jpg` → the four entrance concepts) and
|
||||
`docs/venues.md#the-joke-shop` (`comedy-store/` → the four concept pairs + map plan;
|
||||
`docs/design/venues.md#the-joke-shop` (`comedy-store/` → the four concept pairs + map plan;
|
||||
`comedy-store-hillside/` → the day-concept anchor that clears the image-recitation filter).
|
||||
Frames stay gitignored; only the provenance notes are committed.
|
||||
|
||||
### B. Baseline, scorecard and routing
|
||||
|
||||
- [x] Load `blender-director` plus the per-family specialists before touching geometry, and
|
||||
record the skill stack and the advice that changed a decision in `docs/3d-model-review.md`.
|
||||
record the skill stack and the advice that changed a decision in `docs/assets/3d-model-review.md`.
|
||||
(Routing, QA severity/verdict, texel-density tiers, character loop criteria and budget rules
|
||||
recorded in the review doc; MCP-only steps translated to headless flatpak runs.)
|
||||
- [x] Re-run the neutral NPC baseline (48 frames), the final-context review (96 frames), the
|
||||
@@ -128,7 +128,7 @@ licence-free zone only.
|
||||
not replace committed sheets until a fix lands. (48/48 and 96/96 frames captured under
|
||||
`xvfb-run`, none blank; raw sets in `tmp/model-baseline` and `tmp/model-review`; committed
|
||||
sheets untouched. 24-NPC smoke still 6.94 ms / 168 meshes / 131,616 triangles.)
|
||||
- [x] Create `docs/3d-model-review.md` with a per-asset scorecard: silhouette, anatomy/proportion,
|
||||
- [x] Create `docs/assets/3d-model-review.md` with a per-asset scorecard: silhouette, anatomy/proportion,
|
||||
topology/edge flow, UV/texel density, textures/materials, rig/weights, LOD/impostor,
|
||||
collision/grounding, export contract, provenance, skill route, verdict (P0/P1/P2/accept).
|
||||
(Doc created with character/gear/prop/venue tables, verdict columns and a ranked candidate
|
||||
@@ -144,11 +144,10 @@ licence-free zone only.
|
||||
### C. Character re-evaluation (superseded 2026-11-05)
|
||||
|
||||
The procedural character review is complete and its evidence stays in
|
||||
`docs/3d-model-review.md`. The next character pass is the Quaternius base in
|
||||
[`Milestone 0.9.9`](#milestone-099--quaternius-npc-base-swap-patch) and
|
||||
[`Milestone 0.9.10`](#milestone-0910--npc-roster-rollout-patch); the open items below are kept
|
||||
as evidence for what the new base must not regress (face read, hands, weights, cloth, texel
|
||||
density, crowd variety).
|
||||
`docs/assets/3d-model-review.md`. The Quaternius base shipped in 0.9.9; the remaining roster
|
||||
follow-ups are [`Milestone 0.9.10`](#milestone-0910--npc-roster-rollout-patch). The open items
|
||||
below are kept as evidence for what the new base must not regress (face read, hands, weights,
|
||||
cloth, texel density, crowd variety).
|
||||
|
||||
*Skill route: `character-artist`, `retopology`, `rigging`, `uv-workflow`, `texture-workflow`,
|
||||
`materials`, `hair-groom`, `asset-optimization`, `lookdev`, `qa-review`.*
|
||||
@@ -175,7 +174,7 @@ density, crowd variety).
|
||||
hip fix clean, knee crease minor residual. The guard hip-pouch clip and the residual knee
|
||||
crease remain as 0.10.0 refinements.
|
||||
- [x] UV/texel density: measured (64–122 px/m authored, 287–440 px/m effective fabric on the 4×
|
||||
repeat; table in `docs/3d-model-review.md`). Decision: **accept as-is** — the maps are
|
||||
repeat; table in `docs/assets/3d-model-review.md`). Decision: **accept as-is** — the maps are
|
||||
neutral/runtime-tinted (not painted skin), so density controls only subtle weave/noise, and
|
||||
fabric already sits in the standard tier. No atlas/UDIM/resolution change is justified until
|
||||
a portrait shows texture starvation; `CHAR_MAX_TRIS`/`CHAR_MAX_VERTS` stay unchanged.
|
||||
@@ -187,7 +186,7 @@ density, crowd variety).
|
||||
reconsidered if a later close-up shows visible hem/coat stiffness.
|
||||
- [ ] Fix only the ranked P0/P1s, one asset family per commit; refresh the comparison sheet and
|
||||
re-run `inspect`, `audit`, `fit` and `npc_proportions.py` after each fix. **Scheduled: the
|
||||
remaining character items are covered by Milestone 0.9.9/0.9.10; this row is evidence only.**
|
||||
remaining character items are covered by Milestone 0.9.10; this row is evidence only.**
|
||||
- [x] Crowd-variety reference: five licence-cleared Commons photos fetched to
|
||||
`tmp/research/crowd-variety/` (CC0 ×2, CC BY 2.0, CC BY 3.0, PD) covering umbrella/dense
|
||||
crowds and a pedestrian mall — general build/hair/outer-layer variety context, reference
|
||||
@@ -200,7 +199,7 @@ density, crowd variety).
|
||||
- [x] `qa-review` sign-off: all eight variants **ship with notes** (face realism landed, hands/
|
||||
cloth/gear accepted, props reviewed); the weights/pose column is the only open item (blocked
|
||||
on the harness) and the full foliage carded-cluster is the one remaining owner-gated P1.
|
||||
Recorded in `docs/3d-model-review.md` §qa-review sign-off.
|
||||
Recorded in `docs/assets/3d-model-review.md` §qa-review sign-off.
|
||||
|
||||
### D. Gear and prop re-evaluation
|
||||
|
||||
@@ -209,7 +208,7 @@ density, crowd variety).
|
||||
|
||||
- [ ] Gear: review the 18 pieces for silhouette, straps/buckles, helmet and lanyard readability
|
||||
and rebuild only what fails the scorecard. (Attach/clearance verification is done — the
|
||||
`fit` report is recorded in `docs/3d-model-review.md` with the back-gear-vs-hip-radius
|
||||
`fit` report is recorded in `docs/assets/3d-model-review.md` with the back-gear-vs-hip-radius
|
||||
measurement caveat; the visual silhouette read is what remains, pending the owner scorecard.)
|
||||
- [ ] Props: review the 20 library props plus the 6 generated props for bevels, chamfers,
|
||||
silhouette, ground contact and shared material language (`prop-artist`, `hard-surface`);
|
||||
@@ -233,7 +232,7 @@ density, crowd variety).
|
||||
lamp) and rank the silhouette and proportion mismatches.
|
||||
- [ ] Rebuild only the mismatched pieces through the assisted Blender pipeline
|
||||
(`blender_assets.py inspect` → scripted retopo/UV assist → atlas → `audit`/`fit`); document
|
||||
the exact commands in `docs/asset-tooling.md`.
|
||||
the exact commands in `docs/assets/asset-tooling.md`.
|
||||
- [ ] Refresh `sheet_props.jpg`/`sheet_npc_gear.jpg`, the README asset rows and
|
||||
`docs/blender_previews/README.md` after the rebuilds.
|
||||
- [ ] Exit: a prop/gear capture sheet, budgets and collision checks pass with no unreviewed asset.
|
||||
@@ -293,8 +292,8 @@ density, crowd variety).
|
||||
`tools/three_up.py compose` renders labelled strips into `docs/screens/boards/` (caption
|
||||
sidecar per board, `rows` emits README rows). Boards committed: El Capitan day, El Capitan
|
||||
night, Joke Shop day. Tests in `tools/test_three_up.py`.
|
||||
- [x] Link each committed board from `docs/venues.md#hollywood-boulevard` and
|
||||
`docs/venues.md#the-joke-shop`.
|
||||
- [x] Link each committed board from `docs/design/venues.md#hollywood-boulevard` and
|
||||
`docs/design/venues.md#the-joke-shop`.
|
||||
- [ ] Use the generated concept lighting and palette as the target for the `lighting`/`lookdev`
|
||||
pass, and record the deviations that stay accepted.
|
||||
- [ ] After the pass, regenerate the venue captures and update README plus both venue documents.
|
||||
@@ -322,10 +321,10 @@ and never ship a generated or downloaded image without provenance.
|
||||
log and the generated-board reference table. Linked from `docs/screens/README.md`.)
|
||||
- [x] Hollywood board: five licence-cleared photos (facade day, blade sign, 1922 elevation,
|
||||
Ovation across street, premiere staging) with a sidecar and per-image purpose, linked from
|
||||
`docs/venues.md#hollywood-boulevard` and credited in `CREDITS.md`. Cropped the foreground crowd
|
||||
`docs/design/venues.md#hollywood-boulevard` and credited in `CREDITS.md`. Cropped the foreground crowd
|
||||
out of the facade shot; EXIF stripped. (`docs/screens/refs/hollywood/`.)
|
||||
- [x] Joke Shop board: three licence-cleared photos (hillside/canopy block, frontage with palms,
|
||||
canopy signature band) with a sidecar, linked from `docs/venues.md#the-joke-shop` and credited in
|
||||
canopy signature band) with a sidecar, linked from `docs/design/venues.md#the-joke-shop` and credited in
|
||||
`CREDITS.md`. The CC BY-SA `The Comedy Store.jpg` from the old link list was deliberately not
|
||||
used; the public-domain frames cover the same evidence. (`docs/screens/refs/joke-shop/`.)
|
||||
**Removed 2026-11-03:** the committed Comedy Store photo board was replaced by the local-only
|
||||
@@ -333,8 +332,8 @@ and never ship a generated or downloaded image without provenance.
|
||||
- [x] TV Studio: no separate board — the venue is the same El Capitan Entertainment Centre block as
|
||||
the Hollywood day shift, restaged for a late-night arrival. The Hollywood board covers both
|
||||
venues and the premiere-staging photo is the arrival evidence; the reuse is now stated in
|
||||
`docs/venues.md#hollywood-boulevard`, `docs/gameplay.md`, `PLAN.md` and
|
||||
`docs/development-status.md`.
|
||||
`docs/design/venues.md#hollywood-boulevard`, `docs/design/gameplay.md`, `PLAN.md` and
|
||||
`docs/project/development-status.md`.
|
||||
- [x] Fill the Hollywood gaps that have a clean licence: El Capitan Theatre neighbour and marquee,
|
||||
Walk of Fame terrazzo band, star close-up, and a night street-lighting context frame (cropped
|
||||
to remove people and a plate). The board now has nine photos. (CC BY-SA night frame is
|
||||
@@ -348,7 +347,7 @@ and never ship a generated or downloaded image without provenance.
|
||||
preview sheets.)
|
||||
- [ ] Apply the screenshot rule to every workstream: each accepted fix updates the relevant row in
|
||||
`README.md` plus the matching docs page (`docs/blender_previews/README.md`,
|
||||
`docs/screenshots/README.md`, `docs/3d-model-review.md` or the venue map doc).
|
||||
`docs/screenshots/README.md`, `docs/assets/3d-model-review.md` or the venue map doc).
|
||||
- [ ] Re-run `tools/check_screenshots.sh` and `python3 tools/check_docs.py` after gallery changes
|
||||
and record both results in the handoff.
|
||||
- [ ] Keep AI-generated images out of `assets/` until they are picked, cropped, credited and (for
|
||||
@@ -372,16 +371,16 @@ and never ship a generated or downloaded image without provenance.
|
||||
Suite is 275/275.)
|
||||
- [x] Add a coverage test so every catalogue asset has a scorecard row and verdict.
|
||||
(`tools/test_model_review.py`: every `CHARACTERS`/`GEAR`/`PROPS` entry needs a row in
|
||||
`docs/3d-model-review.md`, and character rows need a non-empty verdict.)
|
||||
- [x] Document the new gates: `docs/blender-assets.md` now lists `texels`, the
|
||||
`docs/assets/3d-model-review.md`, and character rows need a non-empty verdict.)
|
||||
- [x] Document the new gates: `docs/assets/blender-assets.md` now lists `texels`, the
|
||||
`test_model_review.py` coverage gate and the `test_world.gd` collider/proxy gate; skill
|
||||
routes live in `AGENTS.md` §Local Blender skills and each `TODO.md` section; the scorecard
|
||||
and evidence table are in `docs/3d-model-review.md`.
|
||||
- [x] Record accepted limits/deferred rebuilds: `docs/known-limitations.md` already records the
|
||||
and evidence table are in `docs/assets/3d-model-review.md`.
|
||||
- [x] Record accepted limits/deferred rebuilds: `docs/design/known-limitations.md` already records the
|
||||
stylized low-poly style, no finger-curl rig and the >26 m impostor; `MEMORY.md` holds the
|
||||
durable decisions (texel density accepted, cloth sim out of scope, open palm + forward
|
||||
offset, face subdivision prototype gated on the owner). The corrected face note is also in
|
||||
`docs/blender-assets.md`.
|
||||
`docs/assets/blender-assets.md`.
|
||||
|
||||
**Local map workstreams (H–M).** Build a local, data-backed map pipeline that can replace or
|
||||
supplement the stylized venue geometry with licensed OpenStreetMap footprints, 3D building
|
||||
@@ -402,7 +401,7 @@ still apply; the map pipeline has its own exit in M.
|
||||
- [x] ODbL audit: OpenStreetMap is used as **reference only** (hand-built geometry informed by
|
||||
OSM ways + Commons photos), so the shipped geometry is not an ODbL derived database and no
|
||||
share-alike obligation attaches. Attribution is still kept via the OSM way links in
|
||||
`docs/venues.md#hollywood-boulevard` / `docs/venues.md#the-joke-shop`. If derived OSM geometry ever
|
||||
`docs/design/venues.md#hollywood-boulevard` / `docs/design/venues.md#the-joke-shop`. If derived OSM geometry ever
|
||||
ships, it needs the attribution + share-alike review in a separate ADR.
|
||||
- [x] OSM extract workflow: no offline extract is required while OSM is reference-only. If the
|
||||
pipeline later imports footprints, pin an Overpass query + extract date and record it in a
|
||||
@@ -501,13 +500,13 @@ Nothing is committed until the licence gate on any promoted reference and the ma
|
||||
pass. The current `_build_comedy_store_building()` stays as the fallback.*
|
||||
|
||||
- [x] Extract the real proportions and reconcile: vision-read `tmp/research/comedy-store/` frames
|
||||
via `tools/describe_image.py` and recorded the reconciled table in `docs/venues.md#the-joke-shop`
|
||||
via `tools/describe_image.py` and recorded the reconciled table in `docs/design/venues.md#the-joke-shop`
|
||||
§Measured proportions. Key finding: the game facade is proportionally **taller** than the
|
||||
real (3.2:1 vs ~6:1) — the main shape-language deviation; canopy pitch, blade-sign diameter,
|
||||
entrance and roofline all match closely. Curtain-bay count is crop-dependent (3–7), so 7 is
|
||||
accepted as a readable stylization.
|
||||
- [x] Rank the shape-language gaps and write the top-five fix list (measurements from the
|
||||
proportions pass, §`docs/venues.md#the-joke-shop`):
|
||||
proportions pass, §`docs/design/venues.md#the-joke-shop`):
|
||||
1. **Facade height** — game 8.4 m vs real ~5.5–6 m (≈3.2:1 vs ~6:1 ratio). **Fixed
|
||||
2026-11-03:** `facade_height` lowered to 6.0 m; the wall now reads as a low single-storey
|
||||
hall with the canopy capping the top (vision-verified).
|
||||
@@ -533,8 +532,8 @@ pass. The current `_build_comedy_store_building()` stays as the fallback.*
|
||||
top-five list.
|
||||
- [x] Gates after the rebuild: Godot 277/277 (map budget 26,828 tris / 580 meshes under 150k/700;
|
||||
navigation/collider tests pass), `tools/check_screenshots.sh` 21 good / 0 bad; the three-up
|
||||
board and `docs/venues.md#the-joke-shop` were refreshed.
|
||||
- [ ] Update `docs/development-status.md`, `docs/asset-tooling.md` and `CHANGELOG.md` when the
|
||||
board and `docs/design/venues.md#the-joke-shop` were refreshed.
|
||||
- [ ] Update `docs/project/development-status.md`, `docs/assets/asset-tooling.md` and `CHANGELOG.md` when the
|
||||
rebuild lands; record any accepted deviations from the reference.
|
||||
|
||||
### L. Generated location imagery
|
||||
@@ -575,7 +574,7 @@ pass. The current `_build_comedy_store_building()` stays as the fallback.*
|
||||
### M. Local map QA and exit
|
||||
|
||||
- [x] Compare the block against screenshots/map docs and keep the stylized fallback: the three-up
|
||||
boards (photo | concept | capture) and `docs/venues.md#the-joke-shop` record the evidence chain;
|
||||
boards (photo | concept | capture) and `docs/design/venues.md#the-joke-shop` record the evidence chain;
|
||||
the procedural `_build_comedy_store_building()` remains the fallback.
|
||||
- [x] Budget/navigation/collider + day/night captures: Godot 277/277 (Joke Shop 26,828 tris /
|
||||
580 meshes under 150k/700; navmesh, step collider and prop-collider tests pass),
|
||||
@@ -583,8 +582,8 @@ pass. The current `_build_comedy_store_building()` stays as the fallback.*
|
||||
- [x] Gallery + before/after: the Joke Shop day gallery frame and three-up board were recaptured
|
||||
after each facade change; the photo/concept/capture strip is the before/after record.
|
||||
- [x] `tools/check_screenshots.sh` re-run (21/0) and the Joke Shop three-up board refreshed.
|
||||
- [x] Docs: `docs/venues.md#the-joke-shop` (mapping, measured proportions, simplifications),
|
||||
`docs/asset-tooling.md` (`describe_image.py`) and `docs/development-status.md` updated.
|
||||
- [x] Docs: `docs/design/venues.md#the-joke-shop` (mapping, measured proportions, simplifications),
|
||||
`docs/assets/asset-tooling.md` (`describe_image.py`) and `docs/project/development-status.md` updated.
|
||||
`CHANGELOG.md` is untouched (unversioned track; no release).
|
||||
- [x] Exit: **one local block (the Comedy Store) is reconstructed with reference-derived facades
|
||||
and massing** — 6.0 m low hall, white signature fascia, tied-back curtains, hotel tower —
|
||||
@@ -776,7 +775,7 @@ regressing gear fit, budget or readability.
|
||||
FBX artefacts (per-file armatures, `_end`/`neutral_bone`, node transforms, the shared
|
||||
jacket/trouser fabric, seam degenerates). `Suit.glb` is the first base: `npc_coat` is now a
|
||||
dark formal suit instead of a tinted hoodie. The pitfalls are recorded in
|
||||
`docs/npc-model-sourcing.md` and `MEMORY.md`.
|
||||
`docs/assets/npc-model-sourcing.md` and `MEMORY.md`.
|
||||
- [x] **Outfit families rolled out.** Seven more bases intaken (Adventurer, Beach, Casual_2,
|
||||
Farmer, King, Punk, Suit) with a slot map each: the roster now runs **eleven distinct outfits
|
||||
across twelve roles**. `patch_slots` buries a hidden triangle for slots a family cannot paint
|
||||
@@ -833,8 +832,8 @@ accepted on 2026-11-06; the review page and its sheets were then retired.
|
||||
quads became the light sclera and a shrunken copy pushed along the sclera's own normal became
|
||||
the dark pupil (`_add_quaternius_eye_whites()`). Two extra draw calls per head, no new UV work.
|
||||
- [x] Review page re-created for the second pass, then retired after the owner accepted the roster
|
||||
(2026-11-06). The durable evidence is `docs/3d-model-review.md`, the measurements in
|
||||
`docs/blender-assets.md`, and the `capture_npc_gear.gd` / `capture_npc_baseline.gd` scripts.
|
||||
(2026-11-06). The durable evidence is `docs/assets/3d-model-review.md`, the measurements in
|
||||
`docs/assets/blender-assets.md`, and the `capture_npc_gear.gd` / `capture_npc_baseline.gd` scripts.
|
||||
- [-] Arm/torso intersection on `npc_dress`/`npc_jacket`/`npc_crowd_a`/`npc_crowd_d`: the baked
|
||||
rest now aims the upper arm 7° out from vertical. Verified clear on the `casual` base; a
|
||||
light clip remains on `worker`, so this needs either a wider angle or a per-base shoulder
|
||||
@@ -871,7 +870,7 @@ contract.
|
||||
It now reports grip drop, the lowest point at rest against the Quaternius wrist (y 1.017), the
|
||||
hip-line flag (0.95), the authored size and `size_vs_head` — the proportion number that makes
|
||||
"reads oversized" measurable.
|
||||
- [x] Record the nine hand-item measurements (table in `docs/blender-assets.md`). Only the
|
||||
- [x] Record the nine hand-item measurements (table in `docs/assets/blender-assets.md`). Only the
|
||||
`clipboard` was actually mis-authored: its grip sat in the *middle* of the board, so it hung
|
||||
through the thigh line. It now grips the top edge like a carried clipboard (0.22 x 0.30 m).
|
||||
- [x] Re-author the `clipboard` (top-edge grip, 0.22 x 0.30 m) and rebuild + re-bake AO. The
|
||||
@@ -885,7 +884,7 @@ contract.
|
||||
- [x] Retire the gear GLBs the roster no longer uses: `cap` and `hood` are gone from `GEAR`, the
|
||||
manifest and the asset tree (`beanie` was already retired). The builder branches stay for a
|
||||
future design, guarded by a comment.
|
||||
- [x] `docs/blender-assets.md` documents the 15-piece matrix and the hand-item fit table;
|
||||
- [x] `docs/assets/blender-assets.md` documents the 15-piece matrix and the hand-item fit table;
|
||||
`architecture.md`, `asset-tooling.md` and the preview index were updated with the new counts.
|
||||
`CREDITS.md` still cites the upstream pack, which is unchanged.
|
||||
- [x] Owner feedback: the back gear hung at the waist. The `back` attach moved from y 1.10 to
|
||||
@@ -923,7 +922,7 @@ is signed off.
|
||||
- [ ] Re-run the 24-NPC budget smoke and the Web/Compatibility capture; record frame time,
|
||||
mesh/triangle counts and Web load before/after.
|
||||
- [ ] Retire the procedural variants that are no longer used, keeping one tested fallback; update
|
||||
`docs/development-status.md`, `docs/3d-model-review.md`, `docs/blender-previews` sheets and
|
||||
`docs/project/development-status.md`, `docs/assets/3d-model-review.md`, `docs/blender-previews` sheets and
|
||||
the README character row.
|
||||
- [ ] Release `0.9.10` with the full procedure (version, changelog, local build, checksums, tag).
|
||||
- [ ] Shrink the release artifacts: `assets/` alone is ~273 MB in the Linux binary. Excluding
|
||||
@@ -1026,7 +1025,7 @@ only release-blocking fixes and balance changes may land here.
|
||||
### Balance and fairness
|
||||
|
||||
- [ ] Run the scripted venue sweeps across easy/normal/hard and all four phases using the
|
||||
`docs/release-qa.md#balance-acceptance` targets; tune event weights, reaction tables,
|
||||
`docs/process/release-qa.md#balance-acceptance` targets; tune event weights, reaction tables,
|
||||
compliance and report strictness where targets fail.
|
||||
- [ ] Review emergency calls against independent behaviour labels, not `_read_npc_truth()` as its
|
||||
own oracle; no routine behaviour may make emergency the dominant winning move.
|
||||
@@ -1052,8 +1051,8 @@ only release-blocking fixes and balance changes may land here.
|
||||
|
||||
### Documentation and visual sign-off
|
||||
|
||||
- [ ] Update `README.md`, `PLAN.md`, `docs/architecture.md`, the ADRs, `docs/development-status.md`,
|
||||
`docs/getting-started.md`, `docs/release-qa.md`, `CHANGELOG.md` and this roadmap.
|
||||
- [ ] Update `README.md`, `PLAN.md`, `docs/project/architecture.md`, the ADRs, `docs/project/development-status.md`,
|
||||
`docs/process/getting-started.md`, `docs/process/release-qa.md`, `CHANGELOG.md` and this roadmap.
|
||||
- [ ] Regenerate the gallery and realism baselines from the release-candidate build, not the dev
|
||||
tree; verify every README/docs image resolves from the tagged build.
|
||||
- [ ] Run the manual smoke checklist on every target and link the evidence.
|
||||
@@ -1225,7 +1224,7 @@ Goal: publish the first stable release with a documented compatibility promise.
|
||||
- [ ] Confirm legal, privacy, rating and storefront approval is complete in writing.
|
||||
- [ ] Confirm the hardware matrix, accessibility audit and localization sign-off are complete.
|
||||
- [ ] Confirm no P0/P1 defects remain and every P2 is a documented known limitation.
|
||||
- [ ] Update `README.md`, `PLAN.md`, `docs/development-status.md`, `CHANGELOG.md`, `CREDITS.md`,
|
||||
- [ ] Update `README.md`, `PLAN.md`, `docs/project/development-status.md`, `CHANGELOG.md`, `CREDITS.md`,
|
||||
`PRIVACY.md` and the release notes for 1.0.0.
|
||||
- [ ] Run the full release procedure: version 1.0.0, changelog, clean build, checksum
|
||||
verification, tag, push and publish.
|
||||
|
||||
@@ -21,7 +21,7 @@ Reproducing the shipped characters:
|
||||
flatpak run org.blender.Blender --background \
|
||||
--python "$PWD/tools/blender_assets.py" -- build --only npc
|
||||
|
||||
Upstream quirks the build compensates for (see `docs/npc-model-sourcing.md`):
|
||||
Upstream quirks the build compensates for (see `docs/assets/npc-model-sourcing.md`):
|
||||
|
||||
1. every mesh ships a **degenerate UV map** (all loops at `0,0`) with flat-colour
|
||||
materials, so the build Smart-UV-unwraps and repacks before export;
|
||||
|
||||
+31
-30
@@ -1,42 +1,43 @@
|
||||
# Gig Line Documentation
|
||||
|
||||
This folder holds the project documentation, visual references and generated QA evidence.
|
||||
Documentation is grouped by category. Product intent, the gap analysis and the release roadmap
|
||||
live in [`../PLAN.md`](../PLAN.md); the executable task list is [`../TODO.md`](../TODO.md); the
|
||||
workflow rules are in [`../AGENTS.md`](../AGENTS.md).
|
||||
|
||||
## Current priorities
|
||||
## Categories
|
||||
|
||||
1. [Quaternius NPC base migration](../TODO.md#quaternius-npc-base-migration-top-priority) — CC0 Quaternius mesh/animation source baked to the 24,000-budget runtime contract.
|
||||
2. [3D model and local map improvements](../TODO.md#3d-model-and-local-map-re-evaluation) — asset re-evaluation and local map reconstruction.
|
||||
3. [0.10.0 release candidate](../TODO.md#milestone-0100--3d-model-and-map-improvements-minor) — versioned release hardening after the unversioned development tracks.
|
||||
| Folder | Contents |
|
||||
| --- | --- |
|
||||
| [`project/`](project/README.md) | Architecture (arc42) and the implemented-features status |
|
||||
| [`design/`](design/README.md) | Gameplay, venues, UI copy, accessibility and known limitations |
|
||||
| [`assets/`](assets/README.md) | Blender library, asset tooling, NPC sourcing and the 3D model review |
|
||||
| [`process/`](process/README.md) | Setup/controls, release QA and the release runbook |
|
||||
| [`adr/`](adr/README.md) | Architecture Decision Records |
|
||||
| [`screens/`](screens/README.md) | Licensed references, concepts and screen designs |
|
||||
| [`blender_previews/`](blender_previews/README.md) | Committed character/gear/prop preview sheets |
|
||||
| [`screenshots/`](screenshots/README.md) | The committed in-game gallery |
|
||||
|
||||
## Start here
|
||||
|
||||
- [`../PLAN.md`](../PLAN.md) — product, design intent and development priorities
|
||||
- [`../TODO.md`](../TODO.md) — priority-ordered active tasks and roadmap
|
||||
- [`npc-model-sourcing.md`](npc-model-sourcing.md) — character-source evaluation, licence rules and the character-development plan
|
||||
- [`makehuman-head-review.md`](makehuman-head-review.md) — retained MakeHuman fallback head, provenance and review verdict
|
||||
- [`architecture.md`](architecture.md) — arc42 system architecture
|
||||
- [`getting-started.md`](getting-started.md) — setup, run/test commands and controls
|
||||
- [`asset-tooling.md`](asset-tooling.md) — image/model pipelines and screenshot gates
|
||||
- [`../tools/README.md`](../tools/README.md) — tool inventory, categories and test runner
|
||||
- [`gameplay.md`](gameplay.md) — controls, venues and escalation
|
||||
- [`venues.md`](venues.md) — Hollywood, Joke Shop and TV Studio real-site mapping
|
||||
- [`3d-model-review.md`](3d-model-review.md) — 3D model re-evaluation: measurements, scorecard and ranked gaps
|
||||
- [`development-status.md`](development-status.md) — implemented features, current gaps and active planning
|
||||
- [`accessibility.md`](accessibility.md) — accessibility statement and known gaps
|
||||
- [`known-limitations.md`](known-limitations.md) — release-candidate blockers and accepted limits
|
||||
- [`release-qa.md`](release-qa.md) — manual smoke checklist and balance-acceptance protocol
|
||||
- [`../CREDITS.md`](../CREDITS.md) — credits and asset provenance
|
||||
- [`../PRIVACY.md`](../PRIVACY.md) — privacy note
|
||||
- [`ui-copy.md`](ui-copy.md) — screen, copy and button inventory
|
||||
- [`RELEASING.md`](RELEASING.md) — export, CI and publishing workflow
|
||||
- [`adr/README.md`](adr/README.md) — architecture decisions
|
||||
- [`../PLAN.md`](../PLAN.md) — product, design pillars, gap analysis and the roadmap to 1.0.0
|
||||
- [`../TODO.md`](../TODO.md) — milestone-ordered active tasks
|
||||
- [`project/architecture.md`](project/architecture.md) — system architecture and ownership
|
||||
- [`project/development-status.md`](project/development-status.md) — what the build supports now
|
||||
- [`design/gameplay.md`](design/gameplay.md) — the playable loop and escalation model
|
||||
- [`design/venues.md`](design/venues.md) — venue mapping and real-site evidence
|
||||
- [`assets/npc-model-sourcing.md`](assets/npc-model-sourcing.md) — the active NPC base and licence
|
||||
rules
|
||||
- [`assets/3d-model-review.md`](assets/3d-model-review.md) — asset measurements and scorecard
|
||||
- [`process/getting-started.md`](process/getting-started.md) — setup, run/test and controls
|
||||
- [`../tools/README.md`](../tools/README.md) — tool inventory and test runner
|
||||
- [`../CREDITS.md`](../CREDITS.md) — credits, AI/reference provenance and licensing
|
||||
- [`../PRIVACY.md`](../PRIVACY.md) — local-only data and save files
|
||||
|
||||
## Visual references
|
||||
## Current work
|
||||
|
||||
- [`screens/README.md`](screens/README.md) — concepts, designs, screenshots and realism runs
|
||||
- [`blender_previews/README.md`](blender_previews/README.md) — character/gear/prop previews
|
||||
- [`screenshots/README.md`](screenshots/README.md) — committed game gallery
|
||||
- [`ui-copy.md`](ui-copy.md#screen-design-judge-report) — screen/button inventory and latest judge result
|
||||
v0.9.9 shipped the Quaternius NPC roster. The active patch line is `0.9.10` (roster follow-ups:
|
||||
outfit families, the Swat base orientation, per-slot atlases) through `0.9.12`, followed by the
|
||||
`0.10.0` public-readiness minor. See [`../TODO.md`](../TODO.md) for the live checklist.
|
||||
|
||||
## Quick preview
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ A review compared free/open-source sources against that contract. Quaternius
|
||||
Ultimate Modular (CC0), Kenney Blocky Characters (CC0), Khronos CesiumMan and
|
||||
RiggedFigure (CC BY 4.0) and the MakeHuman base mesh (CC0) were imported and
|
||||
measured. None was a drop-in; the full results are in
|
||||
[`docs/npc-model-sourcing.md`](../npc-model-sourcing.md).
|
||||
[`docs/assets/npc-model-sourcing.md`](../assets/npc-model-sourcing.md).
|
||||
|
||||
## Decision
|
||||
|
||||
@@ -86,4 +86,4 @@ measured. None was a drop-in; the full results are in
|
||||
- MakeHuman is now an active local development pipeline (body retarget plus project-owned
|
||||
head/hands), while the procedural library remains the shipped path and CI fallback.
|
||||
- Blender MCP is optional interactive tooling only; it is not a build, CI, test or runtime
|
||||
dependency. Setup is in [`docs/asset-tooling.md#optional-interactive-blender-mcp`](../asset-tooling.md#optional-interactive-blender-mcp).
|
||||
dependency. Setup is in [`docs/assets/asset-tooling.md#optional-interactive-blender-mcp`](../assets/asset-tooling.md#optional-interactive-blender-mcp).
|
||||
@@ -16,7 +16,7 @@ The CC0 **Quaternius Ultimate Modular Characters** pack already provides a
|
||||
coherent low-poly human silhouette, 21 modular outfits and 24 animation clips.
|
||||
The researched GLBs (`Casual`, `Casual_Hoodie`, `Worker`) measure 4 meshes, 62
|
||||
joints and 24 clips each. The owner directed that Quaternius become the NPC
|
||||
base. The full evaluation is in [`docs/npc-model-sourcing.md`](../npc-model-sourcing.md).
|
||||
base. The full evaluation is in [`docs/assets/npc-model-sourcing.md`](../assets/npc-model-sourcing.md).
|
||||
|
||||
## Decision
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ ADR-0017 made Quaternius the NPC base and staged the migration: Stage 1 bakes a
|
||||
proportion-warped mesh onto the existing 13-core contract; Stage 2 adopts the
|
||||
62-joint rig at runtime only if the warp fails.
|
||||
|
||||
The Stage 1 proportion warp was executed and measured (`docs/npc-model-sourcing.md`
|
||||
The Stage 1 proportion warp was executed and measured (`docs/assets/npc-model-sourcing.md`
|
||||
§Rest-pose and proportion-warp measurement). The arm-down rest pose bakes cleanly, but the
|
||||
warp to the contract proportions does not:
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# 3D model review (2026-11-03)
|
||||
|
||||
Status: **baseline measured; scorecard open.** This is the working document for the unversioned
|
||||
`3D model re-evaluation` track in [`TODO.md`](../TODO.md). It records what was measured, what the
|
||||
`3D model re-evaluation` track in [`TODO.md`](../../TODO.md). It records what was measured, what the
|
||||
Blender skill guidance says the targets are, the ranked candidate gaps, and the decisions that
|
||||
still need the project owner. Nothing here re-opens the accepted 0.9.4 limits by itself.
|
||||
|
||||
@@ -88,7 +88,7 @@ Readings:
|
||||
Recorded for the character baseline before the Quaternius migration. `npc_base.blend` is the
|
||||
frozen fallback; the 12 characters are currently assembled procedurally by
|
||||
`tools/blender_assets.py`. The active plan is now the CC0 Quaternius base bake
|
||||
([ADR-0017](adr/0017-quaternius-npc-base.md)); this section and the MakeHuman notes below are the
|
||||
([ADR-0017](../adr/0017-quaternius-npc-base.md)); this section and the MakeHuman notes below are the
|
||||
pre-migration record. The MPFB/MakeHuman development files were removed from `tmp/` after the
|
||||
2026-11-05 pivot.
|
||||
|
||||
@@ -283,7 +283,7 @@ front/three-quarter/profile and judged side by side:
|
||||
The chosen s48 is the `head_proto` default; the rejected s24/s64 stay local under
|
||||
`tmp/npc-parts/`. A before/after sign-off sheet (current `_face` vs s48, 1.85 m
|
||||
front/three-quarter/profile) is
|
||||
[`blender_previews/sheet_head_proto_before_after.jpg`](blender_previews/sheet_head_proto_before_after.jpg).
|
||||
[`blender_previews/sheet_head_proto_before_after.jpg`](../blender_previews/sheet_head_proto_before_after.jpg).
|
||||
|
||||
## Foliage language P1 — resolved 2026-11-06
|
||||
|
||||
@@ -517,6 +517,6 @@ and the full carded-cluster foliage pass is the one remaining owner-gated P1. No
|
||||
- Review the assembled [`makehuman-head-review.md`](makehuman-head-review.md) prototype (hair cap and full-body silhouette) before rebuilding the 12 shipped character GLBs.
|
||||
|
||||
|
||||
Tracked in [`TODO.md`](../TODO.md) `3D model re-evaluation`: the remaining `A. Baseline…` item is
|
||||
Tracked in [`TODO.md`](../../TODO.md) `3D model re-evaluation`: the remaining `A. Baseline…` item is
|
||||
this owner review; `B`/`C`/`D` carry the per-family work, and `E` adds the pose/weight,
|
||||
collider-coverage and scorecard-coverage gates this document found missing.
|
||||
@@ -0,0 +1,19 @@
|
||||
# Asset Documentation
|
||||
|
||||
Asset contracts, pipelines, sourcing and reviews. These pages own the measured evidence; the
|
||||
executable gates are `tools/blender_assets.py inspect|audit|fit`, `tools/npc_proportions.py` and
|
||||
the capture scripts.
|
||||
|
||||
- [`blender-assets.md`](blender-assets.md) — Blender library operation, the character/gear/prop
|
||||
contract, attach points and rebuild discipline.
|
||||
- [`asset-tooling.md`](asset-tooling.md) — image/model pipelines, the optional Blender MCP setup
|
||||
and the screenshot/vision gates.
|
||||
- [`npc-model-sourcing.md`](npc-model-sourcing.md) — character-source evaluation, licence rules,
|
||||
the Quaternius intake and the active NPC plan.
|
||||
- [`3d-model-review.md`](3d-model-review.md) — measurements, per-asset scorecard, ranked gaps and
|
||||
accepted limits.
|
||||
- [`makehuman-head-review.md`](makehuman-head-review.md) — the retained MakeHuman fallback head,
|
||||
its provenance and the review verdict.
|
||||
|
||||
Up: [`../README.md`](../README.md) · Product plan: [`../../PLAN.md`](../../PLAN.md) · Tasks:
|
||||
[`../../TODO.md`](../../TODO.md).
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
Everything the game renders is produced or gated by the scripts below. Architecture-level contracts,
|
||||
data flow and failure fallbacks are summarized in
|
||||
[`architecture.md`](architecture.md#content-and-asset-pipeline-architecture); this page is the
|
||||
[`architecture.md`](../project/architecture.md#content-and-asset-pipeline-architecture); this page is the
|
||||
operational reference. Development-only outputs (AI concept sheets, Blender sources, raw AI fabrics)
|
||||
are gitignored; the audited game assets are committed.
|
||||
|
||||
@@ -72,7 +72,7 @@ colours onto material roles (darkest → metal, warm saturated → wood, light g
|
||||
stone, green → foliage). glTF stores colours in linear space, so the tool converts
|
||||
the sRGB palettes before writing them. Re-run `build` and `godot --headless
|
||||
--path . --import` after changing a prop. See
|
||||
[ADR-0012](adr/0012-surface-materials-and-generated-props.md).
|
||||
[ADR-0012](../adr/0012-surface-materials-and-generated-props.md).
|
||||
|
||||
Surface materials share one definition in `src/game/materials.gd`: named
|
||||
roughness/metallic profiles per surface, plus the environment tune-up (ACES
|
||||
@@ -81,14 +81,14 @@ tonemapping, glow, fog, colour grading) that the phase lighting applies.
|
||||
## NPC character model
|
||||
|
||||
NPCs are moving from the procedural capsule rig to a skinned, UV-mapped base
|
||||
character authored in Blender ([ADR-0013](adr/0013-blender-authored-npc-characters.md)).
|
||||
character authored in Blender ([ADR-0013](../adr/0013-blender-authored-npc-characters.md)).
|
||||
The active base is the CC0 Quaternius modular character, baked to the runtime contract
|
||||
([ADR-0017](adr/0017-quaternius-npc-base.md)).
|
||||
([ADR-0017](../adr/0017-quaternius-npc-base.md)).
|
||||
`tools/npc_pipeline.py` builds `assets/models/generated/npc_base.glb` plus the
|
||||
per-slot material maps. `NpcAvatar` instantiates that skinned model, tints its
|
||||
five material slots from the seed-driven outfit, and drives the bones from the
|
||||
existing animation code; the procedural rig remains the offline fallback (see
|
||||
[ADR-0013](adr/0013-blender-authored-npc-characters.md) and
|
||||
[ADR-0013](../adr/0013-blender-authored-npc-characters.md) and
|
||||
[`blender-assets.md`](blender-assets.md)).
|
||||
|
||||
```bash
|
||||
@@ -138,7 +138,7 @@ the fallback. Kenney/Khronos/MakeHuman remain evaluated references, not active b
|
||||
|
||||
| Characters | Props |
|
||||
| --- | --- |
|
||||
|  |  |
|
||||
|  |  |
|
||||
|
||||
```bash
|
||||
flatpak run org.blender.Blender --background --python "$PWD/tools/blender_assets.py" -- build
|
||||
@@ -246,7 +246,7 @@ gate as `--reference` on `generate`.
|
||||
`tools/refcollect.py` downloads images from DuckDuckGo image search into `tmp/research/<slug>/` for
|
||||
development reference only. It applies **no licence gate** (rows are marked `local_only` /
|
||||
`unchecked-local`); everything it fetches must never be committed or promoted into
|
||||
[`screens/refs/`](screens/refs/README.md) without the normal sidecar licence + privacy gate. This
|
||||
[`screens/refs/`](../screens/refs/README.md) without the normal sidecar licence + privacy gate. This
|
||||
is the owner-authorised local-only override (TODO.md §3D model re-evaluation → A).
|
||||
|
||||
```bash
|
||||
@@ -265,7 +265,7 @@ string); the UA alone is no longer enough to look like a browser.
|
||||
### Reference-board research (`refboard`)
|
||||
|
||||
`tools/refboard.py` searches, fetches and documents Wikimedia Commons photos of a real location for
|
||||
the [`screens/refs/`](screens/refs/README.md) boards. It is stdlib-only and never commits anything
|
||||
the [`screens/refs/`](../screens/refs/README.md) boards. It is stdlib-only and never commits anything
|
||||
itself: downloads land in `tmp/`, and moving a file into a board folder is a deliberate manual step
|
||||
that goes through the sidecar licence gate.
|
||||
|
||||
@@ -322,10 +322,10 @@ their SHA-256 in `CREDITS.md`.
|
||||
|
||||
## Local map development (planned)
|
||||
|
||||
The local map workstreams (H–M) in [`TODO.md`](../TODO.md#3d-model-re-evaluation) are
|
||||
The local map workstreams (H–M) in [`TODO.md`](../../TODO.md#3d-model-and-local-map-re-evaluation) are
|
||||
planned, not implemented; there are no map-generation commands yet. The runtime
|
||||
contract, provenance rules, budget/navigation gates and fallback are in
|
||||
[`architecture.md#venue-implementation-contract`](architecture.md#venue-implementation-contract).
|
||||
[`architecture.md#venue-implementation-contract`](../project/architecture.md#venue-implementation-contract).
|
||||
The detailed pipeline/task list lives in `TODO.md`.
|
||||
|
||||
## Confirmed game assets
|
||||
@@ -335,9 +335,9 @@ Everything below is audited and shipped in the game; development-only outputs
|
||||
|
||||
| | |
|
||||
| --- | --- |
|
||||
|  |  |
|
||||
|  |  |
|
||||
|  |  |
|
||||
|  |  |
|
||||
|  |  |
|
||||
|  |  |
|
||||
|
||||
- **Surface textures:** the v2 picks above (brick, sidewalk pavers, dry and wet asphalt, awning canvas) plus their normal maps, loaded by `src/game/materials.gd` and `WorldBuilder`; the three skyline panoramas are switched per shift phase. The first-generation tiles and `assets/textures/skyline.png` are no longer loaded.
|
||||
- **UI art:** `assets/textures/ai/game_ready/icons/` (flashlight, door lock, wand, REC) and `assets/textures/ai/game_ready/cards/` (ID, wristband, ticket, credential, guest list), loaded by `src/game/ui/hud.gd`.
|
||||
@@ -511,7 +511,7 @@ remain optional interactive exploration; the headless commands stay the build an
|
||||
## Realism pass: scene concepts, skylines and textures
|
||||
|
||||
The skyline, surface tiles and phase lighting were rebuilt against AI concept frames. The
|
||||
concepts live in [`docs/screens/concepts/`](../docs/screens/concepts/README.md); the validated
|
||||
concepts live in [`docs/screens/concepts/`](../screens/concepts/README.md); the validated
|
||||
picks the game loads are in `assets/textures/ai/game_ready/v2/picks/` (day/dusk/night
|
||||
panoramas, brick, sidewalk pavers, dry and wet asphalt, awning canvas, each with a normal
|
||||
map).
|
||||
@@ -633,7 +633,7 @@ texture detail 1.2, backdrop 2.0 and characters 1.2; the Pillow metric gap was
|
||||
particularly lit night facades and dense backdrop detail. That is expected: the
|
||||
pass validated close-range surfaces and promoted the texture repairs, not a
|
||||
photoreal renderer. The 0.9.5 before/after close-up sheet is
|
||||
[`blender_previews/sheet_texture_refinement_0.9.5.jpg`](blender_previews/sheet_texture_refinement_0.9.5.jpg);
|
||||
[`blender_previews/sheet_texture_refinement_0.9.5.jpg`](../blender_previews/sheet_texture_refinement_0.9.5.jpg);
|
||||
the texture-adoption run itself was the earlier 0.8-style candidate comparison,
|
||||
and its report remains local/gitignored.
|
||||
|
||||
@@ -1,21 +1,21 @@
|
||||
# Blender asset library
|
||||
|
||||
Architecture context: the asset contracts and fallback path are summarized in
|
||||
[`architecture.md`](architecture.md#content-and-asset-pipeline-architecture).
|
||||
[`architecture.md`](../project/architecture.md#content-and-asset-pipeline-architecture).
|
||||
|
||||
Status: built, audited, and integrated (2026-11-01). The active character migration
|
||||
replaces the procedural body with a baked CC0 Quaternius base
|
||||
([ADR-0017](adr/0017-quaternius-npc-base.md)); the current library remains the shipped
|
||||
([ADR-0017](../adr/0017-quaternius-npc-base.md)); the current library remains the shipped
|
||||
fallback until the Quaternius 12-variant baseline passes review. `NpcAvatar` selects the
|
||||
character variants and attaches the gear; `WorldBuilder` loads the prop library
|
||||
with colliders and phase-driven emissives. The 0.9.4 neutral baseline and its
|
||||
acceptance criteria are in [`architecture.md`](architecture.md#character-and-gear-asset-contract);
|
||||
acceptance criteria are in [`architecture.md`](../project/architecture.md#character-and-gear-asset-contract);
|
||||
the committed 8 × 6 contact sheet is
|
||||
[`blender_previews/sheet_npc_baseline.jpg`](blender_previews/sheet_npc_baseline.jpg).
|
||||
[`blender_previews/sheet_npc_baseline.jpg`](../blender_previews/sheet_npc_baseline.jpg).
|
||||
|
||||
Generator: [`tools/blender_assets.py`](../tools/blender_assets.py). Manifest (the
|
||||
Generator: [`tools/blender_assets.py`](../../tools/blender_assets.py). Manifest (the
|
||||
source of truth for integration):
|
||||
[`assets/models/blender/manifest.json`](../assets/models/blender/manifest.json).
|
||||
[`assets/models/blender/manifest.json`](../../assets/models/blender/manifest.json).
|
||||
|
||||
## Art direction
|
||||
|
||||
@@ -143,7 +143,7 @@ render about 2.5 min.
|
||||
## Characters
|
||||
|
||||
All library variants share the
|
||||
[character and gear asset contract](architecture.md#character-and-gear-asset-contract):
|
||||
[character and gear asset contract](../project/architecture.md#character-and-gear-asset-contract):
|
||||
`npc_base` mesh node, five tint slots, +Z visual front, 24,000/24,000 character budget and the
|
||||
same 256² slot-map/AO rules. The shipped roster is on the 62-joint Quaternius skeleton
|
||||
(ADR-0018); the procedural fallback built by `build --source procedural` keeps the 13 core bones.
|
||||
@@ -201,7 +201,7 @@ the role's `TYPE_COLORS`.
|
||||
## Gear attach points
|
||||
|
||||
Gear is authored in attach-point space; the exact contract and runtime fit offsets are in
|
||||
[`architecture.md#character-and-gear-asset-contract`](architecture.md#character-and-gear-asset-contract).
|
||||
[`architecture.md#character-and-gear-asset-contract`](../project/architecture.md#character-and-gear-asset-contract).
|
||||
|
||||
The shipped matrix is **fifteen pieces** since the hat removal (owner, 2026-11-06): `cap` and
|
||||
`hood` are retired, and `firefighter_helmet` is the only head item.
|
||||
@@ -278,7 +278,7 @@ carry baked AO and the shared neutral material maps described above.
|
||||
`npc_base`, the bones accept `NpcAvatar`'s pose composition, and props are
|
||||
grounded.
|
||||
- `tools/test_model_review.py`: every `CHARACTERS`/`GEAR`/`PROPS` entry has a
|
||||
scorecard row and verdict in `docs/3d-model-review.md` (coverage gate).
|
||||
scorecard row and verdict in `docs/assets/3d-model-review.md` (coverage gate).
|
||||
- `src/test/tests/test_world.gd`: every library prop that blocks walking has a
|
||||
`StaticBody3D` + `NavigationObstacle3D`, checked against the catalogue
|
||||
(collider/proxy gate).
|
||||
@@ -10,8 +10,8 @@ base. The development source files were removed from `tmp/` on 2026-11-05.
|
||||
|
||||
## Asset
|
||||
|
||||
- GLB: [`assets/models/blender_src/makehuman_head.glb`](../assets/models/blender_src/makehuman_head.glb)
|
||||
- Review sheet: [`blender_previews/sheet_makehuman_head.jpg`](blender_previews/sheet_makehuman_head.jpg)
|
||||
- GLB: [`assets/models/blender_src/makehuman_head.glb`](../../assets/models/blender_src/makehuman_head.glb)
|
||||
- Review sheet: [`blender_previews/sheet_makehuman_head.jpg`](../blender_previews/sheet_makehuman_head.jpg)
|
||||
- Source workflow (development-only, files removed after the Quaternius pivot;
|
||||
retained here as the historical method) — extracts the MakeHuman head, cuts it at the neck, keeps the head/eye/mouth
|
||||
components, cuts an almond aperture through a skin eyelid mask, adds recessed
|
||||
@@ -26,7 +26,7 @@ base. The development source files were removed from `tmp/` on 2026-11-05.
|
||||
- Materials used: `skin`, `eye_white`, `iris`, `pupil`, `hair`. No textures are
|
||||
baked into this prototype.
|
||||
|
||||
|
||||
|
||||
|
||||
## What was done
|
||||
|
||||
@@ -54,7 +54,7 @@ base. The development source files were removed from `tmp/` on 2026-11-05.
|
||||
|
||||
- Base mesh: MakeHuman / MPFB base, CC0, from the local research set
|
||||
(development source files removed after the 2026-11-05 Quaternius pivot); see
|
||||
[`CREDITS.md`](../CREDITS.md).
|
||||
[`CREDITS.md`](../../CREDITS.md).
|
||||
- The head is a **derived prototype**, not a shipped NPC. It does not enter
|
||||
`assets/models/blender/npc/`, `npc_base`, the runtime `NpcAvatar` path, CI, or
|
||||
a release package. It is retained as a fallback, not the active NPC base.
|
||||
@@ -1,8 +1,8 @@
|
||||
# NPC Model Sourcing
|
||||
|
||||
This page records the source evaluation and the active character plan. The
|
||||
decision is [ADR-0017](adr/0017-quaternius-npc-base.md), which supersedes the
|
||||
generator-first sourcing decision in [ADR-0015](adr/0015-npc-model-variety-sourcing.md).
|
||||
decision is [ADR-0017](../adr/0017-quaternius-npc-base.md), which supersedes the
|
||||
generator-first sourcing decision in [ADR-0015](../adr/0015-npc-model-variety-sourcing.md).
|
||||
|
||||
## Active direction
|
||||
|
||||
@@ -198,7 +198,7 @@ deltoid + hand) — both are the gate's rejection conditions.
|
||||
contract proportions; the gate fails and Stage 2 (a 62-joint runtime ADR) is indicated. Do not
|
||||
start the 12-variant rebuild on the warped base.
|
||||
|
||||
[ADR-0018](adr/0018-quaternius-stage2-runtime-rig.md) records the Stage 2 decision (accepted
|
||||
[ADR-0018](../adr/0018-quaternius-stage2-runtime-rig.md) records the Stage 2 decision (accepted
|
||||
2026-11-05, owner chose option 2): adopt the **Quaternius 62-joint rig at runtime**, keep the
|
||||
mesh at source LOD, re-derive gear attach points from the Quaternius skeleton, and use the
|
||||
Quaternius Idle/Walk clips directly (no retarget).
|
||||
@@ -237,7 +237,7 @@ Two source quirks shaped the bake:
|
||||
contract is applied as a rename, not a re-author.
|
||||
|
||||
The face/silhouette gate that chose the full swap is recorded in the follow-up decision of
|
||||
[ADR-0018](adr/0018-quaternius-stage2-runtime-rig.md); its comparison sheets were retired with the
|
||||
[ADR-0018](../adr/0018-quaternius-stage2-runtime-rig.md); its comparison sheets were retired with the
|
||||
review pages.
|
||||
|
||||
## Shipped roster (0.9.9, owner chose the full swap)
|
||||
@@ -354,7 +354,7 @@ not a local workaround.
|
||||
## Licence and provenance
|
||||
|
||||
- CC0 preferred. CC-BY is allowed only with attribution in
|
||||
[`CREDITS.md`](../CREDITS.md).
|
||||
[`CREDITS.md`](../../CREDITS.md).
|
||||
- No service asset whose terms restrict redistribution may be shipped.
|
||||
- Keep the source URL, author, licence, download date and SHA-256 in this page
|
||||
and in `CREDITS.md`.
|
||||
@@ -369,12 +369,12 @@ The MakeHuman/MPFB body pipeline is closed for the NPC base. The accepted
|
||||
MakeHuman head and the procedural `npc_base` remain tested fallbacks until the
|
||||
Quaternius rollout is complete. Their research scripts and renders were removed
|
||||
from `tmp/` after the pivot; the measurements and decisions remain in
|
||||
[`DONE.md`](../DONE.md), [`MEMORY.md`](../MEMORY.md) and the review docs.
|
||||
[`DONE.md`](../../DONE.md), [`MEMORY.md`](../../MEMORY.md) and the review docs.
|
||||
|
||||
## Related documents
|
||||
|
||||
- [ADR-0017: Quaternius NPC base](adr/0017-quaternius-npc-base.md)
|
||||
- [ADR-0016: 24,000-triangle character budget](adr/0016-npc-character-budget-24k.md)
|
||||
- [Blender asset contract](architecture.md#character-and-gear-asset-contract)
|
||||
- [ADR-0017: Quaternius NPC base](../adr/0017-quaternius-npc-base.md)
|
||||
- [ADR-0016: 24,000-triangle character budget](../adr/0016-npc-character-budget-24k.md)
|
||||
- [Blender asset contract](../project/architecture.md#character-and-gear-asset-contract)
|
||||
- [`3d-model-review.md`](3d-model-review.md)
|
||||
- [`asset-tooling.md`](asset-tooling.md)
|
||||
@@ -9,7 +9,7 @@ capture harnesses.
|
||||
| --- | --- |
|
||||
| [](sheet_npc.jpg) <br> `sheet_npc.jpg` | Eight skinned character variants (casual, jacket, coat, hi-vis vest, dress, hoodie, firefighter, guard) with their gear attach points. |
|
||||
| [](sheet_npc_baseline.jpg) <br> `sheet_npc_baseline.jpg` | Neutral studio baseline: 8 characters x front, three-quarter, profile, back, full body and crowd views. |
|
||||
| [](sheet_makehuman_head.jpg) <br> `sheet_makehuman_head.jpg` | MakeHuman head: front, three-quarter and profile review views. The owner accepted the basic head; the automated vision gate still rejects the eye/lid region as deferred polish. See [`../makehuman-head-review.md`](../makehuman-head-review.md). |
|
||||
| [](sheet_makehuman_head.jpg) <br> `sheet_makehuman_head.jpg` | MakeHuman head: front, three-quarter and profile review views. The owner accepted the basic head; the automated vision gate still rejects the eye/lid region as deferred polish. See [`../makehuman-head-review.md`](../assets/makehuman-head-review.md). |
|
||||
| [](sheet_npc_baseline_compare-body.jpg) <br> `sheet_npc_baseline_compare-body.jpg` | Neck/shoulder transition: fuller neck base and a lower shoulder root. |
|
||||
| [](sheet_npc_baseline_compare-face-detail.jpg) <br> `sheet_npc_baseline_compare-face-detail.jpg` | Face detail: nose ala wings, a single rounded mouth and a darker ear concha. |
|
||||
| [](sheet_npc_baseline_compare-face.jpg) <br> `sheet_npc_baseline_compare-face.jpg` | Face-depth pass: recessed sclera, upper lid and sculpted chin/cheek planes. |
|
||||
@@ -27,5 +27,5 @@ capture harnesses.
|
||||
| [](sheet_props.jpg) <br> `sheet_props.jpg` | Twenty street and venue props with baked maps, ground contact and collider footprints. |
|
||||
| [](sheet_texture_refinement_0.9.5.jpg) <br> `sheet_texture_refinement_0.9.5.jpg` | 0.9.5 texture refinement before/after: pavers, awning stripes and NPC fabric. |
|
||||
|
||||
The measurements are in [`../3d-model-review.md`](../3d-model-review.md) and the asset contract in
|
||||
[`../blender-assets.md`](../blender-assets.md).
|
||||
The measurements are in [`../3d-model-review.md`](../assets/3d-model-review.md) and the asset contract in
|
||||
[`../blender-assets.md`](../assets/blender-assets.md).
|
||||
@@ -0,0 +1,13 @@
|
||||
# Design Documentation
|
||||
|
||||
Gameplay, venues, presentation and player-facing constraints.
|
||||
|
||||
- [`gameplay.md`](gameplay.md) — the playable loop, escalation mechanics, venues and tutorial.
|
||||
- [`venues.md`](venues.md) — real-site evidence, game mapping and venue simplifications.
|
||||
- [`ui-copy.md`](ui-copy.md) — screen, copy and button inventory plus the screen-design judge
|
||||
record.
|
||||
- [`accessibility.md`](accessibility.md) — accessibility statement and known gaps.
|
||||
- [`known-limitations.md`](known-limitations.md) — release blockers and accepted limitations.
|
||||
|
||||
Up: [`../README.md`](../README.md) · Product plan: [`../../PLAN.md`](../../PLAN.md) · Tasks:
|
||||
[`../../TODO.md`](../../TODO.md).
|
||||
@@ -28,5 +28,5 @@ Known gaps:
|
||||
review is still a 0.10.0 release-review item.
|
||||
|
||||
Test evidence and the manual checklist live in
|
||||
[`release-qa.md`](release-qa.md#manual-smoke-checklist); settings and save behaviour are
|
||||
documented in [`getting-started.md`](getting-started.md).
|
||||
[`release-qa.md`](../process/release-qa.md#manual-smoke-checklist); settings and save behaviour are
|
||||
documented in [`getting-started.md`](../process/getting-started.md).
|
||||
@@ -1,6 +1,6 @@
|
||||
# Gameplay
|
||||
|
||||
The complete design rationale also lives in [`PLAN.md`](../PLAN.md); this page keeps the playable mechanics close to the README.
|
||||
The complete design rationale also lives in [`PLAN.md`](../../PLAN.md); this page keeps the playable mechanics close to the README.
|
||||
|
||||
## Game Overview
|
||||
|
||||
@@ -12,7 +12,7 @@ public release.
|
||||
observation.
|
||||
- **AI asset provenance:** the image-generation provider terms and commercial
|
||||
redistribution rights for the committed AI-assisted textures/UI art still need
|
||||
legal review. See [`../CREDITS.md`](../CREDITS.md).
|
||||
legal review. See [`../CREDITS.md`](../../CREDITS.md).
|
||||
- **Storefront/legal approval:** age/content rating, storefront policy, trademark
|
||||
language and the mental-health-crisis/body-camera representation have not been
|
||||
externally approved.
|
||||
@@ -31,7 +31,7 @@ public release.
|
||||
- Character faces, hands and fabric use a deliberately low-poly style; the
|
||||
>26 m tier remains a two-quad impostor and there is no separate finger-curl
|
||||
rig. The accepted limits are recorded in
|
||||
[`npc-model-sourcing.md`](npc-model-sourcing.md).
|
||||
[`npc-model-sourcing.md`](../assets/npc-model-sourcing.md).
|
||||
- There is no live 3D body-camera replay; the timeline is text-based.
|
||||
- There is no recorded voice/music track. Ambience and cues are procedural.
|
||||
- The game is English-only and does not yet have a translator workflow or
|
||||
@@ -1,6 +1,6 @@
|
||||
# UI copy and button inventory
|
||||
|
||||
Status: dialogue, button-state, focus, modal-close, font/layout, destructive-action and end-to-end passes complete; capture/smoke sign-off remains for 0.9.3.
|
||||
Status: complete (0.9.3). Retained as the screen/button inventory, copy audit and screen-design judge record.
|
||||
|
||||
## Screen inventory
|
||||
|
||||
@@ -236,9 +236,9 @@ Command: `python3 tools/screen_designs.py judge`
|
||||
Result: **21/21 match, 0 review, 0 diff**
|
||||
|
||||
The screenshot gallery was regenerated on the current build before judging, including the eight UI-state captures 14–21 added in `src/test/capture_ui_states.gd`.
|
||||
Accepted captures are in [`docs/screens/`](screens/README.md); the committed
|
||||
gallery is in [`docs/screenshots/`](screenshots/README.md).
|
||||
Accepted captures are in [`docs/screens/`](../screens/README.md); the committed
|
||||
gallery is in [`docs/screenshots/`](../screenshots/README.md).
|
||||
|
||||
The automatic model selection and retry/spend behavior is documented in
|
||||
[`docs/asset-tooling.md`](asset-tooling.md). This report intentionally records
|
||||
[`docs/assets/asset-tooling.md`](../assets/asset-tooling.md). This report intentionally records
|
||||
the outcome rather than generated captures, which remain local/gitignored.
|
||||
@@ -11,7 +11,7 @@ The game uses two physical Hollywood blocks across three playable venue rows:
|
||||
|
||||
The runtime implementation contract (facade specs, map budgets, navigation,
|
||||
colliders, phase behavior and fallback) lives in
|
||||
[`architecture.md`](architecture.md#venue-implementation-contract). This page
|
||||
[`architecture.md`](../project/architecture.md#venue-implementation-contract). This page
|
||||
keeps the real-site evidence, mapping decisions and deliberate simplifications.
|
||||
|
||||
## Hollywood Boulevard
|
||||
@@ -49,7 +49,7 @@ keeps the real-site evidence, mapping decisions and deliberate simplifications.
|
||||
| TV Studio arrival | same six-column facade/eight steps plus bulb canopy, sedan, handrail and barriers |
|
||||
|
||||
The generated references in
|
||||
[`screens/concepts/hollywood_boulevard/`](screens/concepts/hollywood_boulevard/README.md)
|
||||
[`screens/concepts/hollywood_boulevard/`](../screens/concepts/hollywood_boulevard/README.md)
|
||||
are art direction for lighting, material scale and composition; they are not
|
||||
texture or geometry sources.
|
||||
|
||||
@@ -128,9 +128,9 @@ The guard starts west of the entrance at (-4.8, 0.1, 1.4), facing the approach.
|
||||
- [Hollywood Masonic Temple facade — Wikimedia Commons](https://commons.wikimedia.org/wiki/File:El_Capitan_Theater_frontal_fachade-The_Masonic_Temple.jpg)
|
||||
- [Hollywood Masonic Temple and El Capitan Theatre, 2013 — Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Hollywood_Masonic_Temple_2013-10-13_10-02-25.jpg)
|
||||
- [Comedy Store — OpenStreetMap way 428854155](https://www.openstreetmap.org/way/428854155)
|
||||
- Committed photo boards: [`screens/refs/hollywood/`](screens/refs/hollywood/README.md),
|
||||
[`screens/refs/joke-shop/`](screens/refs/joke-shop/README.md); three-up boards
|
||||
are in [`screens/boards/`](screens/boards/README.md).
|
||||
- Committed photo board: [`screens/refs/hollywood/`](../screens/refs/hollywood/README.md);
|
||||
three-up boards are in [`screens/boards/`](../screens/boards/README.md). The Joke Shop has no
|
||||
committed photo board: its reference set stays local-only under `tmp/research/comedy-store/`.
|
||||
- Local-only research (never committed): `tmp/research/elcapitan-2026/`,
|
||||
`tmp/research/jimmy-kimmel-entrance/`, `tmp/research/comedy-store/` and
|
||||
`tmp/research/comedy-store-hillside/`. These are evidence for decisions, not
|
||||
@@ -0,0 +1,11 @@
|
||||
# Process Documentation
|
||||
|
||||
Setup, quality assurance and releasing.
|
||||
|
||||
- [`getting-started.md`](getting-started.md) — setup, run/test commands, controls and save data.
|
||||
- [`release-qa.md`](release-qa.md) — the manual smoke checklist and the balance-acceptance
|
||||
protocol.
|
||||
- [`RELEASING.md`](RELEASING.md) — export templates, release build, CI/publishing and rollback.
|
||||
|
||||
Up: [`../README.md`](../README.md) · Product plan: [`../../PLAN.md`](../../PLAN.md) · Tasks:
|
||||
[`../../TODO.md`](../../TODO.md).
|
||||
@@ -127,7 +127,7 @@ the documented right-click/`xattr` quarantine instructions. Signing and
|
||||
notarization remain a public-release blocker until an Apple Developer account and
|
||||
a reproducible signing/notarization job are available; they are not silently
|
||||
claimed as complete. The same limitation is recorded in
|
||||
[`known-limitations.md`](known-limitations.md).
|
||||
[`known-limitations.md`](../design/known-limitations.md).
|
||||
|
||||
Always run the release build from a clean checkout or detached worktree. Godot
|
||||
can pack files from ignored `tmp/` and old `build/` folders into the PCK; the
|
||||
@@ -205,7 +205,7 @@ change, update `tools/build_releases.sh` first.
|
||||
|
||||
- [ ] All headless tests pass (exit code 0).
|
||||
- [ ] Game boots cleanly in a smoke test.
|
||||
- [ ] Controls documented in `docs/getting-started.md` match the build.
|
||||
- [ ] Controls documented in `docs/process/getting-started.md` match the build.
|
||||
- [ ] Version in `project.godot` matches the tag.
|
||||
- [ ] Export templates used are the official ones for the pinned engine.
|
||||
- [ ] Artifacts uploaded; README downloads page shows them.
|
||||
@@ -87,7 +87,7 @@ The game writes four JSON files in Godot's `user://` directory:
|
||||
Files: `settings.json`, `campaign.json`, `shift_results.json` and the versioned
|
||||
`shift_state.json` checkpoint. The schema, migration/default-filling rules,
|
||||
atomic-write behavior and checkpoint contents are in
|
||||
[`architecture.md#persistence-and-save-contract`](architecture.md#persistence-and-save-contract).
|
||||
[`architecture.md#persistence-and-save-contract`](../project/architecture.md#persistence-and-save-contract).
|
||||
|
||||
For a clean first launch, delete the four files (or the whole `Gig Line` user
|
||||
directory). Settings' **Reset campaign** clears campaign progress separately.
|
||||
@@ -60,8 +60,8 @@ owns the mechanics.
|
||||
|
||||
These are the acceptance targets for the 0.10.0 balance pass, not measured results.
|
||||
No reaction tables, event weights or scoring rules were changed to set them. The
|
||||
[roadmap](../TODO.md) tracks the sweeps and external playtests still needed.
|
||||
[Gameplay](gameplay.md) owns the mechanics; this page owns their balance-test protocol.
|
||||
[roadmap](../../TODO.md) tracks the sweeps and external playtests still needed.
|
||||
[Gameplay](../design/gameplay.md) owns the mechanics; this page owns their balance-test protocol.
|
||||
|
||||
### Test matrix and evidence
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
# Project Documentation
|
||||
|
||||
Architecture and project status.
|
||||
|
||||
- [`architecture.md`](architecture.md) — the arc42-style architecture: goals, constraints,
|
||||
building blocks, runtime views, decisions and risks.
|
||||
- [`development-status.md`](development-status.md) — the canonical implemented-features list,
|
||||
verification baseline and known gaps.
|
||||
|
||||
Up: [`../README.md`](../README.md) · Product plan: [`../../PLAN.md`](../../PLAN.md) · Tasks:
|
||||
[`../../TODO.md`](../../TODO.md).
|
||||
@@ -27,8 +27,8 @@ This document follows the structure of the arc42 architecture documentation temp
|
||||
- The first implementation should be small enough for a playable vertical slice.
|
||||
- The engine is Godot 4.7.2 with GDScript; a playable prototype vertical slice is implemented. CI, local development and exported builds use 4.7.2; the default renderer stays GL Compatibility for Web parity, with an optional Forward+ Desktop HQ build.
|
||||
- Venue-specific policies must be configurable rather than hard-coded into individual NPCs.
|
||||
- The game must preserve the de-escalation-first design described in [`PLAN.md`](../PLAN.md).
|
||||
- The project uses the repository workflow described in [`AGENTS.md`](../AGENTS.md).
|
||||
- The game must preserve the de-escalation-first design described in [`PLAN.md`](../../PLAN.md).
|
||||
- The project uses the repository workflow described in [`AGENTS.md`](../../AGENTS.md).
|
||||
- The project follows [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`).
|
||||
|
||||
### Version management
|
||||
@@ -37,7 +37,7 @@ This document follows the structure of the arc42 architecture documentation temp
|
||||
- **MINOR** — new venues, NPC archetypes, systems, or features that are backward compatible.
|
||||
- **PATCH** — bug fixes and small polish that do not change behavior.
|
||||
|
||||
The single source of truth for the version is `config/version` in `project.godot` (currently `0.9.8`). Each release is tagged in git as `v<version>` (e.g. `v0.6.0`). The `0.x` series is pre-stable, so MINOR bumps may introduce breaking changes while the prototype is still stabilizing. `tools/build_releases.sh` and `tools/publish_release.sh` read the version from `project.godot`, so bumping it there is the only required step before a release. The full bump checklist lives in [`RELEASING.md`](RELEASING.md).
|
||||
The single source of truth for the version is `config/version` in `project.godot` (currently `0.9.9`). Each release is tagged in git as `v<version>` (e.g. `v0.6.0`). The `0.x` series is pre-stable, so MINOR bumps may introduce breaking changes while the prototype is still stabilizing. `tools/build_releases.sh` and `tools/publish_release.sh` read the version from `project.godot`, so bumping it there is the only required step before a release. The full bump checklist lives in [`RELEASING.md`](../process/RELEASING.md).
|
||||
|
||||
## 3. Context and Scope
|
||||
|
||||
@@ -82,7 +82,7 @@ The player interacts with NPCs, venue entrances, access artifacts, equipment, st
|
||||
- `src/game/ui/art.gd` loads runtime UI/scene art from `assets/images/ui/` and `assets/images/scenes/`, with null fallbacks so panels keep their procedural layouts.
|
||||
- `tools/model_pipeline.py` builds and audits the street-prop `.glb` models and packs their colour atlases.
|
||||
- `tools/npc_pipeline.py` builds and audits the skinned NPC base model (`assets/models/generated/npc_base.glb`) and its per-slot material maps, with an optional AI fabric override (ADR-0013). The active character migration bakes the CC0 Quaternius base onto the same contract (ADR-0017); the procedural base remains the fallback.
|
||||
- `tools/blender_assets.py` builds, renders and audits the Blender asset library (`assets/models/blender/{npc,npc_gear,props}/` + `manifest.json`): NPC character variants that are drop-in for `npc_base`, attach-point gear, and street/venue props. `NpcAvatar` selects variants/gear by role/seed and `WorldBuilder` loads the prop replacements and new street dressing, with procedural fallbacks (see `docs/blender-assets.md`).
|
||||
- `tools/blender_assets.py` builds, renders and audits the Blender asset library (`assets/models/blender/{npc,npc_gear,props}/` + `manifest.json`): NPC character variants that are drop-in for `npc_base`, attach-point gear, and street/venue props. `NpcAvatar` selects variants/gear by role/seed and `WorldBuilder` loads the prop replacements and new street dressing, with procedural fallbacks (see `docs/assets/blender-assets.md`).
|
||||
- `tools/scene_concepts.py` generates realism-pass references (`docs/screens/concepts/`), skyline backdrops and surface tiles (raw `assets/textures/ai/v2/raw/` → candidates `assets/textures/ai/game_ready/v2/`), promotes the validated ones to the tracked `v2/picks/` that `SurfaceMaterials`/`WorldBuilder` preload, audits them, and scores `src/test/capture_realism.gd` A/B captures (six stages, runtime texture swaps) against the concepts (`docs/screens/realism/<run>/`).
|
||||
- `tools/asset_pipeline.py` generates and audits role-aware textures; `tools/screen_designs.py` generates screen references and judges captures; `tools/check_screenshots.sh` renders the staged gallery and runs the compare gate.
|
||||
|
||||
@@ -90,7 +90,7 @@ Confirmed game assets live in `assets/textures/ai/game_ready/` (audited surface,
|
||||
|
||||
### Asset storage conventions
|
||||
|
||||
The canonical rules live in [ADR-0014](adr/0014-runtime-image-root.md). In short:
|
||||
The canonical rules live in [ADR-0014](../adr/0014-runtime-image-root.md). In short:
|
||||
|
||||
| Location | Contents | Loaded at runtime? |
|
||||
| --- | --- | --- |
|
||||
@@ -190,7 +190,7 @@ Venue rules:
|
||||
|
||||
Persistence is local-only under Godot's `user://` directory. The architecture
|
||||
owns the schema; operational locations and reset/rollback steps live in
|
||||
[`getting-started.md`](getting-started.md#save-data-and-migration).
|
||||
[`getting-started.md`](../process/getting-started.md#save-data).
|
||||
|
||||
| File | Contents | Compatibility |
|
||||
| --- | --- | --- |
|
||||
@@ -220,8 +220,8 @@ developer tools only — runtime, tests and CI consume committed GLBs and maps.
|
||||
| `tools/npc_pipeline.py` | Builds the skinned base avatar, five-slot material maps, palette and AI-fabric preparation (`prepare`/`palette`) | `npc_base.glb`, `assets/textures/npc/*_{albedo,normal,orm}.png`, `palette.json` | `audit_glb` against the 24,000-triangle / 24,000-vertex base contract (13 core bones required; extras allowed) |
|
||||
| `tools/blender_assets.py` | Builds/renders the library: 12 characters, 15 gear pieces, 20 props, plus `manifest.json`; stdlib `audit`/`fit`/`sheet`/`list` | `assets/models/blender/{npc,npc_gear,props}/*.glb` | Character cap 24,000 tris / 24,000 verts, 1,500 per gear, 4,000 per prop; grounding, UV, degenerate-triangle, attach-fit and manifest coverage checks |
|
||||
| `tools/bake_ao.py` | Bakes per-asset AO maps | `<asset>_ao.png` (256²) | Wired through `Materials.apply_ao()`/`SurfaceMaterials`; cloth/pants opt out (see below) |
|
||||
| `tools/npc_proportions.py` | Measures exported GLB rest pose (height, head, shoulders, hips, torso, limbs, feet) against the stylized guide | report / JSON in `docs/3d-model-review.md#character-measurements` | All eight variants must stay inside the guide after a body change |
|
||||
| `tools/npc_baseline.py` | Assembles neutral-baseline sheets and before/after comparisons | `docs/blender_previews/sheet_npc_baseline*.jpg` | Human review against `docs/3d-model-review.md` |
|
||||
| `tools/npc_proportions.py` | Measures exported GLB rest pose (height, head, shoulders, hips, torso, limbs, feet) against the stylized guide | report / JSON in `docs/assets/3d-model-review.md#character-measurements` | All eight variants must stay inside the guide after a body change |
|
||||
| `tools/npc_baseline.py` | Assembles neutral-baseline sheets and before/after comparisons | `docs/blender_previews/sheet_npc_baseline*.jpg` | Human review against `docs/assets/3d-model-review.md` |
|
||||
| `src/test/capture_npc_baseline.gd` | Fixed-camera studio baseline, 8 variants × 6 views | local `tmp/` frames | Neutral silhouette/face/gear review |
|
||||
| `src/test/capture_npc_review.gd` | Final-context gate: 8 variants × 2 venues × day/night × 3 distances = 96 frames, crowd hidden, review-only `character_override` for the guard | local `tmp/` frames | Pre-build acceptance gate for gear fit and venue lighting |
|
||||
| `src/test/capture_realism.gd` | Venue realism stages plus a frozen portrait and surface close-ups | `docs/screens/realism/<run>/` | Optional vision judge; portrait is the only avatar-detail capture |
|
||||
@@ -243,16 +243,16 @@ Runtime contracts that must survive any character change:
|
||||
- Rebuild only the assets whose geometry changed (Blender GLB export is byte-nondeterministic),
|
||||
then run `godot --headless --path . --import`; never commit a no-op full rebuild.
|
||||
|
||||
Evidence and detailed contracts live in [`blender-assets.md`](blender-assets.md),
|
||||
[`3d-model-review.md`](3d-model-review.md) and
|
||||
[`3d-model-review.md#character-measurements`](3d-model-review.md#character-measurements); command-level usage is in
|
||||
[`asset-tooling.md`](asset-tooling.md).
|
||||
Evidence and detailed contracts live in [`blender-assets.md`](../assets/blender-assets.md),
|
||||
[`3d-model-review.md`](../assets/3d-model-review.md) and
|
||||
[`3d-model-review.md#character-measurements`](../assets/3d-model-review.md#character-measurements); command-level usage is in
|
||||
[`asset-tooling.md`](../assets/asset-tooling.md).
|
||||
|
||||
### Local map development tooling (planned)
|
||||
|
||||
The current venues are hand-authored procedural reconstructions in
|
||||
`src/game/world_builder.gd`. The local map workstreams (**H–M**) in
|
||||
[`TODO.md`](../TODO.md#3d-model-re-evaluation) are unversioned and planned: they will
|
||||
[`TODO.md`](../../TODO.md#3d-model-and-local-map-re-evaluation) are unversioned and planned: they will
|
||||
test whether licensed data and reference photography can replace or supplement the
|
||||
stylized geometry without moving map data, AI composition or splat rendering into
|
||||
the runtime.
|
||||
@@ -353,7 +353,7 @@ Releases are produced from a tagged commit and published to the repository host'
|
||||
- `tools/build_releases.sh` — exports the desktop binaries and Web zip into `build/`, named `gig-line-<platform>-<version>.<ext>`.
|
||||
- `tools/publish_release.sh` — creates a release and uploads the artifacts via the Gitea API, using `GITEA_TOKEN` or the checkout extraheader fallback.
|
||||
- Packaging — NSIS builds the Windows installer; `packaging/linux/build_appimage.sh` builds the AppImage.
|
||||
- [`RELEASING.md`](RELEASING.md) — step-by-step guide and release checklist.
|
||||
- [`RELEASING.md`](../process/RELEASING.md) — step-by-step guide and release checklist.
|
||||
|
||||
The release process is: bump the version, run the full test suite and `tools/check_screenshots.sh`, run `tools/build_releases.sh`, tag and push (CI publishes), then verify the README "Downloads" links and the release artifacts.
|
||||
|
||||
@@ -372,27 +372,27 @@ The release process is: bump the version, run the full test suite and `tools/che
|
||||
- **Campaign and checkpoint state:** `Campaign` owns venue order/progression; settings, campaign, completed shift history and a versioned pause checkpoint are separate JSON documents. The checkpoint snapshots coordinator systems, scheduler RNG and NPC presentation/access state; it deliberately does not serialize the tutorial overlay or transient input state.
|
||||
- **Difficulty:** easy/normal/hard only scale spawn pacing, NPC compliance tolerance and report-credibility strictness; access/escalation rules and emergency rarity are invariant.
|
||||
- **Settings and accessibility:** volume/motion/caption settings persist through `settings.json`; Help is generated from the input-binding catalogue and the HUD log is the text caption surface. CI/release, local development and exported builds are unified on Godot 4.7.2.
|
||||
- **Documentation ownership:** `PLAN.md` owns design intent; `docs/gameplay.md` owns playable mechanics; `docs/architecture.md` owns system boundaries, data flow, constraints and cross-cutting decisions; ADRs own decision history; `docs/development-status.md` owns the implemented/gap list; `TODO.md` owns the roadmap; `MEMORY.md` owns gotchas and open questions. Specialized docs link to these rather than becoming competing sources of truth.
|
||||
- **Documentation ownership:** `PLAN.md` owns design intent; `docs/design/gameplay.md` owns playable mechanics; `docs/project/architecture.md` owns system boundaries, data flow, constraints and cross-cutting decisions; ADRs own decision history; `docs/project/development-status.md` owns the implemented/gap list; `TODO.md` owns the roadmap; `MEMORY.md` owns gotchas and open questions. Specialized docs link to these rather than becoming competing sources of truth.
|
||||
|
||||
## 9. Architecture Decisions
|
||||
|
||||
Architecture decisions are recorded as ADRs:
|
||||
|
||||
- [ADR-0001: Venue-driven simulation architecture](adr/0001-venue-driven-simulation-architecture.md)
|
||||
- [ADR-0002: De-escalation-first escalation model](adr/0002-de-escalation-first-escalation-model.md)
|
||||
- [ADR-0003: Explicit access-verification system](adr/0003-explicit-access-verification-system.md)
|
||||
- [ADR-0004: Local single-player first](adr/0004-local-single-player-first.md)
|
||||
- [ADR-0005: Event-based incident recording](adr/0005-event-based-incident-recording.md)
|
||||
- [ADR-0006: Godot 4 with GDScript](adr/0006-godot-4-gdscript.md)
|
||||
- [ADR-0007: Locomotion and input layers](adr/0007-locomotion-and-input-layers.md)
|
||||
- [ADR-0008: Cone focus and focus circle](adr/0008-cone-focus-and-head-ring.md)
|
||||
- [ADR-0009: Radial action menu](adr/0009-radial-action-menu.md)
|
||||
- [ADR-0010: Procedural NPC presentation](adr/0010-procedural-npc-presentation.md)
|
||||
- [ADR-0017: Quaternius NPC base](adr/0017-quaternius-npc-base.md)
|
||||
- [ADR-0011: Aim-free selection and precision walk](adr/0011-aim-free-selection-and-precision-walk.md)
|
||||
- [ADR-0012: Surface materials and generated props](adr/0012-surface-materials-and-generated-props.md)
|
||||
- [ADR-0013: Blender-authored NPC characters and baked materials](adr/0013-blender-authored-npc-characters.md)
|
||||
- [ADR-0014: Canonical runtime image root and image conventions](adr/0014-runtime-image-root.md)
|
||||
- [ADR-0001: Venue-driven simulation architecture](../adr/0001-venue-driven-simulation-architecture.md)
|
||||
- [ADR-0002: De-escalation-first escalation model](../adr/0002-de-escalation-first-escalation-model.md)
|
||||
- [ADR-0003: Explicit access-verification system](../adr/0003-explicit-access-verification-system.md)
|
||||
- [ADR-0004: Local single-player first](../adr/0004-local-single-player-first.md)
|
||||
- [ADR-0005: Event-based incident recording](../adr/0005-event-based-incident-recording.md)
|
||||
- [ADR-0006: Godot 4 with GDScript](../adr/0006-godot-4-gdscript.md)
|
||||
- [ADR-0007: Locomotion and input layers](../adr/0007-locomotion-and-input-layers.md)
|
||||
- [ADR-0008: Cone focus and focus circle](../adr/0008-cone-focus-and-head-ring.md)
|
||||
- [ADR-0009: Radial action menu](../adr/0009-radial-action-menu.md)
|
||||
- [ADR-0010: Procedural NPC presentation](../adr/0010-procedural-npc-presentation.md)
|
||||
- [ADR-0017: Quaternius NPC base](../adr/0017-quaternius-npc-base.md)
|
||||
- [ADR-0011: Aim-free selection and precision walk](../adr/0011-aim-free-selection-and-precision-walk.md)
|
||||
- [ADR-0012: Surface materials and generated props](../adr/0012-surface-materials-and-generated-props.md)
|
||||
- [ADR-0013: Blender-authored NPC characters and baked materials](../adr/0013-blender-authored-npc-characters.md)
|
||||
- [ADR-0014: Canonical runtime image root and image conventions](../adr/0014-runtime-image-root.md)
|
||||
|
||||
## 10. Quality Requirements
|
||||
|
||||
@@ -435,32 +435,32 @@ architecture document.
|
||||
|
||||
| Document | Canonical role | Relationship to this architecture |
|
||||
| --- | --- | --- |
|
||||
| [`PLAN.md`](../PLAN.md) | Product/design intent, pillars, venues and success criteria | Design source; architecture realizes it |
|
||||
| [`docs/gameplay.md`](gameplay.md) | Playable loop, escalation, tutorial, venue mechanics | Runtime/behavioral view |
|
||||
| [`docs/venues.md`](venues.md) | Real-site evidence, mapping decisions and deliberate simplifications | Runtime venues' evidence companion to §5 |
|
||||
| [`docs/architecture.md`](architecture.md) | System boundaries, data flow, constraints, deployment, cross-cutting decisions, quality risks | Single architecture source |
|
||||
| [`docs/adr/`](adr/) | Immutable decision records with context and consequences | Decision history linked from §9 |
|
||||
| [`docs/asset-tooling.md`](asset-tooling.md) | Build/audit/capture commands, optional Blender MCP and pipeline usage | Operational appendix to the pipeline section |
|
||||
| [`docs/blender-assets.md`](blender-assets.md) | Blender library art direction, roles, layout and checks | Operational asset appendix; contract lives here in §5 |
|
||||
| [`docs/3d-model-review.md`](3d-model-review.md) | Character and asset measurements, scorecard and ranked gaps | Visual-QA appendix to the character tooling section |
|
||||
| [`docs/3d-model-review.md`](3d-model-review.md) | Scorecard, measurements and ranked asset gaps | Working review companion to §5 |
|
||||
| [`docs/npc-model-sourcing.md`](npc-model-sourcing.md) | Character-source evaluation and licence/prototype outcome | Supports the character tooling section and ADR-0015 |
|
||||
| [`docs/getting-started.md`](getting-started.md) | Setup, commands, controls | Developer onboarding |
|
||||
| [`docs/RELEASING.md`](RELEASING.md) | Release checklist and CI/publishing steps | Deployment appendix to §7 |
|
||||
| [`docs/release-qa.md`](release-qa.md) | Manual smoke checklist and balance protocol | QA appendix to §10 |
|
||||
| [`docs/accessibility.md`](accessibility.md) | Accessibility features, statement and known gaps | Player-facing quality statement |
|
||||
| [`docs/known-limitations.md`](known-limitations.md) | Release blockers and accepted limitations | Player/release-facing risk statement |
|
||||
| [`docs/ui-copy.md`](ui-copy.md) | Screen/button inventory, copy audit and screen-judge report | Presentation appendix |
|
||||
| [`docs/development-status.md`](development-status.md) | Implemented features and current gaps | Status companion to the roadmap |
|
||||
| [`TODO.md`](../TODO.md) | Priority-ordered active tasks, unversioned development tracks and versioned roadmap | Planning source; no architecture duplication |
|
||||
| [`CHANGELOG.md`](../CHANGELOG.md) | User-facing release history | Release/version companion |
|
||||
| [`PLAN.md`](../../PLAN.md) | Product/design intent, pillars, venues and success criteria | Design source; architecture realizes it |
|
||||
| [`docs/design/gameplay.md`](../design/gameplay.md) | Playable loop, escalation, tutorial, venue mechanics | Runtime/behavioral view |
|
||||
| [`docs/design/venues.md`](../design/venues.md) | Real-site evidence, mapping decisions and deliberate simplifications | Runtime venues' evidence companion to §5 |
|
||||
| [`docs/project/architecture.md`](architecture.md) | System boundaries, data flow, constraints, deployment, cross-cutting decisions, quality risks | Single architecture source |
|
||||
| [`docs/adr/`](../adr) | Immutable decision records with context and consequences | Decision history linked from §9 |
|
||||
| [`docs/assets/asset-tooling.md`](../assets/asset-tooling.md) | Build/audit/capture commands, optional Blender MCP and pipeline usage | Operational appendix to the pipeline section |
|
||||
| [`docs/assets/blender-assets.md`](../assets/blender-assets.md) | Blender library art direction, roles, layout and checks | Operational asset appendix; contract lives here in §5 |
|
||||
| [`docs/assets/3d-model-review.md`](../assets/3d-model-review.md) | Character and asset measurements, scorecard and ranked gaps | Visual-QA appendix to the character tooling section |
|
||||
| [`docs/assets/3d-model-review.md`](../assets/3d-model-review.md) | Scorecard, measurements and ranked asset gaps | Working review companion to §5 |
|
||||
| [`docs/assets/npc-model-sourcing.md`](../assets/npc-model-sourcing.md) | Character-source evaluation and licence/prototype outcome | Supports the character tooling section and ADR-0015 |
|
||||
| [`docs/process/getting-started.md`](../process/getting-started.md) | Setup, commands, controls | Developer onboarding |
|
||||
| [`docs/process/RELEASING.md`](../process/RELEASING.md) | Release checklist and CI/publishing steps | Deployment appendix to §7 |
|
||||
| [`docs/process/release-qa.md`](../process/release-qa.md) | Manual smoke checklist and balance protocol | QA appendix to §10 |
|
||||
| [`docs/design/accessibility.md`](../design/accessibility.md) | Accessibility features, statement and known gaps | Player-facing quality statement |
|
||||
| [`docs/design/known-limitations.md`](../design/known-limitations.md) | Release blockers and accepted limitations | Player/release-facing risk statement |
|
||||
| [`docs/design/ui-copy.md`](../design/ui-copy.md) | Screen/button inventory, copy audit and screen-judge report | Presentation appendix |
|
||||
| [`docs/project/development-status.md`](development-status.md) | Implemented features and current gaps | Status companion to the roadmap |
|
||||
| [`TODO.md`](../../TODO.md) | Priority-ordered active tasks, unversioned development tracks and versioned roadmap | Planning source; no architecture duplication |
|
||||
| [`CHANGELOG.md`](../../CHANGELOG.md) | User-facing release history | Release/version companion |
|
||||
|
||||
Consolidation decisions:
|
||||
|
||||
- **Architecture owns the "how"** (components, contracts, data flow, constraints, quality gates); **PLAN/gameplay own the "what"**; **ADRs own the "why"**. Links replace duplicated prose.
|
||||
- **Asset and release documents remain separate** because they are command-heavy operational procedures; their architecture-relevant contracts and failure modes are summarized in §5 and §7.
|
||||
- **Completed plans are removed, not kept as competing roadmaps.** Historical graphics work is summarized by ADR-0013, the asset pipeline section and the v0.6.0 changelog; new work belongs in TODO.
|
||||
- **Status and roadmap are separate from architecture.** `docs/development-status.md` records what exists; `TODO.md` records what remains, ordered as unversioned development tracks, versioned milestones and deferred work.
|
||||
- **Status and roadmap are separate from architecture.** `docs/project/development-status.md` records what exists; `TODO.md` records what remains, ordered as unversioned development tracks, versioned milestones and deferred work.
|
||||
- **Documentation drift is a tracked risk:** release/version, test counts, renderer status, and stale plans must be corrected in the same commit as the change that invalidates them.
|
||||
|
||||
## 13. Glossary
|
||||
@@ -1,9 +1,9 @@
|
||||
# Development Status
|
||||
|
||||
Baseline: **v0.9.8** (2026-11-04). This page lists what the build currently
|
||||
Baseline: **v0.9.9** (2026-11-06). This page lists what the build currently
|
||||
supports and what remains; it is not a release history. Completed work lives in
|
||||
[`DONE.md`](../DONE.md), user-facing changes in [`CHANGELOG.md`](../CHANGELOG.md),
|
||||
and the active order/gaps in [`TODO.md`](../TODO.md).
|
||||
[`DONE.md`](../../DONE.md), user-facing changes in [`CHANGELOG.md`](../../CHANGELOG.md),
|
||||
and the active order/gaps in [`TODO.md`](../../TODO.md).
|
||||
|
||||
## Implemented
|
||||
|
||||
@@ -16,7 +16,7 @@ and the active order/gaps in [`TODO.md`](../TODO.md).
|
||||
| Access and escalation | Six escalation levels, venue access policies, artifact validity/recognition, door lock, crowd reactions, investigation/false-report handling and shift review. |
|
||||
| UI/input | Keyboard/mouse and gamepad bindings, focus rings, default modal focus, single top-modal close path, shared button states, font scaling, long-string handling, searchable Help and 21 committed UI/game captures. |
|
||||
| Audio/accessibility | Procedural crowd bed and radio cues, master/SFX/ambience volumes, reduced motion, captions, colour-independent escalation cue, hold-to-confirm emergency and guarded destructive actions. |
|
||||
| Persistence | Separate settings, campaign, shift-history and versioned checkpoint files; default-filling migration, atomic writes and corrupt/partial-file fallback. Save locations and rollback are documented in [`getting-started.md`](getting-started.md#save-data-and-migration). |
|
||||
| Persistence | Separate settings, campaign, shift-history and versioned checkpoint files; default-filling migration, atomic writes and corrupt/partial-file fallback. Save locations and rollback are documented in [`getting-started.md`](../process/getting-started.md#save-data). |
|
||||
| Assets | Blender character/gear/prop library with AO and manifests; 256² NPC maps with 4× fabric weave; image/texture pipelines, reference boards and three-up boards; environment/realism capture tools. |
|
||||
| Build/release | Godot 4.7.2 Compatibility/Web default plus optional Forward+ Desktop HQ. Gitea checks/build/publish, seven release assets, checksums, preflight/rollback and clean-worktree release discipline. |
|
||||
|
||||
@@ -41,7 +41,7 @@ and the active order/gaps in [`TODO.md`](../TODO.md).
|
||||
library and the MakeHuman head remain the tested fallback.
|
||||
- The roster passed its owner visual review on 2026-11-06: faces, head gear, hand-held and back
|
||||
gear were all accepted after the follow-up fixes. The review page and its sheets were retired;
|
||||
the measurements live in `docs/3d-model-review.md` and `docs/blender-assets.md`.
|
||||
the measurements live in `docs/assets/3d-model-review.md` and `docs/assets/blender-assets.md`.
|
||||
- Roster silhouette variety is narrower than the procedural library (three meshes for twelve
|
||||
roles, differentiated by tint and gear) until the modular part library is added.
|
||||
- Head gear is authored for the shipped Quaternius head; the procedural fallback therefore wears
|
||||
@@ -51,6 +51,6 @@ and the active order/gaps in [`TODO.md`](../TODO.md).
|
||||
- Live 3D replay, recorded VO/music, more venues and seasonal content are future
|
||||
work.
|
||||
|
||||
See [`TODO.md`](../TODO.md) for the ordered task list and
|
||||
[`known-limitations.md`](known-limitations.md) for the current release blockers.
|
||||
See [`TODO.md`](../../TODO.md) for the ordered task list and
|
||||
[`known-limitations.md`](../design/known-limitations.md) for the current release blockers.
|
||||
Architecture and ownership are in [`architecture.md`](architecture.md).
|
||||
@@ -15,13 +15,13 @@ The map-optimization references for the El Capitan Entertainment Centre block
|
||||
(6840 Hollywood Blvd) are in
|
||||
[`hollywood_boulevard/README.md`](hollywood_boulevard/README.md). The real-site
|
||||
facts and game mapping are documented in
|
||||
[`../../venues.md`](../../venues.md#hollywood-boulevard).
|
||||
[`../../venues.md`](../../design/venues.md#hollywood-boulevard).
|
||||
|
||||
## The Joke Shop — Sunset Strip
|
||||
|
||||
The current Joke Shop map is based on The Comedy Store at 8433 Sunset Blvd.
|
||||
The real-site mapping and simplifications are in
|
||||
[`../../venues.md`](../../venues.md#the-joke-shop); the frames are in
|
||||
[`../../venues.md`](../../design/venues.md#the-joke-shop); the frames are in
|
||||
[`joke_shop/README.md`](joke_shop/README.md).
|
||||
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ AI-generated art-direction frames for the real El Capitan Entertainment Centre
|
||||
block at 6840 Hollywood Boulevard. They are generated with
|
||||
`tools/scene_concepts.py generate --group scene --only ...` and are not shipped
|
||||
game textures. The geometry mapping and source links are in
|
||||
[`../../../venues.md`](../../../venues.md#hollywood-boulevard).
|
||||
[`../../../venues.md`](../../../design/venues.md#hollywood-boulevard).
|
||||
|
||||
## Entrance — day
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ AI-generated art-direction frames for the fictional Joke Shop, based on the
|
||||
real Comedy Store block at 8433 Sunset Boulevard. They are generated with
|
||||
`tools/scene_concepts.py generate --group scene --only ...` and are not shipped
|
||||
game textures. The geometry mapping and source links are in
|
||||
[`../../../venues.md`](../../../venues.md#the-joke-shop).
|
||||
[`../../../venues.md`](../../../design/venues.md#the-joke-shop).
|
||||
|
||||
## Entrance — day, photo-anchored
|
||||
|
||||
|
||||
@@ -1,68 +0,0 @@
|
||||
# Head rework — review page (2026-11-04)
|
||||
|
||||
> **Historical page / changed source (2026-11-04).** The numbers below describe the
|
||||
> earlier decimated MakeHuman head (1,548-tri skin). The shared source
|
||||
> `assets/models/blender_src/makehuman_head.glb` now holds the higher-resolution
|
||||
> standalone prototype. The owner accepted the basic head; the automated vision gate
|
||||
> still records REJECT on the eye/lid region as deferred polish. See
|
||||
> [`../../makehuman-head-review.md`](../../makehuman-head-review.md). Re-run the
|
||||
> library head build before relying on the comparison counts below.
|
||||
|
||||
This page is the review checkpoint for the NPC head rework. The goal was to replace the
|
||||
sphere-and-floating-primitive face with a head that has real nose / chin / jaw landmarks at
|
||||
portrait distance.
|
||||
|
||||
## What changed
|
||||
|
||||
The original procedural face is a head sphere plus separate nose, mouth, ear and eye primitives.
|
||||
The new head uses the **decimated MakeHuman head** (CC0, 1,573 tris) as the base shape and keeps
|
||||
the project's separate eyeballs, brow and mouth pieces on top. An AI judge was used to drive the
|
||||
decision: it scored the procedural rework at ~3/5 and then picked the MakeHuman head as the
|
||||
clearer silhouette.
|
||||
|
||||
| | Source | Tris (head) | Read |
|
||||
| --- | --- | --- | --- |
|
||||
| **Before** | procedural `_face` (sphere + primitives) | ~1,900 | flat face, slit eyes |
|
||||
| **After** | overhauled MakeHuman head + project eyes/brows/mouth | ~1,880 | smooth nose/chin/jaw landmarks |
|
||||
|
||||
The head source was overhauled 2026-11-04: the blocky decimated MakeHuman head was welded
|
||||
(merge-by-distance) and Laplacian-relaxed into one clean manifold shell (`makehuman_head.glb`,
|
||||
1,548 tris skin), then the project eyes/brows/mouth were added.
|
||||
|
||||
## AI-generated target concept
|
||||
|
||||
The rework was guided by two generated concept frames (front + profile, `bytedance-seed/seedream-4.5`).
|
||||
|
||||
|
||||
|
||||
## 1.85 m comparison (top = current, bottom = new)
|
||||
|
||||
Left to right: front, three-quarter, profile.
|
||||
|
||||
|
||||
|
||||
## New head at 1.5 m (portrait)
|
||||
|
||||
|
||||
|
||||
## Contract and checks
|
||||
|
||||
- `blender_assets.py inspect` on the assembled `npc_casual` with the new head: **14 bones,
|
||||
skinned, no issues**.
|
||||
- Source: `assets/models/blender_src/makehuman_head.glb` (CC0, attributed in `CREDITS.md`).
|
||||
- Python 167/167, Godot 277/277, `check_docs` OK.
|
||||
|
||||
## Remaining polish (known, not blockers)
|
||||
|
||||
1. The hair cap still reads as a stepped block instead of hugging the skull.
|
||||
2. The brows weld to the face but can read as a slightly separate bar.
|
||||
3. The neck underside cap is plain; it is hidden by the body neck in the assembled character.
|
||||
4. The head skin is 1.5k tris (smooth but low-poly); a retopology pass could add resolution if a
|
||||
portrait shows faceting.
|
||||
|
||||
## Decision (2026-11-04, owner)
|
||||
|
||||
The MakeHuman-head direction is approved for the basic human head. The remaining review is the
|
||||
assembled prototype's hair cap and full-body silhouette. After that, roll the head into the other
|
||||
11 variants (one asset family at a time) with a before/after sheet per batch, then re-run the
|
||||
24-NPC budget + AO bake.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 45 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 55 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 29 KiB |
@@ -76,8 +76,8 @@ committed here is the redacted copy, not the original.
|
||||
## How the folder is used
|
||||
|
||||
- Build the venue **three-up boards** (photo | concept | current capture) for the review verdicts.
|
||||
- Link the board from the venue map document (`docs/venues.md#hollywood-boulevard`,
|
||||
`docs/venues.md#the-joke-shop`) and from the local-map block notes.
|
||||
- Link the board from the venue map document (`docs/design/venues.md#hollywood-boulevard`,
|
||||
`docs/design/venues.md#the-joke-shop`) and from the local-map block notes.
|
||||
- Cite the sidecar when a texture, proportion or signage decision is derived from a photo.
|
||||
- Refresh the board when a venue change makes an old reference misleading, and note the change in
|
||||
the sidecar.
|
||||
|
||||
@@ -34,12 +34,12 @@ attribution string for CC BY / CC BY-SA in the `Author` or a note below.
|
||||
|
||||
| Decision | Evidence | Where it landed |
|
||||
| --- | --- | --- |
|
||||
| e.g. six-column spacing kept at 2.4 m | photo 1, measured against door width | `docs/venues.md#hollywood-boulevard` |
|
||||
| e.g. six-column spacing kept at 2.4 m | photo 1, measured against door width | `docs/design/venues.md#hollywood-boulevard` |
|
||||
| e.g. banner red sampled to `#8a1f24` | photo 1 + photo 2 | `docs/screens/refs/hollywood/` notes, facade kit |
|
||||
|
||||
## Generated boards used with this set
|
||||
|
||||
Generated frames live in [`../../concepts/`](../../concepts/README.md); reference them here so the
|
||||
Generated frames live in [`../../concepts/`](../concepts/README.md); reference them here so the
|
||||
three-up sheet is reproducible.
|
||||
|
||||
| Board | Path | Model | Prompt / seed | Generated | Spend |
|
||||
|
||||
@@ -11,7 +11,7 @@ TV Studio board.
|
||||
|
||||
Provenance, licences and the decisions these photos informed are in
|
||||
[`SIDECAR.md`](SIDECAR.md). The rules for this folder are in
|
||||
[`../README.md`](../README.md); generated art-direction frames live in
|
||||
[`../README.md`](README.md); generated art-direction frames live in
|
||||
[`../../concepts/hollywood_boulevard/`](../../concepts/hollywood_boulevard/README.md).
|
||||
|
||||
| Photo | What it is evidence for |
|
||||
@@ -35,5 +35,5 @@ Provenance, licences and the decisions these photos informed are in
|
||||
- The east retail neighbour beyond the temple (the modern retail block), for facade rhythm at the
|
||||
right-hand edge of the venue.
|
||||
|
||||
Add new files with the naming convention in [`../README.md`](../README.md) and list them in the
|
||||
Add new files with the naming convention in [`../README.md`](README.md) and list them in the
|
||||
sidecar in the same commit.
|
||||
@@ -26,7 +26,7 @@
|
||||
Licence texts: [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/),
|
||||
[CC BY 3.0](https://creativecommons.org/licenses/by/3.0/) and
|
||||
[CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/). The CC BY and CC BY-SA files are
|
||||
also listed in [`../../../CREDITS.md`](../../../CREDITS.md) under "Development-only reference
|
||||
also listed in [`../../../../CREDITS.md`](../../../../CREDITS.md) under "Development-only reference
|
||||
images".
|
||||
|
||||
**CC BY-SA review (2026-11-03):** `hollywood-boulevard-night-context-ccbysa.jpg` is redistributed
|
||||
@@ -51,10 +51,10 @@ before use.
|
||||
|
||||
| Decision | Evidence | Where it landed |
|
||||
| --- | --- | --- |
|
||||
| Six Ionic columns, ~2.4 m spacing, 8 steps | facade photo measured against the door width | `docs/venues.md#hollywood-boulevard` geometry notes |
|
||||
| Six Ionic columns, ~2.4 m spacing, 8 steps | facade photo measured against the door width | `docs/design/venues.md#hollywood-boulevard` geometry notes |
|
||||
| Masonic parapet motto and medallions | 1922 elevation + facade photo | `WorldBuilder` facade, `docs/screenshots/01-venue-overview.png` |
|
||||
| Three vertical event banners | facade photo | facade banners and the day/night capture set |
|
||||
| Red carpet + barrier staging narrows the sidewalk | premiere photo | `docs/venues.md#hollywood-boulevard` event staging notes |
|
||||
| Red carpet + barrier staging narrows the sidewalk | premiere photo | `docs/design/venues.md#hollywood-boulevard` event staging notes |
|
||||
| Across-street height and plaza opening | Ovation photo | opposite frontage massing |
|
||||
| TV Studio arrival staging (bulb canopy, car, barriers) | premiere staging photo | `VENUE_SPECS["tv_studio"]` and the Late Night TV Studio venue docs |
|
||||
| Terrazzo band width, star size/spacing | terrazzo + star close-up photos | `WalkOfFame` band geometry and the paver material |
|
||||
|
||||
@@ -29,6 +29,6 @@ README, the gameplay docs and the screenshot gate; do not edit them by hand.
|
||||
| 21 | [Responder arrival](21-responder-arrival.png) | A responder at the locked door |
|
||||
|
||||
The captures are 1280×720 PNGs. Reference designs and the judge report live in
|
||||
[`../screens/`](../screens/README.md) and [`../ui-copy.md#screen-design-judge-report`](../ui-copy.md#screen-design-judge-report);
|
||||
[`../screens/`](../screens/README.md) and [`../ui-copy.md#screen-design-judge-report`](../design/ui-copy.md#screen-design-judge-report);
|
||||
the re-evaluation's pose and review sheets are under
|
||||
[`../blender_previews/`](../blender_previews/README.md).
|
||||
@@ -23,7 +23,7 @@ extends SceneTree
|
||||
## same `_animate()` sequence *does* render the crouch, and writing a single
|
||||
## bone rotation directly does deform the mesh, so this is a staging/capture
|
||||
## discrepancy, not a rig failure. Do not use these sheets as pose evidence.
|
||||
## Repro and what was ruled out: `docs/3d-model-review.md` section
|
||||
## Repro and what was ruled out: `docs/assets/3d-model-review.md` section
|
||||
## "Pose evidence is blocked".
|
||||
##
|
||||
## Usage (windowed; `xvfb-run -a` works for automation):
|
||||
|
||||
+1
-1
@@ -160,7 +160,7 @@ dependencies or replace the tools above.
|
||||
network/budget-dependent review aids, not deterministic CI gates.
|
||||
- `openrouter_judge.py` is an implementation detail imported by other tools.
|
||||
- `check_docs.py` and `export_venues.gd` are short, single-purpose commands;
|
||||
documenting them in this README and `docs/asset-tooling.md` is enough.
|
||||
documenting them in this README and `docs/assets/asset-tooling.md` is enough.
|
||||
- `npc_baseline.py`, `npc_proportions.py` and `three_up.py` are better included
|
||||
as references/steps inside the proposed asset or release skill than exposed as
|
||||
separate skills; fragmenting them would increase routing mistakes.
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
Everything here is modelled procedurally inside Blender (flatpak, headless) so
|
||||
the assets are reproducible from source. Outputs are staged for *later*
|
||||
integration: nothing in the game loads them yet (see
|
||||
`docs/blender-assets.md` for the integration contract).
|
||||
`docs/assets/blender-assets.md` for the integration contract).
|
||||
|
||||
# build every asset (or --only name,name) -> assets/models/blender/**.glb
|
||||
flatpak run org.blender.Blender --background \
|
||||
@@ -1489,7 +1489,7 @@ def build_character(name, head="face"):
|
||||
# is 4 skinned meshes on the same 62-joint armature; the build joins them
|
||||
# **without welding** (a weld corrupts the skin weights), renames the upstream
|
||||
# materials onto the five tint slots, unwraps the degenerate source UVs and bakes
|
||||
# the arm-down rest. See docs/npc-model-sourcing.md for the measurements.
|
||||
# the arm-down rest. See docs/assets/npc-model-sourcing.md for the measurements.
|
||||
|
||||
QUATERNIUS_SRC = SRC_DIR / "quaternius"
|
||||
|
||||
@@ -1497,7 +1497,7 @@ QUATERNIUS_SRC = SRC_DIR / "quaternius"
|
||||
# (face, hair detail and hivis fabrics); anything not listed is kept too, so a
|
||||
# new upstream material shows up as an extra fixed-colour slot instead of
|
||||
# silently disappearing. The maps were derived from the per-material height bands
|
||||
# measured in docs/npc-model-sourcing.md.
|
||||
# measured in docs/assets/npc-model-sourcing.md.
|
||||
QUATERNIUS_SOURCES = {
|
||||
"casual": {
|
||||
"file": "Casual.glb",
|
||||
@@ -2605,7 +2605,7 @@ def build_gear(name):
|
||||
# procedural library's 0.315 m, and its centre sits 0.07 m higher, so the
|
||||
# head gear is scaled and lifted to match. The procedural fallback then
|
||||
# wears slightly small hats — cosmetic, and recorded in
|
||||
# docs/blender-assets.md.
|
||||
# docs/assets/blender-assets.md.
|
||||
centre = Vector((0.0, 0.0, HEAD_GEAR_LIFT))
|
||||
obj.data.transform(
|
||||
Matrix.Translation(centre)
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
#
|
||||
# Requirements:
|
||||
# - Godot 4.7.2 (or the version in project.godot `config/features`) on PATH,
|
||||
# with export templates installed (see docs/RELEASING.md).
|
||||
# with export templates installed (see docs/process/RELEASING.md).
|
||||
# - Run from the repository root.
|
||||
#
|
||||
# Produces:
|
||||
@@ -20,8 +20,8 @@ VERSION="$(grep -oP 'config/version="\K[^"]+' project.godot)"
|
||||
PLAYER_DOCS=(
|
||||
"CREDITS.md"
|
||||
"PRIVACY.md"
|
||||
"docs/accessibility.md"
|
||||
"docs/known-limitations.md"
|
||||
"docs/design/accessibility.md"
|
||||
"docs/design/known-limitations.md"
|
||||
)
|
||||
mkdir -p build
|
||||
# Presets now embed the PCK into a single binary; drop stale .pck leftovers.
|
||||
@@ -95,4 +95,4 @@ shasum -a 256 build/*"${VERSION}"* > "build/SHA256SUMS-${VERSION}.txt"
|
||||
cat "build/SHA256SUMS-${VERSION}.txt"
|
||||
echo ""
|
||||
echo "Upload to: https://git.allucanget.biz/zwitschi/security-game/releases"
|
||||
echo "See docs/RELEASING.md for the full release checklist."
|
||||
echo "See docs/process/RELEASING.md for the full release checklist."
|
||||
@@ -16,7 +16,7 @@ path must be absolute):
|
||||
python3 tools/npc_pipeline.py palette # derive outfit colours -> palette.json
|
||||
python3 tools/npc_pipeline.py audit
|
||||
|
||||
Contract (frozen in ADR-0013 and docs/blender-assets.md):
|
||||
Contract (frozen in ADR-0013 and docs/assets/blender-assets.md):
|
||||
|
||||
* scene root "Rig" with a skinned mesh and an armature
|
||||
* bones: Head, HipL/R, KneeL/R, ShoulderL/R, ElbowL/R, HandL/R
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
"""Keep the 3D model review scorecard honest.
|
||||
|
||||
Every catalogue asset (characters, gear, props) must have a row in
|
||||
`docs/3d-model-review.md`, and the character rows must carry a verdict. This does
|
||||
`docs/assets/3d-model-review.md`, and the character rows must carry a verdict. This does
|
||||
not judge the art; it only fails when an asset is added or renamed without being
|
||||
reviewed, which is how a scorecard silently rots.
|
||||
"""
|
||||
@@ -13,7 +13,7 @@ from pathlib import Path
|
||||
import blender_assets as model
|
||||
|
||||
ROOT = Path(model.__file__).resolve().parent.parent
|
||||
REVIEW = ROOT / "docs" / "3d-model-review.md"
|
||||
REVIEW = ROOT / "docs" / "assets" / "3d-model-review.md"
|
||||
|
||||
|
||||
def catalogue_names() -> set[str]:
|
||||
|
||||
Reference in new issue
Block a user