architecture & patterns

7 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Three-layer narrative game architecture

Narrative game systems use three layers: Presentation (UI nodes, scenes), Logic (parser, world_state, resolver — pure code), and Content (JSON, Yarn — data only, non-programmer editable). The Content layer must never contain code. The Logic layer must never contain hardcoded story. The Presentation layer must never contain state.

WorldState as single source of truth

The WorldState class serves as the single source of truth for runtime game data. It tracks: time_minutes (int), day (int), current_room (string), item_locations (dictionary mapping location_key to item_id arrays), flags (dictionary mapping flag_id to bool/string), player_stats (dictionary), npc_stats (dictionary), and diary_entries (array). WorldState should provide to_dict() for saving and static from_dict(d) for loading. Keep methods as either query methods (get_*) that do not mutate state, or mutation methods (set_*, adjust_*) that signal emit on change.

Text parser pipeline for narrative games

A text parser for narrative games follows this pipeline: input string → tokenize (lowercase, split, strip punctuation) → canonicalize (map synonyms to canonical forms, e.g., 'grab' → 'take', 'север' → 'north') → match verb to grammar pattern → extract noun phrases → resolve nouns to items in world with disambiguation if multiple match → return Intent with verb, target, instrument, modifier → ActionResolver executes intent and returns ActionResult with text, time_cost, and side_effects.

Moral axes for choice consequences in branching narratives

For deeply branching games with meaningful consequences, model 3–4 hidden moral axes tracked as integers from -100 to +100. Example axes: tyrant_democrat, isolationist_open, pragmatic_idealist, loyal_critic. Player choices nudge these axes by increments. NPC compatibility and reactions depend on axis values. Game endings branch on final axis values and world state flags.

Auto-populated diary system for narrative games

Every significant action should log an entry to a diary that is auto-populated from gameplay. Use world.add_diary_entry(text, category) with the event description and category (e.g., 'discovery', 'pride'). Display diary entries by day and filterable by category. The player never types — the diary is entirely generated from mechanical systems.

Survival needs system with tick-based resources

Survival needs (hunger, thirst, health) are implemented as shrinking-bar resources that tick over time. Use constants like HUNGER_PER_HOUR and HUNGER_DEATH threshold. In a tick() method, adjust stats by minutes elapsed. When resources cross death thresholds, apply damage or trigger special events. Display resource values as emotional text descriptions ('сыт', 'желудок шумит', 'сильно хочется есть', 'невыносимый голод') instead of raw numbers for better player experience.

Companion as first-class game subject

A companion character like Pride is tracked as first-class state: pride_present (bool), pride_room (string), and pride_stats (dictionary with keys: hunger, thirst, bladder, bowel, attention, health, bond). Bond grows from player care actions and drops from neglect. High bond unlocks companion abilities ('pride sniff', 'pride bring'). Low bond causes the companion to refuse to follow. Companion death triggers special ending conditions and should be saveable via pride_present = false flag, affecting dialogue everywhere.

Give your agent this brain