# Follow Kids — Game Design Document (GDD)

Guide robot: **Cubit** (original). No Superbook, Gizmo, or branded game characters/names.  
Privacy: no accounts, ads, or chat — `localStorage` only (`follow.v1.kids.*`).

---

## 0. First principle — the point is honored

Each portal exists to carry a **message** (courage, wisdom, mercy, stewardship, faithful work, forgiveness, …) centered on **exact Scripture**.

- The **message and its exact verse** are the center of the portal.
- Gameplay, physics, voxels, art, and transitions **serve** that point. They never trivialize, parody, or distort it.
- Every portal **ends with the child meeting the point plainly**:
  1. the **exact verse** (WEB from the Follow corpus),
  2. **what it meant then**,
  3. **how real people lived it** (sourced exemplars — never invented),
  4. **how they might live it now** (Follow stories + living exemplars, sourced).
- No gimmicks that undercut the point (no joke violence, no “win the Bible,” no score that replaces the verse).

If a design choice fights the point, cut the choice — keep the point.

---

## 1. Fantasy — Wonder Hall across all time

The child explores a **museum / gallery / wonder hall** spanning **ancient → historical → modern & now**. Pedestals hold **public-domain artworks** (with attribution) and **original 3D artifacts**. Touching one **unfolds** into a realm. Returning places a **badge or collected item** on that pedestal.

Any artifact can be a portal: sling stone, ark model, scroll, loaf & fish, trowel, staff, star map, printing press, telescope, pea pods, lab notebook, protein model, vaccine vial, solar panel, code laptop, soil sensor…

## 2. Structure — message threads (data-driven)

The museum is a **timeline of messages**. Kids can follow **one message across eras**.

Each portal is a **thread**:

| Step | Content | STEM |
|---|---|---|
| **Scripture moment** | Exact WEB verse(s) + plain “what it meant then” | Challenge that *illustrates* (never mocks) the story |
| **Historical living** | Real sourced exemplars who embodied the message | Light lab / measure / pattern tied to their field |
| **Today** | Follow original story (e.g. Adaeze) + living exemplars | Hands-on linked to the modern work |

**Source of truth:** `public/kids/messages.json` (and later the living exemplars DB). Growing the DB grows the Hall — no hard-coded biography invention.

```jsonc
{
  "messages": [{
    "id": "courage",
    "title": "Courage",
    "summary": "…",
    "point": "Trust God and step forward even when you feel small.",
    "nodes": [
      { "era": "ancient", "verse_refs": ["1 Samuel 17:45"], "artifact": "sling-stone",
        "realm": "/kids/quests/david-goliath", "stem": "sling-physics" },
      { "era": "historical", "exemplar_ids": ["Q8750"], "stem": "…" },
      { "era": "modern", "story_n": 1, "exemplar_ids": ["…"], "stem": "…" }
    ]
  }]
}
```

## 3. Wings (eras) still organize the Hall

Ancient / Historical / Modern pedestals, but **indexed by message** so Cubit can say: “Want to follow **Courage** through time?”

## 4. Tech spine

Leptos SSR; accessible 2D always; lazy `follow-kids-core` (Rapier3D) + three.js; SW caches `/kids/*`; offline after first visit.

## 5. Vertical slice (ship now)

**Courage** thread, first node playable:

- Wonder Hall hub with era wings + Courage pedestals.
- **Sling stone / David & Goliath** portal → exact WEB 1 Samuel 17 + Rapier sling STEM **in service of** the point (courage in Yahweh’s name, not “violent high score”).
- Closing panel: verse → then → historical exemplar (e.g. Faraday, sourced) → today (Adaeze story link + living exemplar path).
- Badge on return; Minecraft guide optional printable.

## 6. Non-goals for slice

Full 3D museum walk; inventing exemplar facts; more than one fully playable STEM realm.


## 7. External references (studied for tech — licenses respected)

### Sand3D — https://sandflow.ai/sand3d/
- **What it is:** “3D-as-code” library + ~100K object dataset (Sandflow). Objects are short **Python programs** (profiles, solids, joints, assemblies) over Blender `bpy`, not Gaussian splats / NeRF captures.
- **Viewer stack (site):** marketing page uses **three.js**; site JS mentions **WebGPU/WebGL** capability checks. Exports **GLB, URDF, USD, OBJ, STL** for Blender / three.js / ROS / MuJoCo etc.
- **Generation pipeline:** open collections (Objaverse, CAD, Articraft, SimReady, AutoMate) rewritten as Sand3D programs; HF datasets + explorer; library on GitHub [`Sandflow-ai/sand3d`](https://github.com/Sandflow-ai/sand3d).
- **License:** library **Apache-2.0** (GitHub). Datasets on Hugging Face — **verify each dataset card** before shipping assets (upstream collections may differ); do not assume Apache covers every mesh.
- **Adopt for Wonder Hall (permitted):**
  - Idea of **artifacts-as-programs** (parametric sling, ark, press, telescope) → export **GLB** into `/kids/` realms.
  - **Touch-to-enter**: crossfade PD painting ↔ GLB/voxel world (our three.js path); optional later load of Sand3D-exported GLBs.
  - Keep **lazy** loads; do not pull Blender/`bpy` into the browser.
- **Do not adopt blindly:** their proprietary foundation-model training stack; any dataset row without a clear open license; Gaussian-splat pipelines (Sand3D is **not** splat-based).

### frax — https://github.com/StanfordASL/frax
- **What it is:** Fast robot **kinematics & dynamics in JAX** (Stanford ASL). Pinocchio-class speed, Python ergonomics, MJX-like differentiation/batching. New `frax.ik` for IK / humanoid retargeting (>100k FPS claimed on GPU batches).
- **License:** **MIT** (Copyright 2026 Daniel Morton) — permissive for use/modification with notice.
- **Web port path:** JAX does **not** run in-browser today. Practical paths for Cubit / STEM:
  1. **Offline / CI:** author Cubit joint trajectories or IK with frax → bake keyframes or spline tables into `follow-kids-core` / JSON.
  2. **Server optional:** JAX service for advanced demos (out of slice; Follow kids stays offline-first).
  3. **In-browser physics:** keep **Rapier3D** (already in `follow-kids-core`) for sling/buoyancy/stacks; use frax-inspired *formulas* (Jacobians, gravity vector) reimplemented in Rust if needed — not a line-by-line port of JAX.
- **Adopt for Wonder Hall:** plausible Cubit arm/pose animation from baked IK; STEM readouts that mirror real dynamics vocabulary; never let flashy motion undercut the **point** (First principle).

### Slice stance
Ship with Rapier + three.js + PD art + `messages.json`. Treat Sand3D GLBs and frax-baked motion as **post-slice** upgrades once licenses for specific assets are confirmed.


## 8. AI-assisted art pipeline (David = art director)

Goal: original or openly licensed assets with **provenance**, serving the **point** (never style that undercuts the message).

### Workflow
1. **Playtest mechanics first** (2D lab + Rapier STEM) before commissioning heavy art.
2. **Look-dev references** — ~**8 concept images per portal world** (and short video stills if useful): lighting, palette, costume, artifact close-ups, museum pedestal, “picture unfolds into world” frames. David **approves** references before production.
3. **Rebuild as clean low-poly glTF** placed in three.js (instanced voxels OK for Cubit realms). No mystery blobs; readable silhouettes on tablets.
4. **Multi-view concept → 3D** for original characters (**Cubit** the robot companion; the child **explorer**): turnarounds, cloth/soft-body notes, simple animation cycles (idle, cheer, point-at-pedestal).
5. **Play-and-fix loops** — drop glTF into `/kids/`, playtest, note friction, revise art or mechanics; repeat.
6. **Provenance ledger** in `/kids/art/ATTRIBUTION.md` (and per-file sidecars): source, license, date, approver.

Optional later: Sand3D-exported GLB for parametric artifacts (Apache-2.0 tools; **check each dataset card**); frax-baked Cubit poses (MIT) as offline keyframes.

### Look-dev prompt shortlist (for David’s approval)
Use as briefs, not as final art. Keep tone reverent, warm, blocky/voxel-adjacent — **not** imitating commercial game brands.

1. **Wonder Hall wide:** sunlit gallery, era wings (stone / brass / glass), empty pedestals, Cubit at child’s height, soft god-rays; no logos.
2. **Courage pedestal:** sling stone + Doré-inspired PD painting frame; label “1 Samuel 17”; touch glow.
3. **Unfold transition:** painting warps into low-poly valley, stone flying mid-arc under clear sky.
4. **David realm STEM:** side-view toy physics diagram overlaid lightly (angle/power), not cartoony blood.
5. **Cubit turnaround:** cyan blocky robot, friendly eyes, measuring-cubit forearm mark; T-pose + idle.
6. **Explorer kid:** modest contemporary clothes, backpack, wonder expression; multi-view.
7. **Historical Faraday pedestal:** induction coil artifact, brass/wood, sourced-quote plaque area (blank for UI).
8. **Modern Adaeze pedestal:** abstract protein helix model + lab notebook; link plate to `/stories/1`.

Reject any output that mimics Superbook/Gizmo or named commercial avatars.

## 9. Render modes — 2D · 2.5D · 3D · AR · XR (not all at once)

The Wonder Hall **blends** presentation modes. **Any portal may use any mode**; the mode is chosen **per realm** to best serve that portal’s **message** (First principle). Modes are never stacked as a gimmick.

### Data (`messages.json` / portal nodes)
```jsonc
"render_mode": "3d",                 // primary for this portal
"render_modes_allowed": ["2d","3d","ar"],
"presenter": "three-webgpu-fallback-webgl2"
```
Enum: `2d` | `2_5d` | `3d` | `ar` | `xr`.

### Shared core (mode-agnostic)
- Quest FSM, badges, `localStorage`, verse panels, “Meet the point”.
- **Physics:** Rapier in `follow-kids-core` — **Rapier3D** for 3D/AR/XR; **Rapier2D** or a gravity-constrained 3D slab for pure 2D STEM (same STEM numbers either way).
- Input: touch / gamepad / keyboard mapped into a neutral `AimRelease` / `Interact` API.

### Mode-specific presenters (lazy-loaded)
| Mode | Presenter | Notes |
|---|---|---|
| **2d** | Canvas2D / SVG (or thin 2D WebGL) | Accessible default; always available as fallback |
| **2_5d** | three.js **orthographic** + parallax layers | Museum diorama / scroll feel |
| **3d** | three.js **WebGPU → WebGL2** | Slice default for David sling arena |
| **ar** | **WebXR** `immersive-ar` | Pedestal in the living room; graceful fallback → 3d/2d |
| **xr** | **WebXR** `immersive-vr` | Full immersion when headset present; else 3d |

### Transitions as magic
Entering a portal may **crossfade or unfold** between modes (e.g. museum **2_5d** pedestal → **3d** realm → optional **ar** “place the sling stone on your table”). Exiting restores the Hall’s mode. Transitions serve wonder; they never skip “Meet the point.”

### Slice stance
Ship **3d** (+ always-on **2d** lab) for Courage / David. Document AR/XR/2.5D presenters here; implement when a message clearly needs them.


## 10. Portal tiers — vignette · quest · saga (Bible-shaped range)

Realms range like Scripture itself: a short parable you can finish in a few minutes, or a long narrative you return to. **Tier is chosen to serve the message**, not to pad playtime.

| Tier | Length (guide) | Shape | Age / difficulty |
|---|---|---|---|
| **vignette** | ~3–8 min | One verse beat + one STEM beat + Meet the point | Ages ~5–8 default; large hit targets; Cubit narrates more |
| **quest** | ~15–40 min | Thread across 2–3 era nodes (scripture → historical → today) | Ages ~8–12; optional harder STEM params |
| **saga** | multi-session | Meta-arc spanning several messages/wings; museum state changes | Ages ~10+; parental pin for longer sessions |

**Scaling knobs (data-driven):** `tier`, `age_min`, `age_max`, `stem_difficulty` (`gentle` \| `standard` \| `challenge`) on each portal node in `messages.json`. Physics limits (sling power band, hit radius) follow `stem_difficulty` — never gore, never “win the Bible.”

### Meta-story (Wonder Hall across eras)
Cubit keeps a simple **museum journal** (local first): which messages you’ve walked, which pedestals woke, which badges sit in the Hall. The meta-story is not a separate game — it is the Hall itself remembering. Later sync (below) can share journal *entries the family opts into*, never a stranger’s feed.

Slice: Courage ancient node ships as a **quest**-length first session (vignette-completable if the child only does sling + Meet the point).

## 11. Multiplayer & shared state (slice = single-player; model sync-ready)

### Kid safety (mandatory — non-negotiable)
- **COPPA-aware:** no accounts that collect kids’ PII; no behavioral ads; parental gate for any network feature.
- **Invite-only** family/friend rooms (code/link from a parent device). **No open matchmaking.**
- **No free chat with strangers.** Communication = **preset emotes / approved phrases** only (localized).
- **No PII** in sync payloads (no names, photos, emails, precise location). Display names are local nicknames, not uploaded.
- **Parental controls:** enable/disable multiplayer, session time, which tiers unlock; clear “leave room” and block.

### Technology evaluation
| Option | License / notes | Fit for Follow Kids |
|---|---|---|
| **SpacetimeDB** | **BSL 1.1** (Clockwork Labs) — *not* OSI open source until Change Date (~2031 → AGPLv3+linking). Additional Use Grant: ≤1 prod instance, not a multi-tenant “Database Service.” | Powerful realtime + reducer model, but **BSL is a hard product/legal fit** for a free forever Bible site unless a commercial license is negotiated. **Do not depend on it for the kids path without explicit legal OK.** |
| **Yjs** | MIT | Mature CRDT for shared docs/presence; good for museum layout / journal / build boards in the browser. |
| **Automerge** | MIT | Document CRDT; strong offline; WASM builds available. |
| **Loro** | MIT | Fast CRDT; good for structured shared state; WASM. |
| **VoidDB (`inv-dimension-voiddb` in joulesperbit)** | First-party event-sourced CRDT-oriented DB (Holodeck/dimension line). Prefer this (or Yjs/Loro WASM) for museum sync so Follow isn’t captive to BSL. License follows the joulesperbit crate — confirm before shipping network sync. |

### Recommended architecture
```
Single-player (default, offline-first)
  └─ localStorage / OPFS  (quest progress, badges, journal)  ← slice ships here

Optional family room (parent-gated)
  ├─ CRDT document (Yjs or Loro or VoidDB): museum pedestals, builds, journal shares
  │     sync via WebSocket relay (no PII; invite token auth)
  └─ Authoritative physics room (short-lived): ONLY when two devices co-op a STEM beat
        server simulates Rapier step OR hosts deterministic lockstep seeds
        clients render; no chat channel
```

- **CRDT** = shared museum / build / journal (eventual, offline-tolerant).
- **Authoritative server** = physics co-op only (fair sling / wall stack); not for chat.
- **SpacetimeDB** = researched; **parked** under BSL unless licensed — CRDT+light relay covers the kids need.
- Keep entities and intents **sync-ready** (stable IDs in `messages.json`, badge keys, pedestal IDs) so single-player records can merge later without rewrite.

Slice stays **single-player**; no network calls for multiplayer yet.
