# Refrain Garden — Game Design Document v0.1

## Source and Truth Labels

This document is the authoritative player-facing contract for concept `refrain-garden`. The source
brief and mobile/no-visual-novel constraints are CONFIRMED. Rules, scope, content counts, UX targets,
and technical budgets are DESIGN TARGETS until prototype or player evidence exists. Originality,
demand, retention, acquisition cost, conversion, and revenue are UNKNOWN here and belong only to
later gates. The defining promise is: draw one breeze, keep it forever, and solve with every breeze
returning together.

## Player Promise and Audience

Refrain Garden is a portrait deterministic motion-composition puzzle for players who enjoy compact
spatial planning, visible cause and effect, and solutions that become small performances. The player
conducts living wind through a moonlit garden. A board lasts 45–120 seconds. The first session must
deliver one real ribbon, one complete four-beat breath, and one flower bloom within 90 seconds. The
primary audience is mobile puzzle players aged 13+ who prefer calm planning over timers, dexterity,
randomness, or long tutorials.

## Fantasy, Promise, Audience, and Genre

Genre: deterministic spatial motion-composition puzzle. Fantasy: awaken a sleeping garden by
conducting permanent currents. `ENV-GARDEN` is the playable cell garden, `ENV-NIGHT` is the quiet
non-interactive surround, and `ENV-HERBARIUM` holds completed living dioramas. The store promise is
not generic line drawing: every committed gesture becomes a rule that returns in all later turns.

## Design Pillars and Non-Goals

1. `P-REFRAIN`: every committed `M-RIBBON` must replay on every later `M-BREATH`; no move is disposable.
2. `P-PREVIEW`: `M-PREVIEW` must reveal all four beats, vector combinations, blocks, blooms, and fatal outcomes before commitment.
3. `P-COMPOSE`: later decisions must interact materially with earlier ribbons through reinforcement, cancellation, or confluence.
4. `P-ONE-THUMB`: core play uses one portrait finger with large border anchors and no camera manipulation.
5. `P-FAIR`: identical states and ribbon paths resolve identically; no randomness, hidden priority, timer, or paid reasoning bypass exists.
6. `P-LIVING-SCORE`: the solved board must replay as a readable garden choreography, not merely display a completion badge.

Non-goals are visual-novel structure, dialogue choices, twitch steering, tilt input, real-time combat,
decorative gardening, match-three, random wind, physics ambiguity, base building, gacha, multiplayer,
or a prototype created before the accepted Art Bible and manual Codex design lock.

## Design Pillars

`P-REFRAIN`, `P-PREVIEW`, `P-COMPOSE`, `P-ONE-THUMB`, `P-FAIR`, and `P-LIVING-SCORE` are release
invariants. If the best levels are solvable as isolated route drawings, if prior ribbons can be
ignored, or if the preview cannot exactly predict resolution, the design returns to the GDD rather
than being disguised with additional art or metagame rewards.

## Player-Facing Fingerprint

- Input: drag one snapped `M-RIBBON` between two enabled `E-ANCHOR` sockets, inspect `M-PREVIEW`, then release to commit or return to origin to cancel.
- Decision: add a permanent vector field that advances one seed while every earlier field replays safely for all remaining seeds.
- Objective: land each glyph-marked `E-SEED` on its matching `E-FLOWER` at the end of a four-beat breath within the ribbon budget.
- Failure: a seed enters `E-THORN`, exits the garden, collides or swaps with another seed, reaches a numbered flower out of order, or remains after the final ribbon.
- State change: every commit adds a permanent current, advances all active seeds simultaneously for four beats, removes matched seeds, and blooms flowers.
- Progression: thirty authored boards across five beds add multiple seeds, intersections, stones, beat gates, and ordered blooms without adding input verbs.
- Content: authored integer-grid boards produced from anchors, paths, vectors, entities, blockers, gates, budgets, and canonical solutions.
- Presentation: portrait top-down tactile night garden with indigo beds, pale anchors, cyan current ribbons, glyph-marked seeds, coral hazards, and warm bloom halos.
- Metagame: solved current scores restore pages in `ENV-HERBARIUM`; there are no power upgrades.

## Core Loop and Player Verbs

Read seeds, flowers, existing ribbons, four-beat timing, and remaining budget → press an enabled
`E-ANCHOR` → drag a snapped path through legal cells → inspect the complete `M-PREVIEW` timeline →
return to origin to cancel or release on another anchor to commit → observe `M-BREATH` resolve four
beats → continue, enter `ST-SUCCESS`, or enter `ST-FAILURE` → retry or advance.

Legal gameplay verbs are inspect, press anchor, drag ribbon, cancel before release, commit, scrub the
preview beats, pause, retry, and advance. There is no post-commit undo in the base contract because
accumulation is the central consequence. `UI-TIMELINE` exposes beats one through four;
`UI-TOPBAR` exposes bed, board, seeds, and ribbons; `UI-PRIMARY` advances or retries; `UI-MODAL`
owns pause and confirmations.

## Camera, Dimension, and Controls

The design target is portrait top-down 2D or shallow 2.5D; Phase 05 must select the cheapest
justified implementation after the market verdict. Simulation uses a 6×9 maximum integer cell grid
inside a 360×800 logical canvas. `ENV-GARDEN` stays fully visible between `UI-TOPBAR` and the lower
thumb zone. One-finger drag begins only on an enabled 56×56 logical border anchor. The sampled path
snaps to orthogonally adjacent cell centers. The player may backtrack over the last segment while
dragging but may not cross the same cell twice. Gameplay never requires pan, zoom, rotation,
multi-touch, device tilt, or perspective-dependent adjacency.

## Deterministic Rules

1. A level loads an integer grid from 3×4 through 6×9 cells, a set of border `E-ANCHOR` sockets, active seeds, flowers, hazards, blockers, optional gates, a ribbon budget, and a canonical solution.
2. Every seed and flower carries one of four redundant identities: circle, triangle, square, or diamond. Shape is authoritative; color is secondary.
3. A candidate ribbon starts at one enabled anchor, visits an ordered list of orthogonally adjacent non-stone cells, and ends at a different enabled anchor. It must visit 2–12 cells, may not repeat a cell, and may not reuse an already occupied directed segment.
4. At most two ribbon vectors may occupy one cell. A third vector makes the preview invalid. Crossing is permitted only when the shared cell contains no stone, thorn, flower, or gate.
5. Each visited cell receives the cardinal vector leading to the ribbon's next cell. The final cell receives the vector pointing from that cell through the exit anchor. The entry anchor itself contributes no off-grid motion.
6. During `M-PREVIEW`, the candidate is evaluated together with all committed ribbons from the exact current seed state. The preview exposes start state and beats one through four. Nothing mutates before release.
7. On each beat, every active seed reads every ribbon vector in its current cell. Vector components are summed independently, then each nonzero component is clamped to -1 or +1. Zero plus zero means stay; one nonzero axis means one orthogonal cell; two nonzero axes mean one diagonal cell.
8. Equal opposing components cancel. Reinforcing components still move only one cell. Thus two east vectors equal one east step; east plus west equals no step; east plus north equals one northeast step.
9. All seed intents are calculated from the same pre-beat state. Resolution is simultaneous and does not depend on entity iteration order.
10. A destination outside the grid or containing `E-THORN` causes immediate `ST-FAILURE`. The decisive seed, vector sources, origin, and destination remain visible.
11. `E-STONE` is an immovable blocker. A seed intending to enter stone remains in its origin for that beat; this is safe and visible in preview. A ribbon may not visit a stone cell.
12. `E-GATE` lies on one directed boundary and declares one or more open beat numbers. Crossing it on an open beat succeeds; crossing it while closed leaves the seed at origin. The preview shows the closed gate and blocked vector.
13. If two seeds intend the same destination, or intend to swap origins, the board fails before either movement is applied. A seed moving into a cell vacated by another seed in the same direction is legal.
14. After safe intent validation, every moving seed reaches its destination simultaneously. Seeds with zero or blocked intent remain in place.
15. Flowers do not stop seeds during beats one through three. At the end of beat four, a seed on its matching flower blooms: the seed becomes inactive, the flower becomes completed, and neither participates in later breaths.
16. A seed on a nonmatching flower at the end of beat four remains active. In ordered-bloom levels, a seed matching a numbered flower when another lower number is incomplete causes `ST-FAILURE`; the number and next valid flower are shown in preview.
17. A committed ribbon is appended permanently before the breath begins, the ribbon budget decrements exactly once, and the four-beat sequence shown by `M-PREVIEW` becomes authoritative.
18. If all flowers are completed after beat four, enter `ST-SUCCESS`. Otherwise, if the budget is zero, enter `ST-FAILURE`. Otherwise return to `ST-ACTIVE` with all committed ribbons intact.
19. Invalid candidates—missing exit, repeated cell, illegal segment, stone cell, third vector, or disabled anchor—cannot be committed and do not consume budget.
20. Returning the drag to its entry anchor, pressing system back during drag, or releasing outside an enabled exit cancels without mutation.
21. There is no randomness. A replay is level ID plus ordered cell lists for committed ribbons. Identical replay input produces byte-identical seed, flower, ribbon, and state logs.
22. System back during `ST-ACTIVE` opens `ST-PAUSED`; back closes the top overlay; back from home requests exit. App interruption auto-pauses before another beat renders.
23. `M-RETRY` restores the authored start state, clears ribbons and timeline, and re-enables input within 500 ms.

## Preview Contract

`M-PREVIEW` is a reasoning tool, not an answer generator. It shows the exact candidate path,
existing and candidate vectors, all four seed positions, blocked steps, collisions, blooms, failure,
and final state. It does not recommend an anchor, compare alternate ribbons, show future uncreated
ribbons, or label a candidate “optimal.” The timeline can be scrubbed without animation. Fatal
previews remain commit-able so responsibility stays with the player, but release over a fatal
preview requires a 350 ms hold and displays the specific rule beside the destination.

## Failure, Consequence, and State Change

A safe commit always adds one visible ribbon, consumes one budget unit, and advances the whole seed
system through four beats. `V-PULSE` illuminates each ribbon in beat order without changing the
simulation; `V-BLOOM` uses a warm expanding glyph and paired chime; `V-THORN`, `V-EDGE`,
`V-COLLISION`, `V-ORDER`, and `V-BUDGET` use distinct silhouettes, text, and haptic patterns.
Failure freezes the decisive beat, names the exact rule, keeps earlier ribbons visible, and offers
`M-RETRY`. Success hides editing controls and replays the full committed score from the authored
start state into `ENV-HERBARIUM`.

## Progression and Content Grammar

Launch scope is 30 authored boards in five six-level beds:

1. **First Breath** — one seed, one flower, cardinal motion, cancellation, and one-ribbon boards.
2. **Crosscurrent** — multiple seeds, reinforcement, opposing cancellation, diagonal confluence, and collision avoidance.
3. **Quiet Stone** — impassable `E-STONE`, blocked intents, narrow anchors, and persistent currents that become useful only after later commits.
4. **Timed Petals** — `E-GATE` schedules, timeline scrubbing, safe waiting, and different seeds crossing one boundary on different beats.
5. **Full Chorus** — ordered flowers and combinations of every established rule, never a new player verb.

Difficulty variables are grid size, anchor set, ribbon budget, maximum path length, committed-ribbon
depth, seed count, shape distribution, thorn density, stone placement, vector intersection count,
gate schedule, solution depth, decoy-safe candidates, and bloom order. Every board must have at least
one verified solution, no more than ten initially enabled anchor pairs, and a canonical solution of
one to five ribbons. The first 18 boards must have a unique shortest solution; later boards may
permit readable alternatives. Three optional badges reward par ribbons, no canceled previews, and
timeline-free completion; badges never affect power.

The content format serializes dimensions, anchors, entities, hazards, gate schedules, budget,
tutorial callouts, canonical ribbons, and expected beat logs. A deterministic solver enumerates
bounded snapped paths, simulates exact rules, rejects duplicate normalized solutions, and estimates
branching. Thirty boards are the launch target; further beds are a post-validation possibility, not
a promise.

## State and Content Inventory

Required screen IDs are `SCR-ONBOARDING`, `SCR-HOME`, `SCR-BED-SELECT`, `SCR-GAMEPLAY`,
`SCR-PAUSE`, `SCR-SUCCESS`, `SCR-FAILURE`, `SCR-SETTINGS`, `SCR-ACCESSIBILITY`, and `SCR-LEGAL`.
Important states are `ST-FRESH`, `ST-DRAWING`, `ST-PREVIEW`, `ST-RESOLVING`, `ST-ACTIVE`,
`ST-PAUSED`, `ST-SUCCESS`, `ST-FAILURE`, and `ST-ERROR`. Mechanics are `M-RIBBON`, `M-PREVIEW`,
`M-BREATH`, `M-VECTOR`, `M-BLOOM`, and `M-RETRY`. Entities and objects are `E-SEED`, `E-FLOWER`,
`E-ANCHOR`, `E-THORN`, `E-STONE`, and `E-GATE`. Environments are `ENV-GARDEN`, `ENV-NIGHT`, and
`ENV-HERBARIUM`. This is the full launch visual inventory; another rule-bearing entity requires a
GDD revision and repeat audit.

## Difficulty, Progression, and Economy

Difficulty rises through interaction depth, not speed or visual noise. First Breath teaches one
cause per board; Crosscurrent introduces simultaneous consequences; Quiet Stone turns blocked motion
into planning; Timed Petals introduces beat reading; Full Chorus combines known rules. Completion
restores one herbarium page and awards up to three cosmetic dew seals. Seals unlock alternate
garden palettes only after accessibility validation and never alter solutions. No consumable
currency, upgrade tree, daily streak, energy, or loss aversion system exists.

## First Session and FTUE

`SCR-ONBOARDING` opens on a 3×4 garden with one circle seed, one circle flower, two anchors, and one
valid short ribbon. A hand trace demonstrates press and drag once, then disappears and waits. While
dragging, the four preview positions appear. Release performs the real deterministic breath and
blooms the flower. The result names the permanent-refrain rule, then level two starts with one
existing authored ribbon so the player sees an old current replay before drawing a new one. The
tutorial is skippable before the demonstration and replayable from settings. Hints explain one rule
or highlight eligible anchors; they never draw or commit a ribbon.

## Economy and Monetization Boundaries

The test build has no ads or purchases. A future commercial build may use one premium full-game
unlock after the first six-board bed or platform-funded catalog placement. It must not combine that
unlock with forced interstitials, sell solutions, use rewarded hints at launch, add energy, loot
boxes, streak penalties, artificial waits, manipulative scarcity, or child-targeted purchasing.
Restore purchase, regional pricing, consent, and parental gates are mandatory if commerce is added.

## Monetization Constraints

Monetization cannot change ribbon budgets, preview fidelity, path limits, vector rules, gates,
canonical solutions, or failure recovery. `UI-UNLOCK` may appear only on home after the free bed and
never on `ST-FAILURE`. Analytics and commercial SDKs default off until consent where required and
must not block offline play.

## UX, Accessibility, Audio, and VFX

Portrait safe areas reserve the platform inset plus 16 logical pixels. Interactive controls are at
least 48×48; anchors are 56×56 with a 12-pixel invisible inward extension. `A-COLOR` pairs every
seed/flower with a glyph and outline; thorns use spikes and hatch; open gates use an aperture plus
beat numeral. `A-MOTION` replaces flowing lines with four 100 ms stepped highlights and removes
background drift. `A-TEXT` supports 100%, 125%, and 150% UI type without covering the garden.
`A-HAPTIC` distinguishes valid snap, commit, bloom, and each failure family and can disable all
vibration. Screen-reader summaries describe seed cell, matching flower cell, current vector, and
gate schedule.

`UI-TOPBAR` never overlaps `ENV-GARDEN`; `UI-TIMELINE` remains below it and exposes four labeled
beats. `UI-PRIMARY` and pause sit in the lower thumb zone outside anchor paths. `UI-MODAL` traps
focus, closes with back, and keeps the frozen failure reason visible. `SCR-ACCESSIBILITY` is reachable
from first launch and settings. `ST-ERROR` preserves the board and offers retry loading or safe home.

Audio groups are music, night ambience, ribbons, blooms, failures, UI, and haptics. Each beat uses a
soft four-note pulse; combined vectors use harmony without implying strength beyond one cell.
`V-RIBBON` is a restrained cyan paper-light line; `V-PULSE` travels no faster than 300 ms per beat;
`V-BLOOM` uses one warm halo; failures use no flashing. No effect flashes more than three times per
second. Audio confirms but never replaces text, shape, or motion.

## UX and Accessibility

Drawing remains possible with either thumb. Anchor hit areas may overlap the safe border but never
the system gesture exclusion. The candidate ribbon receives a high-contrast outline and direction
chevrons; committed ribbons use numbered origin seals so their age and direction are non-color
cues. The timeline exposes “start, 1, 2, 3, 4” and can be scrubbed through buttons as an alternative
to drag. Focus order follows top bar → garden summary → anchors → timeline → primary controls.
Reduced-motion, high-contrast, glyph labels, text size, haptics, screen-reader labels, music, and
effects are independently configurable.

## Audio and VFX

`V-PULSE` is a cyan edge traveling along each ribbon with a quiet breath; `V-BLOOM` is a 350 ms
paper-light flower opening with paired chime; `V-THORN` is a coral spike outline and low double
pulse; `V-EDGE` uses an outward arrow and muted drop; `V-COLLISION` uses two intersecting glyphs;
`V-ORDER` highlights the required numeral; `V-SUCCESS` replays the score with UI hidden. Runtime
budget is 32 simultaneous particles, six ribbon meshes, one full-screen dimmer, and no mandatory
post-processing.

## Analytics and Technical Constraints

Target iOS 16+ and Android 10+ phones and tablets, 60 fps on a 2019 mid-tier device, 30 fps fallback,
under 150 MB installed, under 250 MB peak memory, and under two seconds cold-to-home after first
load. Core play is offline. Cloud save and analytics are optional adapters and may fail without
blocking play. Simulation uses integer cells, integer vectors, and ordered immutable snapshots; no
gameplay physics engine, account, server authority, or generative runtime dependency is permitted.
A replay stores level ID plus each committed ribbon's ordered cells and anchor IDs.

Local QA records tutorial start/complete/skip, level start, candidate length, preview scrub, preview
cancel, fatal-preview commit, ribbon commit, beat block, failure rule, retry, bloom, success, solution
length, elapsed time, accessibility settings, and frame-time buckets. Production telemetry requires
consent and coarse event data only. Deterministic acceptance runs must replay 10,000 solver sequences
with identical state hashes and render every required state at 360×800 and 430×932 logical portrait
reference sizes.

## Technical Constraints

The runtime contract is deterministic integer-grid simulation, offline-first play, bounded 2D assets,
replayable committed-ribbon inputs, and reproducible state hashes. Optional analytics, cloud save, and
store adapters must never become gameplay authority or block owned play.

## Risks, Falsifiers, and Acceptance Criteria

Top risks are resemblance to ordinary line-drawing puzzles, preview overload, uncontrolled path
enumeration, weak tactile clarity at intersections, repetitive content, and an artistic garden layer
that obscures vectors. Kill or redesign if at least 6 of 10 unfamiliar target players describe the
core as “just draw a path,” fewer than 7 of 10 can predict a two-ribbon cancellation after the FTUE,
median board-four completion exceeds five minutes, or the solver cannot produce 30 mechanically
distinct validated boards without a new verb. Do not compensate with collection systems before the
core survives these falsifiers.

## Risks and Falsifiers

Originality must survive live comparison at the dominant-loop and consequence-structure levels,
not only theme or artwork. The input fails if players cannot reliably snap or cancel with one thumb.
The preview fails if it disagrees with commit or becomes an automatic solution. The content plan
fails if shortest solutions reduce to independent paths that ignore prior ribbons. The visual
direction fails if intersecting currents, seed identities, gates, or decisive failure cells are
unclear without color. Each failure is an explicit return-to-GDD trigger.

## Acceptance Criteria

- Given any valid level and ribbon set, `M-PREVIEW` and committed `M-BREATH` produce identical start and four-beat state hashes.
- Vector reinforcement, cancellation, diagonal confluence, zero motion, stone blocks, gate blocks, edge loss, thorn loss, same-cell collision, swap collision, matching bloom, nonmatching flower, ordered bloom, budget failure, success, and retry pass deterministic unit tests.
- Every safe commit appends exactly one permanent ribbon, decrements budget once, and replays every prior ribbon on all four beats.
- Invalid paths never mutate state or consume budget; cancellation restores the exact pre-drag state.
- The solver verifies 30 launch boards, a canonical solution for each, unique shortest solutions for the first 18, and bounded initial anchor-pair branching.
- Ten unfamiliar users complete the FTUE; at least seven predict a two-ribbon consequence and at least six request another board without prompting.
- Every required screen, runtime state, mechanic, entity, environment, UI element, accessibility cue, and VFX family appears in the UX contract and later Art Bible with physical source references.
- All targets meet size and safe-area rules, all semantic states pass non-color inspection, 150% text preserves play area, and reduced motion removes continuous travel.
- No HTML prototype begins until the owner accepts the complete GDD-bound Art Bible and a manual Codex design lock binds the exact package hash.