CODEQUEST.toml is an optional, versioned cartridge manifest at the root of a
git repository. The application reads and validates it when the repository is
inserted, compiles its scene graph, and passes the resulting finite-state
machine to the Bevy engine. Invalid configuration refuses the cartridge with an
INVALID CODEQUEST.toml error. Unknown fields are rejected so misspellings
cannot silently change a game.
The complete executable v2 example is
docs/examples/CODEQUEST.toml. The Rust tests and
the game-designer validator both parse it, so the example and engine contract
cannot drift without failing verification.
| Field | Runtime behavior |
|---|---|
schema_version |
2 enables executable scenes and transitions. Legacy schema 1 remains readable as metadata. |
game.type |
Selects the trusted quiz or quest gameplay systems and limits which scene handlers are valid. |
game.title |
Overrides the repository-directory cartridge title when present. |
game.summary |
Validated and retained as design metadata. |
game.start_scene |
Names the first scene in the executable v2 machine. |
scenes[].handler |
Selects a trusted Rust scene implementation. It does not load code from the cartridge. |
scenes[].transitions |
Routes semantic engine signals to target scenes, with optional timing gates. |
mechanics |
Validated design requirements referenced by scenes; they do not dynamically create code. |
art |
Validated production requirements. An optional typed template selects a safe renderer asset built into CODE QUEST; entries without it remain metadata. There is no audio template: sound is derived by the engine from game state for each trusted handler, and kind = "audio" entries record its production requirements. |
Without CODEQUEST.toml, the engine builds the same finite-state machine from
its quiz or quest template. A repository with CODEQUEST.md uses the legacy
quest-battle detection; any other repository uses quiz mode. A manifest takes
precedence over that detection.
The manifest is data only. It cannot provide JavaScript, load engine plugins, replace the game loop, or execute arbitrary conditions. Quest commands continue to come from the engine's existing repository inspection.
schema_version = 2
[game]
type = "quiz" # required: "quiz" or "quest"
title = "MY CODE QUEST" # optional
summary = "What players do." # optional
start_scene = "title" # required in v2Scenes, mechanics, and art are arrays of tables. IDs must be non-empty and unique within their array. Every reference must resolve.
A v2 scene separates three concerns:
kindis author-facing classification such astitle,challenge, orreward.handlerchooses a built-in renderer and gameplay behavior.transitionssay where the machine goes when that handler emits a semantic signal.
This means a designer can reorder scenes, create loops, insert another instance of a handler, or change timing without adding another hard-coded screen enum.
[[scenes]]
id = "quiz"
title = "Quiz"
kind = "challenge"
handler = "concept-quiz"
summary = "Test one durable concept about the project."
mechanics = ["answer-question"]
art = ["quiz-frame"]
[[scenes.transitions]]
signal = "needs-question"
target = "oracle"
[[scenes.transitions]]
signal = "hearts-empty"
target = "game-over"Each signal may appear at most once per scene. A transition may set
after_ticks to prevent that signal from advancing until the scene has been
active for the given number of 60 fps ticks. Handlers that draw a continue or
skip prompt (repository-credits, opening-fanfare, and level-up) show it
only once the gated signal would be accepted, so after_ticks also times the
prompt. The elapsed signal is generated by the scene clock and always
requires after_ticks:
[[scenes.transitions]]
signal = "continue"
target = "title"
after_ticks = 90
[[scenes.transitions]]
signal = "elapsed"
target = "title"
after_ticks = 330Cycles and branches are allowed. Every declared scene must be reachable from
game.start_scene; terminal scenes may omit transitions.
| Handler | Game family | Signals it can emit |
|---|---|---|
repository-credits |
shared | continue, elapsed |
opening-fanfare |
shared | continue, elapsed |
title |
shared | continue |
quiz-menu |
quiz | new-run, open-codex, back |
character-creation |
quiz | hero-ready, back |
oracle |
quiz | questions-ready, back |
concept-quiz |
quiz | needs-question, batch-complete, hearts-empty, back |
level-up |
quiz | questions-ready, needs-question |
game-over |
quiz | replay |
codex |
quiz | back |
quest-select |
quest | quest-selected, back |
battle |
quest | victory, defeat |
victory |
quest | continue |
defeat |
quest | continue |
A transition using a signal that its handler cannot emit is rejected at cartridge load time. Quiz-only handlers are rejected in quest games and vice versa.
The quiz menu's second option follows its routes. When the current menu scene
declares an open-codex transition, that option reads OPEN THE CODEX and
emits open-codex; otherwise it keeps RETURN TO TITLE and emits back. B
always emits back, so a manifest without a Codex route behaves exactly as it
did before the Codex existed. With the route, the menu subtitle also summarizes
the lesson journal (for example LESSONS 07 REVIEW 02).
The codex handler is a lesson journal that never changes mastery or the
question deck. Its first page shows every
concept lens with three mastery runes that wake at exactly 1, 3, and 5 pieces
of evidence (first-try successes plus misses redeemed in a later launch) and an
amber count of that lens's lessons awaiting review. Rune II also needs 60% of
the lens's newest five graded answers correct, and rune III 80% plus no pending
review; a rune those gates hold back is drawn cracked, and the totals row then
reads CRACKED = REVIEW DUE while a cracked lens has a pending review, or
CRACKED = LOW ACCURACY while only recent accuracy holds its runes back.
Each later page shows one lesson, oldest first: lens, question, and whether a
review is pending; a learned page adds the correct answer and rationale. A
pending lesson, or a relearned lesson whose spaced check is still due, is a
self-test: it shows the player's wrong pick and the misconception it reveals,
and seals the answer. A reveals a sealed lesson's answer; revealing before the
review or spaced check counts the next correct answer as relearning, which is
saved but is not evidence. Left, Up, and L page back;
Right, Down, and R page forward; paging wraps between the mastery page and the
newest lesson and seals the page again. A and Start are inactive on every
other page, and B emits back. An empty journal renders an explicit
NO LESSONS YET state. The built-in quiz template (used without a manifest)
includes quiz-menu → codex → quiz-menu.
The concept-quiz handler shows each question's choices in a stable shuffled
order. Committing an answer opens a lesson card with the committed choice's
rationale and, after a miss, the correct answer's rationale; the card ignores
input for 45 ticks and then waits for A or Start. A survivable miss returns as a
review copy after exactly three other questions; a copy that would land past
the batch end joins the next batch instead, so batch-complete is emitted on
time and the retry gap never shrinks. These timings are engine behavior, not
manifest fields.
A mechanic captures reusable rules and feedback. These fields are currently
validated design metadata; inputs, rules, and feedback default to empty
lists.
[[mechanics]]
id = "answer-question"
summary = "Choose one of four answers."
inputs = ["d-pad", "a", "b"]
rules = ["Exactly one answer is correct.", "A wrong answer costs one heart."]
feedback = ["Reveal correctness immediately."]Art entries name production needs. kind is author-defined, requirements
defaults to an empty list, and the optional template field selects a trusted
visual template compiled into the application. A cartridge can choose and reuse
these templates, but cannot provide executable drawing code or read arbitrary
asset paths.
[[art]]
id = "quiz-frame"
kind = "ui"
summary = "Question, answer, score, streak, and heart presentation."
template = "oracle-trial"
requirements = ["Fits 240x160.", "Keeps focus visible."]The built-in Oracle template catalog is:
oracle-chronicleoracle-awakeningoracle-titleoracle-menuoracle-atelieroracle-herooracle-sanctumoracle-trialoracle-ascensionoracle-aftermathoracle-progressionoracle-codex
Scene handlers activate a visual template only when the current scene references
the corresponding art entry. oracle-codex composites the Codex mastery page on
the dormant archive plate and each lesson page on the trial-chamber plate; a
Codex scene without it uses the plain legacy renderer. oracle-hero and
oracle-progression are shared
systems: once selected by the cartridge, they preserve the chosen hero and
Initiate/Adept/Oracle-bound visual tier across the scenes that use them. Unknown
template names are rejected instead of falling back silently.
Renderer changes can emit all fourteen reachable Oracle scenes—including the five-beat opening story and the Codex mastery, sealed-lesson, and lesson layouts—as native 240×160 PPM files for visual review without packaging the application:
CQA_VISUAL_PREVIEW_DIR=/tmp/codequest-previews \
cargo test --manifest-path src-tauri/Cargo.toml \
oracle_templates_produce_nine_distinct_native_scene_frames --libWith the same variable, lesson_cards_render_the_misconception_and_the_answer
writes the quiz lesson-card states, and
dogfood_manifest_routes_its_menu_into_the_templated_codex,
empty_codex_says_no_lessons_yet_and_cannot_page, and
codex_lesson_pages_show_the_answer_and_mark_outstanding_reviews write the
journal menu and the remaining Codex states. The remaining writers cover newer
surfaces:
the_header_counts_the_batch_and_labels_the_returning_retry: batch progress, theBACK INnote, and theRETRYheader, templated and legacy.waking_a_lens_rune_banners_blinks_and_sounds_above_insight: the lens-rune wake banner.the_legacy_lesson_footer_carries_a_woken_rune_iii_banner_readably: the legacy lesson footer under a rune III banner.codex_mastery_runes_crack_at_the_exact_gate_breakpoints_on_the_rendered_frameandthe_lesson_footer_meter_shows_a_cracked_rune_for_an_open_miss: cracked mastery runes on the Codex and the trial lesson footer.the_oracle_line_stays_contained_disjoint_and_readable: the Oracle recall and failure line, templated and legacy.recalled_lessons_are_written_in_but_stay_static_under_reduced_motion: a recalled lesson typing in on the Oracle line.the_result_prompt_stays_lit_on_every_frame: the Ascension and Aftermath learning debriefs, templated and legacy.
Schema v1 remains supported so existing cartridges continue to load. In v1,
scenes use next = ["scene-id"]; the graph, mechanics, and art are validated
and retained as metadata, while the engine uses its built-in machine template.
V1 cannot use handler or transitions. V2 cannot use next.
schema_versionmust be1or2.game.typemust bequizorquest.- IDs cannot be blank or duplicated within their category.
- All scene, mechanic, and art references must resolve.
art[].template, when present, must name a built-in visual template.- Every v2 scene must be reachable from
game.start_scene. - V2 handlers must belong to the selected game family, transitions must use a signal their handler emits, and duplicate signal routes are rejected.
elapsedtransitions requireafter_ticks.- Optional title/summary text cannot be blank when present. Required display and summary fields cannot be blank.
- Unknown keys at every level are errors.
Adding a new field, handler, signal, or game type is a contract decision and must arrive with engine behavior, an updated example, and parser tests.