# Pin & Bloom — Game Design Document v0.1

**Status:** provisional candidate for pretotype  
**Updated:** 2026-08-08  
**Source opportunity:** opp-calm-fastener-logic  
**Production authority:** none until pretotype selection and prototype greenlight

## Product definition

Pin & Bloom is a portrait, flat-2D mobile logic game. The player releases color-coded screw-pins
from layered protective plates in a safe order. Removed pins travel into visible sorting trays.
When the last brace clears, the tiny botanical automaton beneath it unfolds and blooms.

Store-positioning candidate: **Pin & Bloom: Screw Puzzle**  
Short promise: **Calm mechanical puzzles that come alive.**

Market evidence supports the broad fastener-puzzle lane. Calm pacing, restoration payoff, fair
economy, and retention are hypotheses.

## Audience and use

- Adults and older children who play logic/sort puzzles in one-to-five-minute breaks
- Players who value readable rules, undo, offline play, and low-pressure sessions
- Not aimed at physics-sandbox or high-speed competition players
- Primary device: phone in portrait; tablet layout scales without changing board topology

## Design pillars

1. **See the rule.** No hidden faces, random physics, or camera search.
2. **Think without pressure.** Normal mode has no timer, lives, or mid-level interruption.
3. **Every solve restores something.** Completion creates a short, memorable living-machine reveal.
4. **Failure teaches.** A jam pauses the board and offers undo/restart; it never sells emergency
   recovery as the only path.

## Core loop

1. Read the layered automaton and three visible color trays.
2. Tap a screw-pin to preview what it holds and where it will travel.
3. Tap again to release it.
4. A freed brace slides away when none of its pins remain.
5. Three same-color pins in a tray convert into one decorative seed and clear that tray.
6. If every tray is full with no legal release, the board enters Jammed state.
7. Undo or restart; no life is consumed.
8. Clear every brace and tray.
9. Watch the automaton bloom for two seconds; collect its seed and continue.

Target level time: 60–180 seconds. Target first-session set: five levels in under ten minutes.

## Player verbs

- Inspect: one tap previews pin, held brace, and destination tray.
- Release: second tap confirms.
- Undo: restores the exact previous deterministic state.
- Restart: returns to the certified initial state.
- Pause/resume: persists board state locally.
- Pan: available only when accessibility zoom is enabled; normal boards fit without panning.

No drag precision, camera rotation, pinch dependency, or rapid tapping is required.

## Board model

### Entities

- **Bloom core:** final animated object; never blocks a pin.
- **Brace plate:** flat illustrated shape with a visible z-order and one or more pin sockets.
- **Screw-pin:** color plus redundant engraved symbol; occupies one socket.
- **Tray:** three slots, visible at all times, accepts one configured color family.
- **Seed:** post-match reward token; cosmetic/progression only.

### Deterministic rules

- A pin is legal when its head is not covered by another brace and its destination tray has space.
- Removing a pin changes only its socket, destination tray, and any newly unheld brace.
- A brace releases when all of its pins are removed; movement follows a authored 2D vector.
- Tray matching is deterministic: three equal color-symbol pins clear immediately.
- Jammed means zero legal pin moves while uncleared braces remain.
- Undo restores the exact prior board snapshot, including tray and brace state.
- Every shipped board has a solver certificate produced by the same pure rules module.
- Random generation may choose among certified boards; it never changes a loaded board.

## Difficulty grammar

Difficulty comes from visible dependency depth, branching factor, tray pressure, and symbol count.

| Tier | Layers | Colors | Trays | New demand |
|---|---:|---:|---:|---|
| Seedling | 2–3 | 2 | 3 | learn inspect/release/match |
| Sprout | 3–4 | 3 | 3 | one safe ordering dependency |
| Canopy | 4–5 | 4 | 3 | plan two matches ahead |
| Conservatory | 5–6 | 4–5 | 3 | branching solutions and controlled jams |

No normal board uses a timer. Daily challenge may count moves but cannot remove undo.

## Content structure

- Chapter 1: Paper Conservatory — flower, moth, watering can, songbird, seed clock
- Chapter 2: Sunlit Clockhouse — orrery vine, weather vane, tea automaton, bell flower
- Chapter 3: Cloud Nursery — kite fern, rain beetle, wind blossom, moon greenhouse
- Each chapter: 20 certified boards, five automaton families, four difficulty tiers
- First prototype: one flower automaton, five certified layouts, two-to-four colors

## Progression

- Solved boards add restored automatons to a shelf.
- Seeds unlock palette variants and shelf decorations.
- Chapter access follows completed-board count, not streaks or calendar pressure.
- Optional daily board reuses certified grammar with a move-count medal.
- No energy system, lives, punitive streak loss, or consumable power economy in v0.1.

## Business model hypothesis

INFERRED candidate:

- free first chapter;
- one-time full-game unlock;
- optional cosmetic palette packs;
- optional rewarded preview of a solution step, never required for a solvable board;
- no banner or interstitial during a board.

Willingness to pay, price, conversion, and revenue are UNKNOWN. Pretotype and later store tests must
compare this with a conventional free/ad-supported offer before production lock.

## UX and game states

Canonical states are specified in ux-flow.md. Gameplay must support Ready, Inspecting, Animating,
Jammed, Paused, Solved, and Restoring from persistence. No generated image may introduce a state
absent from that file.

## Art, motion, and audio

- Strict flat 2D orthographic presentation; no isometric or 3D camera
- Light paper-and-enamel botanical atelier; readable mechanical layering
- Released plates glide and settle; no uncontrolled rigid-body physics
- Bloom reveal lasts at most two seconds and can be shortened in accessibility settings
- Audio: soft click, paper slide, ceramic tray note, three-note bloom phrase
- Haptics: light inspect tick, medium release, optional bloom pulse

Art rules live in visual-brief.md and art-bible.md.

## Accessibility

- Every pin color has a unique engraved symbol and tray silhouette.
- Minimum interactive target: 48 CSS pixels in prototype; Unity equivalent scales by Canvas.
- Contrast target: WCAG AA for UI text and essential icons.
- Color-blind preview modes: deuteranopia, protanopia, tritanopia simulation during QA.
- Reduced motion, haptics off, sound sliders, large text, and hold-to-confirm alternative.
- No essential information conveyed by animation, color, sound, or haptics alone.
- Full state recovers after interruption without forcing replay.

## Analytics and validation

Only collect with consent and the minimum event payload:

- tutorial_start, tutorial_complete
- level_start, pin_preview, pin_release, undo, jam, restart, level_complete
- level duration, move count, undo count, jam count, solver-certificate ID
- chapter_paywall_view, unlock_start, unlock_complete

No advertising identifier is required for the core game. Prototype validation focuses on rule
comprehension, next-move predictability, completion, and desire for another board.

## Technical architecture

- Pure BoardState, MoveValidator, TrayMatcher, JamDetector, Solver, and LevelLoader modules
- GameController orchestrates; BoardView and InputHandler remain separate
- Integer IDs and explicit z-order; no physics engine in the rules path
- Level JSON includes braces, sockets, pins, trays, initial z-order, release vectors, and solution
  certificate hash
- Save after every committed move using versioned local JSON
- Portrait reference 1080×1920; safe-area aware; minimum supported play width 320 CSS pixels
- Stage 2 implementation is dependency-light HTML/CSS/JavaScript before Unity

## Acceptance tests

1. Solver confirms every bundled board has at least one solution.
2. MoveValidator rejects covered pins and full destinations.
3. Undo restores a byte-equivalent prior rules state.
4. JamDetector reports jam only when no legal moves remain.
5. Save/reload resumes the same board state.
6. Color-blind mode remains playable using symbols alone.
7. A first-time human completes tutorial level without spoken help.
8. A human can predict the consequence of the highlighted next move.
9. Full board can be played at 320-pixel width without overlap or scroll.
10. No timer, life loss, mid-board interstitial, or pay-required recovery exists.

## Kill or revise risks

- Kill if pretotype viewers cannot explain the restoration payoff after five seconds.
- Revise if the botanical theme is liked but the fastener interaction is unclear.
- Kill if the prototype feels like a slower clone after five boards.
- Revise if tray pressure recreates the unfairness the concept promises to remove.
- Kill if certified content requires more authoring effort than the small-team limit permits.