# Counterweight Choir — Game Design Document v0.4 ## Source and Truth Labels This document is the owner-directed material revision of Counterweight Choir. It replaces the player-facing resonance-token and torque-notation design in v0.2. The instruction is preserved in `00-brief/revision-2026-08-21-hypercasual.md` and the realistic-continuity correction in `00-brief/revision-2026-08-21-realistic-continuity.md`. Rules and inventories below are design facts. Fun, demand, retention, revenue, and store acceptance remain hypotheses for later evidence gates. ## Player Promise and Audience Counterweight Choir is a portrait tactile order puzzle with hyper-casual readability and hybrid-casual content depth. In a 30-to-90-second level, the player drags realistic suspended counterweights between visible hooks, swaps occupied weights, and watches a linked hanging sculpture settle. Each placement may reveal or hide the hook needed next. The goal is to match the pictured sculpture within the move budget. Players never read formulas, torque values, signed angles, pitch bands, or token strings. The target audience is broad mobile puzzle players who understand sorting, swapping, and visual matching immediately but enjoy discovering a short sequence. The store promise is: "Swap the right weights in the right order and watch the whole hanging puzzle click into place." ## Design Pillars and Non-Goals - `P-TOUCH`: one weight drag is the only gameplay input. - `P-VISIBLE`: size, distance, target pose, reachability, and result are shown physically. - `P-ORDER`: a committed swap changes which later hooks are reachable, so sequence matters. - `P-HIERARCHY`: later levels link beams; one lower change visibly reposes several ancestors. - `P-FORGIVING`: unsafe previews bounce back, Undo restores the prior move, and Retry is instant. - `P-SATISFY`: snap, settle, hook reveal, target lock, and final ring create a clear reward. - `P-VARIETY`: six mechanic families and four tiers change the reasoning pattern, not only numbers. Non-goals are visible mathematics, resonance phrases, generic single-scale equality, free-running physics, timing, catching, accelerometer play, rhythm tapping, narrative branching, combat, gacha, base building, multiplayer, forced social play, and any hint that automatically performs a move. ## Player-Facing Fingerprint - Input: drag one visible weight from a tray or hook to a currently open hook; release to place or swap. - Decision: choose the replacement order that moves beams toward their targets and exposes later hooks. - Objective: match every authored target beam angle and required target socket before moves reach zero. - Failure: exhaust the move budget without completing the target; unsafe previews never commit. - State change: a swap changes one or two weight locations, settles the hierarchy, changes hook reachability, consumes one move, and leaves a new visible arrangement. - Progression: 60 levels, six mechanic families, four difficulty tiers, and increasingly linked orders. - Content: authored weight sets, target poses, hooks, gates, blockers, move budgets, and recovery routes. - Presentation: a bright architectural sculpture gallery with slender anodized beams, tension wires, realistic ceramic and metal counterweights, hard daylight, compact white/cobalt UI, and a dense seven-to-ten-weight hierarchy in standard levels. - Metagame: completed sculptures fill a gallery shelf; no power upgrades or paid solution bypass. ## Core Loop and Player Verbs 1. Read the target silhouette: each beam has a thick target arc and required hooks have matching outlines. 2. Inspect the available weights. Size is communicated by physical volume plus one, two, or three embossed dots. 3. `M-PICK`: press a weight in the tray or on an open hook. Legal destinations pulse. 4. `M-DRAG`: move the weight toward a legal hook. The source remains reserved. 5. `M-PREVIEW`: show the exact final sculpture as a translucent solid-color ghost, including target matches, newly open hooks, closed hooks, and the first clearance problem. No numbers appear. 6. `M-SWAP`: release. An empty destination receives the weight and leaves the source empty. An occupied destination exchanges the two weights. An unsafe or closed destination bounces the weight home. 7. `M-SETTLE`: animate affected beams from the edited beam upward in at most 500 ms. 8. `M-CHECK`: matched beams click into their target arcs. If all target conditions pass, complete the level. 9. Continue, `M-UNDO` the last committed move, or `M-RETRY` the authored setup. There is no separate commit button after drag. Tap-selection plus tap-destination and keyboard selection/activation execute the identical command for accessibility and desktop testing. ## Deterministic Rules ### Authored level data A standard level contains one rooted acyclic tree of two to six beams, seven to ten movable weights, zero to four tray slots, and six to sixteen hooks. FTUE and the first reading lesson may use four or five weights. A weight has stable ID, mass class 1, 2, or 3, shape, and color. A beam has stable ID, parent hook, integer hook coordinates from -3 through -1 and 1 through 3, allowed angle states, and an authored target angle. A hook may contain a weight, be empty, be a required final socket, or carry one reachability rule. Weight classes remain hidden resolver data; no weight face prints a numeral. Every level declares a move budget, mechanic family, difficulty tier, target state, and canonical solution. ### Hidden settle resolver The simulation uses integers but the UI never exposes the calculation. Leaves resolve before parents, with stable IDs breaking ties. Local moment is the sum of hook coordinate multiplied by weight mass plus each child's transmitted mass at its parent hook. Moment maps to five poses: strong-left, left, centered, right, or strong-right. The preview, commit, solver, replay, Undo record, and tests call the same pure resolver. Animation timing cannot affect a result. The player-facing result is communicated only through weight size, lever distance, beam motion, target arcs, hook halos, and ghost pose. An optional accessibility label may say "left side becomes heavier" or "upper beam tilts right"; it may not require arithmetic. ### Placement and swap A source is legal when it holds a movable weight and is currently reachable. A destination is legal when it is another currently open hook compatible with the weight. Dropping on an empty hook moves the weight. Dropping on an occupied hook swaps the two weights atomically. The displaced weight goes to the source; a tray source remains a tray destination. A drag back to source or outside a target cancels without mutation. ### Reachability and correct order A hook has one of four readable states: open, target, closed by shutter, or blocked by another element. An authored `openWhen` rule may reference the current pose of its own beam, its parent, or one stable blocker. Reachability is evaluated before the move. A committed move settles the sculpture and then recalculates reachability for the next move. Therefore a player may need to place a heavy weight temporarily, open a higher hook, perform the important swap, then recover the temporary weight. No hidden timer, randomness, or arbitrary sequence flag controls order. One-way hooks accept a weight only from the tray or from the arrow direction shown on the beam. Reveal shutters physically slide away when open. Fragile clearance zones reject a preview if a final weight or beam overlaps the outlined glass zone. These rules always have visible geometry. ### Target, move budget, Undo, and terminal states After settling, a beam matches when its angle state equals its thick pictured target arc. A required target socket matches when it contains the specified mass class or shape, according to a nonnumeric silhouette and dot/shape motif on the target card. Success requires all declared beam and socket targets simultaneously. The final correct move consumes one move and then completes the level. Every safe committed move consumes exactly one move. Unsafe, closed, cancelled, or invalid drops do not. Undo restores the exact prior weight positions, beam poses, hook states, remaining moves, and terminal state; it is available once per committed step back to the initial state. Undo refunds that move and records no grade advantage. At zero moves, an incomplete level enters failure and offers Undo or Retry. Retry restores the authored setup. Reload starts FTUE and Level 1 fresh with no gameplay persistence. ### Determinism and tie-breaking If several rules fail, report closed destination before direction, clearance, boundary, then invalid target data. Within a category use beam depth followed by stable entity ID. No floating-point physics, random seed, frame time, tween completion, device speed, or pointer path affects state. ## Failure, Consequence, and State Change Closed hooks show a solid shutter and short "Open this first" label. Unsafe previews outline the decisive collision or boundary and bounce back on release without spending a move. A safe but poor swap commits, changes the sculpture, may close a later hook, and consumes one move. This is the core consequence: the player can see why their order created or removed an opportunity. At zero moves, the sculpture remains visible with unmatched target arcs and offers Undo and Retry. There is no punishment animation, currency loss, energy loss, or forced ad. Success locks each beam to its target in leaf-to-root order, rings the bells once, displays moves versus par, and advances. ## Progression and Content Grammar Launch content is 60 solver-verified levels. Adjacent levels may not share a canonical route signature. No family may exceed 20 percent of the campaign. - `F-SIMPLE-SWAP` (10): one beam, size/distance reading, empty placement, then occupied swaps. - `F-LINKED-BALANCE` (10): two and three linked beams where one lower change reposes an ancestor. - `F-REVEAL-HOOK` (10): target hooks open only in visibly authored beam poses. - `F-ONE-WAY` (10): arrow hooks constrain which replacement may happen first. - `F-CLEARANCE` (10): outlined glass zones reject specific heavy-weight routes. - `F-RELAY-ORDER` (10): combine temporary placements, reveal, swap, and recovery in short sequences. Four tiers control solution depth and branching: - `T1-READ`: one to two moves, one beam, no dead-end after a safe move. - `T2-SWAP`: two to four moves, occupied replacements and one linked consequence. - `T3-ORDER`: three to six moves, one reveal or one-way dependency and recoverable wrong orders. - `T4-MASTERY`: four to eight moves, two linked dependencies across at least two mechanic families. The offline solver enumerates legal swaps, rejects unreachable targets, stores canonical shortest routes, requires at least one solution within budget, records state count and branching, and proves adjacent route signatures differ. The first 36 levels require unique shortest solutions. Later levels may permit intentional alternatives but must keep different first-two-move signatures. ## State and Content Inventory Mechanics: `M-PICK`, `M-DRAG`, `M-PREVIEW`, `M-SWAP`, `M-SETTLE`, `M-CHECK`, `M-UNDO`, `M-RETRY`. Entities: `E-BEAM`, `E-PIVOT`, `E-HOOK`, `E-WEIGHT-1`, `E-WEIGHT-2`, `E-WEIGHT-3`, `E-TRAY`, `E-SHUTTER`, `E-ONEWAY`, `E-GLASS`, `E-TARGET-ARC`, `E-BELL`. Runtime states: fresh, selected, dragging, preview-safe, preview-blocked, settling, hook-reveal, target-match, active, success, failure, paused, loading, error, disabled, and interrupted. Screens: onboarding, gallery home/level select, gameplay, pause, success, failure, settings, accessibility, legal, and recoverable error. ## First Session and FTUE Every visit and reload opens FTUE from step one. 1. Goal: show a one-beam sculpture beside its thick target arc and say "Make the beam match the picture." 2. Input: highlight the large two-dot weight and an open hook. The player performs the real drag. 3. Result: while dragging, the whole target ghost moves and the destination shows "This opens the top hook." 4. Commit: release performs the real swap, settles the beam, opens the hook, and completes the first core action. 5. Order: a second guided swap uses the newly opened hook and completes Level 1. FTUE can be skipped before interaction and replayed from the visible How to Play control. The game shell is inert while the explanation is open. Skip enters Level 1. No FTUE or gameplay state persists. ## Economy and Monetization Boundaries The evaluation build has no ads, shop, currency, energy, consumable hint, paid solution, streak loss, push notification, or purchase gate. Market analysis may recommend a later business-model test, but monetization cannot alter the deterministic level result. If retention is proven, the first test is either rewarded visual guidance after two voluntary retries or a one-time ad-free/full-gallery purchase. Never sell automatic solutions. Interstitial frequency, pricing, willingness to pay, and ad tolerance remain unknown until observed tests. ## UX, Accessibility, Audio, and VFX The complete sculpture, target card, move count, Undo, and Retry remain visible in portrait play. Weights are at least 64 by 64 logical pixels; other controls are at least 48 by 48. Safe areas cannot crop a beam or hook. Back cancels a drag, then opens Pause. Rotation pauses and asks for portrait. Mass uses volume plus one, two, or three embossed dots. Hook state uses geometry, icon, outline, and short label as well as color. Target arcs use thick silhouettes. Screen-reader summaries name the selected weight size, source, destination, affected beams, newly opened/closed hooks, target matches, and remaining moves. Text scales to 150 percent without covering the sculpture. Pickup uses a porcelain/metal tick, preview uses a restrained cable hum, swap uses a double clack, settling uses a descending mechanical sequence, hook reveal uses a latch, and success rings the sculpture once. Reduced motion replaces rotations with a 100 ms before/after crossfade and stepped highlights. No flashes, screen shake, continuous sway, or sound-only information are allowed. ## Technical Constraints Target mid-tier 2019 iOS and Android phones at 60 fps with 30 fps fallback, under 150 MB installed, under 250 MB peak memory, and under 128 MB texture residency. Use authored integer JSON and a pure resolver shared by preview, commit, solver, Undo, replay, and tests. A canonical state hash includes level ID, sorted weight locations, beam poses, hook states, remaining moves, history depth, and terminal state. The game is offline-first with no backend or runtime generation. Settings, consent, and optional entitlement may persist; FTUE completion, level progress, board state, moves, results, and gallery completion do not persist in the factory prototype. ## Risks, Falsifiers, and Acceptance Criteria Primary risks are that the game collapses into generic equal-scale puzzles, target silhouettes reveal answers, correct order feels arbitrary, linked movement becomes visually noisy, or 60 levels repeat the same swap pattern. Revise if fewer than 8 of 10 unfamiliar players can explain the goal without reading a paragraph, fewer than 7 can predict which hook opens after FTUE, or fewer than 6 request another level. Reject the concept if the order dependency requires hidden rules, if fewer than four mechanic families produce distinct solver route signatures, or if live comparables already deliver the same reachability-changing hierarchical swap loop as their dominant product. Acceptance requires byte-identical preview and commit, visible reason for every hook state, no formula/token UI, exact Undo, 60 reachable levels, six families, four tiers, maximum 20 percent per family, different adjacent route signatures, 36 unique shortest routes, mobile no-scroll at 390x844, desktop/touch/keyboard parity, 150 percent text, reduced motion, non-color cues, fresh FTUE on reload, and no gameplay persistence. Prototype testing must complete representative recovery and all solver-authored level routes before technical sign-off. ## Fantasy, Promise, Audience, and Genre Restore a realistic hanging kinetic sculpture by swapping visible dot-marked weights in the right physical order. The audience is broad portrait-mobile puzzle players; the genre is hypercasual-readable spatial/order puzzle with authored hybrid-casual depth. ## Design Pillars Touchability, exact consequence preview, order-changing hook access, whole-board readability, forgiving recovery, and solver-enforced variety are mandatory. ## Camera, Dimension, and Controls Portrait 2.5D fixed orthographic front elevation. One-finger drag or tap-select/tap-destination performs place or occupied swap; no pan, zoom, orbit, tilt, timing, or hidden off-screen action. ## Difficulty, Progression, and Economy Sixty authored solver-verified levels span six capped families and four tiers. Progress comes from new action-graph consequences, not larger numbers. There is no power economy. ## Monetization Constraints The evaluation build is ad-free and currency-free. Any later rewarded guidance, ad removal, or full-gallery purchase must be separately tested and cannot block owned play or sell solution power. ## UX and Accessibility The entire sculpture, compact pictured target, moves, tray, Undo, and Retry stay on one screen. Size plus dots, hook geometry plus labels, scalable text, reduced motion, haptics, screen-reader summaries, and tap parity repeat critical state. ## Audio and VFX Porcelain taps, metal clicks, shutter slides, restrained settle motion, full-pose ghost, hook-change pulse, target stamps, and one completion bell reinforce visible causality without musical token notation or casino spectacle. ## Analytics and Technical Constraints Offline-first JSON levels use one deterministic integer resolver shared by preview, commit, Undo, solver, replay, and tests. Optional consented analytics never gates play. Target 2019 mid-tier phones, 60 fps with 30 fps fallback. ## Risks and Falsifiers Reject or revise if occupied swaps rarely change future hook reachability, unfamiliar players describe only generic balancing, route families collapse into coordinate variants, the target reveals the entire move order, or the first two real moves fail to teach reveal causality. ## Acceptance Criteria The FTUE shows an occupied swap opening the next hook; at least four families alter the legal-action graph; every level is solver-verified with Undo; ten-player testing reaches the defined comprehension gates; no visible equation, torque label, resonance token, phrase rail, or generic balance-only objective remains. ## Realistic Visual Continuity Contract Standard gameplay frames show a credible gallery-scale mobile with two to six slender beams and seven to ten visible counterweights. Materials read as anodized aluminum, tension cable, porcelain, brushed steel, clear acrylic, plaster, and concrete under directional architectural daylight. The compact interface uses warm white panels, graphite text, and restrained cobalt action color. The earlier soft candy-toy treatment is explicitly rejected. Visual continuity with the prior Counterweight Choir generation is owner-requested; only its mathematical and resonance presentation is removed.