Guide Style

Docs style guide

The rules every page of this wiki obeys. Written in the voice it prescribes; reviewed like code, because it documents code.

Voice

Second person, imperative, present tense. "Register the species, then override its front sprite." No marketing adjectives. The reader will implement without hand-holding — the same audience as the engine docs.

Cite your source

Prose that states an engine fact cites the file (src/mods/Loader.lua), and a claim about vanilla behavior cites the parity ledger (docs/behavior-porting-notes.md). Reference pages carry the emit/call site per entry. This keeps the docs auditable against the code.

Names

Record fields are camelCase (baseStats, catchRate) — exactly as the importer emits them. snake_case appears only in manifest keys (optional_dependencies, game_version) and registry names (map_scripts). See Data Model.

Vocabulary is fixed: "registry" not "database", "record" for a registry value, "merge semantics" (record/deep/compose), "mod API 2", "manifest v2", "profile", "asset transform", "fingerprint", "quarantine", "tri-ledger", "modkit".

Snippet tags

Every fenced Lua block is one of three kinds, tagged by an HTML comment immediately above the fence:

• <!-- snippet: run --> — executable as a mod entry chunk against the merged base dataset; the snippet runner asserts it does not error. run blocks on one page execute in page order against a shared harness, so a later block may use an id an earlier block registered. Use it for main.lua bodies, registry calls, and event/hook registrations.
• <!-- snippet: expect --> — a run block whose captured output is compared against the ```text block that follows it.
• <!-- snippet: illustrative --> — shown for shape only, never executed: signature listings, elided fragments ({ ... }), transform recipes, deliberately wrong forms, and examples whose ids live in another page's mod.

An untagged Lua block defaults to run, and the runner fails on an untagged block it cannot execute — an unexecutable example must say so explicitly. This is the mechanism that retired the phantom-event class of doc bug (an example subscribing to an event no engine code emits): the buggy example was an untagged, unexecuted block.

Formatting

Hard-wrap prose near 80 columns. #/## headings, fenced blocks with language tags, pipe tables, ASCII diagrams for pipelines. One concept per concepts page; one task per cookbook recipe.

CHange + Doc

Every change that adds or alters an extension point lands, in the same change, with its schema/catalog entry updated, the regenerated reference page, and any affected hand-authored page updated with a tagged snippet. The generated registry reference is never edited by hand — change src/mods/Schemas.lua and regenerate.