Skip to content

Latest commit

 

History

History
283 lines (238 loc) · 12.2 KB

codequest-toml.md

File metadata and controls

283 lines (238 loc) · 12.2 KB

CODEQUEST.toml contract

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.

Runtime support

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.

Top-level contract

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 v2

Scenes, mechanics, and art are arrays of tables. IDs must be non-empty and unique within their array. Every reference must resolve.

Executable scenes

A v2 scene separates three concerns:

  • kind is author-facing classification such as title, challenge, or reward.
  • handler chooses a built-in renderer and gameplay behavior.
  • transitions say 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 = 330

Cycles and branches are allowed. Every declared scene must be reachable from game.start_scene; terminal scenes may omit transitions.

Handlers and signals

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.

Mechanics

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 requirements

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-chronicle
  • oracle-awakening
  • oracle-title
  • oracle-menu
  • oracle-atelier
  • oracle-hero
  • oracle-sanctum
  • oracle-trial
  • oracle-ascension
  • oracle-aftermath
  • oracle-progression
  • oracle-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 --lib

With 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, the BACK IN note, and the RETRY header, 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_frame and the_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 compatibility

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.

Validation rules

  • schema_version must be 1 or 2.
  • game.type must be quiz or quest.
  • 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.
  • elapsed transitions require after_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.