przygody-pana-cegly/CONTEXT.md

Mr. Brick Adventures

A 2D platformer. This context covers player state and progression — what the player has, what they have done, and at what point each of those becomes permanent. Gameplay behaviour (movement, combat, hazards) lives in the composable components and is deliberately outside this context.

Language

Scopes

Three lifetimes. Every fact in this context belongs to exactly one.

Attempt: One try at a level, from entering it to either completing it or losing a life. Holds a ledger of everything that happened during the try — coins found, coins spent, skills bought. Discarded whole if the player dies. Avoid: Session, run, life

Playthrough: One game from New Game until game over, identified by a PlaythroughId. Holds lives, banked coins, owned skills and their levels, campaign position, and which levels it has cleared. Several exist at once and the player picks between them. Avoid: Save, save slot, progress, game, run

Profile: Everything shared across all Playthroughs, one per installation. Achievements, best time per Level, and lifetime statistics. Never reset by starting a new Playthrough. Avoid: Global state, meta, persistent data, account

Operations

Settle: Resolving an ended Attempt against the Playthrough — Commit it on a First Clear, Discard it otherwise. Settling is the only way an Attempt affects a Playthrough, and it decides First Clear versus Replay itself rather than being told which one happened. Avoid: Apply, resolve, finalise

Commit: Applying an Attempt's ledger to the Playthrough. Only a First Clear commits — nothing else, ever. Avoid: Save, persist, flush, sync

First Clear: Completing a Level this Playthrough has not cleared before. The only event that commits an Attempt and advances campaign position. Avoid: Level complete, finish (both ambiguous — they also describe a Replay)

Replay: Completing a Level this Playthrough has already cleared. Records Best Time, achievements and statistics to the Profile; commits nothing and never advances campaign position. Avoid: Practice, retry, second run

Bank: The coins a Playthrough holds, as opposed to coins found in the current Attempt. Coins are banked by committing, never on pickup. Avoid: Total coins, saved coins

Discard: Throwing away an Attempt's ledger — on death, or at the end of a Replay. Purchases made during the Attempt are undone by discarding, not refunded; under the ledger they never happened. Avoid: Reset, rollback, revert

Things

Level: One playable stage, identified by a stable LevelId — never by position in a list. Knows its scene and display name. Ids must survive inserting and reordering levels, because Playthroughs and Best Times both reference them. Avoid: Stage, scene, level index

Campaign: The authored ordering of Levels that defines progression — which Level is first, and what follows a given one. One Campaign is shared by every Playthrough: it is authored data, not per-Playthrough state, and it carries no scene or presentation detail. Avoid: Level list, level order, world, chapter

Cleared Levels: The Levels a Playthrough has completed at least once. Gates both campaign progression and level select; whether a Level is reachable is computed from this, never stored alongside it. Avoid: Unlocked levels, completed levels, available levels

Skill: An ability the player can own and upgrade. SkillData is the authored asset describing one (name, icon, upgrade table) and is immutable at runtime; the level the player has reached in it belongs to the Playthrough. Avoid: Ability, power-up, upgrade (for the skill itself)

Movement Ability: A composable behaviour attached to the player controller (jump, wall-jump, gravity). Unrelated to Skill — authored per movement preset, not owned, not upgraded, not persisted. Avoid: Skill, movement skill

Best Time: The fastest recorded completion of a Level, from a First Clear or a Replay alike. Belongs to the Profile, so it survives New Game and is shared by every Playthrough. Stored alongside, but distinct from, the ghost replay frames that produced it. Avoid: Personal best, high score, record

Rules

• Reads may cross scopes freely — affordability spans Attempt and Playthrough. Writes must not.
• Derived facts are computed, never stored. Level reachability is derived from Cleared Levels; total coins from Attempt plus Bank. Storing either alongside its source creates the second source of truth this context exists to prevent.
• Achievements are mirrored to Steam, which is per-account and cannot be un-earned. That is why they are Profile and not Playthrough: a per-Playthrough achievement list would contradict Steam permanently.
• Nothing in this context may reference Godot. Its correctness must be checkable without a scene tree.