Skip to content

docs

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

docs

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
adr
adr
 
 
agent-rules
agent-rules
 
 
analysis
analysis
 
 
bug-investigations
bug-investigations
 
 
design
design
 
 
guides
guides
 
 
images
images
 
 
ops
ops
 
 
process
process
 
 
testing
testing
 
 
validation
validation
 
 
README.md
README.md
 
 
testing.md
testing.md
 
 

README.md

OloEngine documentation

Index of everything under docs/. Most subsystem code comments link here by path, so keep references in sync when moving a file (git grep "docs/<name>" before a rename).

Adding a doc? Add it here too. This index drifted to 5-of-46 on agent-rules/ once already; an unlisted doc is an unread doc.

agent-rules/ — guidance for AI agents working in this repo

Two genres: postmortems (one real failure each) and the notes-*.md reference guides (accumulated per-subsystem gotchas). Two indexes, deliberately:

  • agent-rules/README.md Part A — indexed by subsystem, one sentence each. Use this when you know what you're touching.
  • agent-rules/README.md Part B — the same set indexed by failure mode (green-but-wrong, one-contract-several-mirrors, silent drop, your-instrument-is-lying, ordering/lifetime, never-actually-called). Use this when you know what you're doing but not what can go wrong.

Read the relevant file before non-trivial work; don't duplicate its content into CLAUDE.md.

Testing

  • testing.md — the canonical testing opinion doc: why we test what we test, the renderer L1–L11 pyramid + Functional axis, value heuristic, anti-patterns, classification. The hub the test suite, CI, and agent-rules/testing-architecture.md all point at.
  • test-catalogue.{renderer,functional,unit}.md — generated & git-ignored per-file catalogues, rendered from test_catalogue.json + in-file // OLO_TEST_LAYER tags by OloEngine/tests/scripts/generate_test_catalogue.py. Not tracked; regenerate on demand.

guides/ — subsystem & tooling how-tos

  • guides/ai-goap.md — GOAP planner / AI action system.
  • guides/ai-perception.md — AI perception (sight/sound/awareness).
  • guides/cinematic-sequencer.md — cinematic sequencer / timeline.
  • guides/gltf-material-extensions.md — what the glTF transmission / IOR / volume extensions import and render, and where that stops.
  • guides/skin-material-profiles.md — what a .oloskin profile holds, in which units and colour space, how a skin material names one, and how to look at the four outputs a skin surface exposes.
  • guides/foliage-leaf-material.md — the vegetation material: which fields a foliage layer's leaf material has, why its transmission is split into a shadowed direct half and an environment half, what the distant impostor keeps and what it loses, and how to look at the transmission term on its own.
  • guides/skin-transmission.md — the thin-region transmission term: the unit chain from an authored thickness in metres to an optical depth, the three-premise argument for why it cannot double-count the diffusion beside it, and the four ways it silently does nothing.
  • guides/skin-diffusion.md — how the screen-space skin scattering works, which diffusion profile it uses and the reference comparison that chose it, what its radius is in world units, and exactly where it stops.
  • guides/skin-layered-specular.md — the two-lobe skin specular, the pore/normal filtering that stops it sparkling, and the expression-driven detail band: which five fields an author sets, the measured comparison that chose the model, why the variance is read from screen space and not from the normal map, and why the detail follows the APPLIED morph weights.
  • guides/skin-oral-surfaces.md — lips, gums, tongue and teeth: the wet coat that TAKES energy from the tissue rather than adding to it, the cavity weight that stops a closed mouth glowing under a back light, why teeth are a matter of authoring rather than a second code path, and the two limits (no coat under IBL, no oral anatomy in this repo).
  • guides/eye-cornea-iris.md — the eye: the corneal refraction that moves the iris you see, the left/right convention that needs no mirrored asset, why the index is the aqueous humour's and not the cornea's, why the tear line is #1245's wet coat rather than a second code path, and why a front-on screenshot cannot tell you whether any of it works.
  • guides/skin-digital-human.md — running skin, eyes and mouth on ONE subject: a complete face spends the whole seven-slot skin-profile budget and an eighth profile silently renders as not-skin, the material debug views are deferred-only, how to switch the three lighting rigs without changing two things at once, and why the decomposition is checked by cross-talk rather than by a sum.
  • guides/input-action-maps.md — input action maps & contexts.
  • guides/localization.md — localization & LocalizedTextComponent.
  • guides/mcp-diagnostics-server.md — the read-only MCP diagnostics server (tools, resources, prompts, attach flow).
  • guides/oloctl.md — oloctl, the CLI frontend generated from the automation registry (spelling rules, arguments, exit codes, the closed write path).
  • guides/perf-stress-scenes.md — perf stress-scene generator + measurement runbook.
  • guides/player-camera-rigs.md — reusable player + camera rigs (first-person / third-person follow spring arm).
  • guides/procedural-terrain.md — procedural terrain generation.
  • guides/ui-system.md — runtime UI system.
  • guides/video-playback.md — video playback component.

design/ — design rationale & roadmap docs (cited from source for why)

  • design/water-ocean.md — design record for the shipped water/FFT-ocean system. Cited by ~57 code comments via bare water-ocean.md §X.Y — keep this basename AND the section numbering stable; add new sections at the end. Open work lives in issues #1033-#1035, not here.
  • design/animation-retargeting.md — animation retargeting (humanoid bone roles, rebasing).
  • design/locomotion.md — character locomotion (issue #631).
  • design/soundgraph-metasounds.md — SoundGraph / MetaSounds-style audio graph refactor.
  • design/restir-gi-reconnection-shift.md — ReSTIR GI (#1169): the measure convention, the reconnection shift and its Jacobian, the DDGI hand-off, and why the DI chain is not renameable. Cited from source as restir-gi-reconnection-shift.md §X — keep the section numbering stable.

Roadmap docs describe intended/future work — verify "doneness" against the code, not these files.

process/ — how we run the project

  • process/issue-scoring.md — the rubric for rating issues/tasks (WSJF-derived, engine-tuned: Capability/Craft/Stability/Decay over Effort, plus Learning/Fun). Drives /start-work task picking; raw axes live in an olo-score block in each issue body, ranked on demand by scripts/issue_scores.py (nothing derived is stored).
  • process/task-loop.md — the worker-session contract: what a session started from HANDOVER.md does, from implementing through self-review, PR, CI and CodeRabbit, to a green thread-clean PR. Absorbed the former /finish-pr and /pr-status commands. Stops short of merging.

The three workflow slash commands live in .claude/commands/ and are versioned with the repo because they reference repo content: /start-work (pick + scaffold), /cleanup-worktree (reclaim merged worktrees, heal the registry), /resume-worktrees (reopen windows).

analysis/ — quality & code-health reports

ops/ — build & deployment

adr/ — architecture decision records

bug-investigations/ — postmortems & deep-dives