Page format

The step-by-step workflow for a new topic is in WRITING.md. This file is the format.

The goal is a good first implementation and an honest map of the options — not the final word. Write what is common and proven; mark opinions and typical values as such ("typically", "start at ~0.1 s") rather than stating them as rules.

Rules

  1. One folder per topic, in its category folder, kebab-case: rendering/outlines/README.md, with img/ and demo/ beside it.
  2. A topic is a problem, a technique is a solution. "Outlines" is a topic; "inverted hull" is a technique. If a technique grows beyond ~40 lines, give it its own file and link it from the topic.
  3. Short. A reader should be able to pick a technique in two minutes. Enough to implement from, not a tutorial. Link out for depth.
  4. Engine-agnostic. Describe the idea (passes, data, math). Put engine specifics in an Engine notes line, only when they save real pain.
  5. Same fields for every technique, so they compare. Leave a field out rather than pad it.
  6. Say what it looks like. One line of visual/feel description beats a paragraph of theory.
  7. Name a baseline — the good one, not the simplest one. The baseline is what a competent team would ship today: good-looking (or good-feeling) and fast. Not the most basic technique. List cheaper fallbacks separately, with when to use them (low-end targets, tiny scope).
  8. Cite real, public uses (shipped games, engines, papers, talks) under Seen in / References. No local file paths, machine-specific addresses or private project code.

Topic sections

At a glance (table) → one section per technique (fields below) → In game design (what it's for, how games layer variants, when it's on, accessibility, art-direction angle) → Baseline → Related → References.

Fields

Field What goes in it
Looks like What the player sees / feels.
How 2–5 bullets: the core steps.
Strong Where it wins.
Weak Where it breaks, artefacts, failure cases.
Needs Prerequisites: data (depth, normals, stencil), systems, math, authoring work.
Cost Rough runtime + authoring cost: low / med / high with a reason.
Variants Derivations and knobs worth knowing (short bullets, can link).
Seen in Shipped games, engines or public projects that use it. Never local paths or private project files.
Reference code Link to the technique's file in demo/.

Images

Images are encouraged: one picture of what a technique looks like often replaces a paragraph. They must be real in-game / in-engine renders, never hand-drawn or script-generated diagrams.

Sources, in order of preference:

  1. Our reference demos — captures from the demo that implements the technique in this repo. List each shot in demo/shots.json (file, URL query) and run npm run capture, so every image can be regenerated. Clips add "seconds": they're captured as MP4 (H.264, 720p30) plus a still poster .webp of the same name. Each image is one bare render of one thing: no collages, split screens, side-by-sides or overlays, and no other technique's effect mixed in. Show comparisons as separate images.
  2. The web — screenshots from shipped games, talks, papers or articles. Link to the source and credit it under the image. Only copy the file into the repo if its license allows; otherwise embed the external URL or just link it.

Format:

Demos

One demo per topic in <category>/<topic>/demo/: index.html, main.js (scene + UI), one file per technique (that's what docs link to), shots.json. Shared setup lives in engine/ (renderer + capture/record, stage, pass helpers).

Topic frontmatter

---
topic: Outlines
category: rendering
tags: [stylised, post-process, selection]
status: stub | draft | reviewed
---

Tags are free-form but reuse existing ones; they are how agents search across categories.

Adding a category

Only when three or more topics would not fit anywhere else. Add it to the table in README.md.