Writing a topic page

How a topic goes from nothing to a finished page with a playable demo. Each phase ends with a concrete result; the page's status tracks where it is. Format rules live in CONTRIBUTING.md; this is the workflow.

1. Research: find references, see what's common

• Collect sources first: GDC/SIGGRAPH talks, papers, engine docs (Unreal, Unity, Godot), well-known articles, and shipped games that use it (breakdowns, frame analyses). Note the link and one line on what each adds.
• Map the techniques: list every approach you find, then group them. Two sources with different names for the same idea are one technique; one idea done with two algorithms may be one technique with two variants (e.g. mask dilation vs jump flood: same outline, brute force vs distance field).
• Find what's common, not what's novel: which approach do most shipped games use, which is the textbook default, which is the modern upgrade. The page is a starting point for prototypes, not a survey of papers.
• Look for the game-design side: what the effect is for in games, how games combine variants (e.g. art-style line art + gameplay highlight + x-ray), when it's on, accessibility concerns.

2. Rough draft

• Copy _template.md to <category>/<topic>/README.md, fill the frontmatter (status: stub), add it to the index in README.md.
• Write the intro (the problem, what a solution looks like), the At a glance table, and one section per technique with a rough Looks like / How / Strong / Weak. Short and possibly wrong is fine here.
• Put a first guess at the Baseline, and bullets for In game design.

3. Technical pass

For each technique, go deeper until you could implement it:

• How: the actual passes, buffers and math; what runs per pixel / per object / per frame.
• Needs: data and features it depends on (depth, normals, MRT, compute, smoothed normals, authoring).
• Cost: what scales with what (resolution, width, light count, object count). Rough numbers beat adjectives.
• Failure modes: where it breaks and why (grazing angles, hard normals, thin geometry, aliasing, occlusion, temporal ghosting). These become the most useful images later.
• Variants worth knowing, and cross-check claims against at least one source.

4. Complete draft

• Fill every field for every technique; move depth that doesn't fit into links under References.
• Choose the baseline: the good-looking and fast option a competent team ships today, not the most basic one. List cheaper fallbacks with when they make sense.
• Write In game design: what the technique is for, which variants play which role, when each is on, how it reads to the player, accessibility, art-direction angle.
• Set status: draft.

5. Implement versions

Build the demo in <category>/<topic>/demo/ on the shared engine (engine/):

• Baseline first, then each alternative; one file per technique, commented with the same steps as the page's How. Readable over clever: it is a rough reference, not production code.
• A scene that shows weaknesses: include the cases from the failure-mode list (hard edges, flat faces, occluders, grazing floors, distant detail…), so images teach trade-offs.
• Debug views for multi-part techniques (each buffer and each term on its own). Check every part works on its own; a combined image can hide a part that silently does nothing.
• Every tunable in the GUI and overridable by URL; every technique reachable with ?t=<technique>.
• Captures in demo/shots.json: one per technique, plus:
  • zooms (zoom=6&focus=x,y) where pixels matter: anti-aliasing, line quality, seams;
  • failure cases (a camera or setting that triggers the weakness), next to the fix;
  • clips (seconds) for anything about motion or feel: MP4 + poster, played in place on the site. Each image is one bare render of one thing: no collages, split screens or other techniques mixed in.
• Run npm run capture -- <topic> and look at every image (for clips, tile a few frames). Iterate until each image clearly shows its point.

6. Update the page from the implementation

Implementing always teaches something; put it back into the page:

• Correct anything the demo proved wrong or incomplete (a term that didn't matter, a cost that surprised you, a failure mode you didn't expect, a variant that turned out to be the same technique).
• Add the images: each followed by [▶ Play](demo/?<its shot query>) so it is playable on the site. Zooms and failure cases go right where the page claims them.
• Add Reference code links per technique, and practical numbers from the demo (defaults that looked right).
• Revisit the Baseline and In game design with what you saw.
• Set status: reviewed.

7. Final check

• npm run dev, open the page: every image loads, every ▶ Play opens the matching state, anchors work.
• Links and images resolve in plain Markdown too (GitHub / editor view).
• No local paths, no private project references, credits for any external image or asset.
• Index row in README.md up to date (techniques, status).