# Lantern Street — Design

A short single-player browser game (about 1 minute per run). Hang six lanterns along one street before the festival starts at dusk. You choose how many lanterns to carry on each trip: **light trips are steady but slow overall, heavy trips are fast overall but wobbly.**

Scope of this document: design only. Nothing is implemented yet.

## 1. Pitch and pillars

- **One street, six hooks, one clock.** The whole game is visible on one screen.
- **The core decision is load size.** Before each trip you pick 1, 2 or 3 lanterns. Every other rule exists to make that choice interesting.
- **One input idea.** Move left/right and hang. No other mechanics, so the choice is not buried in controls.
- **Readable and fair.** Each failure is visible, explained and cheap to retry. A run takes under 90 seconds.

## 2. The core loop

1. Start at the **depot cart** at the left end. Six unlit lanterns sit on it.
2. **Load** 1–3 lanterns. Tap Load once per lantern, up to 3. Each lantern takes 0.5 s to load.
3. **Walk** right along the street toward the hooks.
4. **Hang** a lantern when standing at an empty hook. This takes 1.2 s, during which you can't move.
5. **Return** to the depot, or stop early if you've dropped everything you carried.
6. Repeat until all six hooks are lit, or the clock runs out.

Win: all six hooks lit before the festival clock hits zero.
Lose: the clock hits zero with any hook dark.

## 3. The tradeoff (the heart of the game)

Carrying more makes you slower and makes you sway.

| Load | Walk speed | Sway buildup while moving | Time to a full sway meter |
|------|-----------|---------------------------|---------------------------|
| 1 | 100% (8 m/s) | below the recovery rate | never |
| 2 | 75% (6 m/s) | slow | about 9 s of continuous walking |
| 3 | 60% (4.8 m/s) | fast | about 4 s of continuous walking |

**Sway meter:** a small gauge over the player. It rises while you move with 2 or 3 lanterns and drains while you stand still. Speed drops as the load drops, so after each hang you are lighter and quicker.

**If the meter fills:** you stumble. One lantern (the last loaded) goes out and is **dropped**. It returns to the depot, and you lose 2 s recovering. The meter resets to 40%.

So a heavy trip means walking in bursts. You go, you pause to settle, you go again. A light trip means holding right and never worrying.

### Why neither choice dominates

Street layout: the six hooks are at 10, 20, 30, 40, 50 and 60 m from the depot. Rough timings with starting values:

- **All singles:** about 55 s. This is slightly over the clock, so pure singles lose. Round trips to the far hooks dominate the time.
- **Two trips of 3 (near three, far three), no stumbles:** about 35 s plus roughly 4 s of settling pauses. This is much faster, but each stumble costs about 2 s of recovery plus a full round trip to re-fetch the dropped lantern.
- **Mixed plans** (heavy for the far hooks, a single for a quick near hook, or 2+2+2) finish in about 40–45 s with a lower stumble risk.

The festival clock is **50 s**, so pure singles fail. A reckless all-3 plan that stumbles twice also fails. The good plans are in between, and players will find different ones.

Additional pressure that makes the choice situational:

- **Cobble patches.** Two fixed patches (at about 25 m and 45 m) add a sway spike when you cross them. A load of 3 needs to be at low sway before crossing. A load of 1 ignores them.
- **Lantern order matters little, hook choice matters a lot.** You may hang at any empty hook, so when carrying 3 you can drop the far ones first and lighten up early.
- **Hang time is fixed** (1.2 s each). Heavy trips save walking, not hanging, so the savings come only from fewer round trips.

## 4. Controls

All inputs map to three actions: **Move**, **Load/Hang** (context action), and **Restart/Pause**.

### Keyboard
- **Left/Right arrows** or **A/D**: move (hold).
- **Space** or **Enter**: context action. At the depot it loads one lantern. At an empty hook with a lantern in hand it hangs one.
- **R**: restart. **P** or **Esc**: pause.

### Touch
- Two large on-screen buttons at the bottom-left: **◀** and **▶** (hold to move).
- One large **Action** button at the bottom-right (same as Space).
- A small pause button at the top-right.
- Buttons are at least 64×64 CSS px, separated so thumbs don't overlap. Multi-touch is required, so you can hold ▶ while tapping Action.
- No hover-only UI. Use pointer events so mouse also works.
- Prevent page scroll, zoom and text selection on the game area (`touch-action: none`).

### Context action rules
- At the depot with an empty hook-free hand: Action loads a lantern, up to 3. Holding Action does not repeat. Each tap is a deliberate choice.
- Standing at an empty hook with a lantern in hand: Action hangs.
- Anywhere else: Action does nothing (the button dims).
- Hook proximity is within ±1.5 m, with a visible highlight ring.

## 5. Screens and states

State machine: `title → playing ⇄ paused → won | lost → (restart) playing`

- **Title:** the name, a 3-line "how to play" and a Start button (or press Space). Shows the controls for the detected input type.
- **Playing:** the street scene plus HUD (below).
- **Paused:** dimmed scene, Resume and Restart buttons. Pauses automatically if the tab loses focus.
- **Won:** shows time left, stumbles, trips taken and a star rating (see §7). Buttons: Play again.
- **Lost:** shows how many lanterns were lit and a one-line hint chosen from what went wrong (e.g. "Too many short trips" or "Two stumbles cost you a full trip"). Button: Try again.

Restart is one input from any end state. Time to retry is under 1 s.

## 6. HUD and feedback

- **Festival clock** at top-center: a numeric countdown plus a sky that shifts from gold to dusk to night. The crowd gathers at the street's right end as time runs out.
- **Lantern tracker:** six slots at the top-left, showing lit, carried and at depot.
- **Load indicator:** carried lanterns shown on the player's pole.
- **Sway gauge:** a small arc over the player. It turns amber at 60% and pulses red at 85%, with a soft creak sound.
- **Hook rings:** dark hooks pulse gently, and a ring brightens when in range.
- **Stumble:** a brief screen shake, a lantern-out puff, a clear "Dropped!" label, and a thin line showing the lantern back at the depot.
- **Audio** (optional, mutable, off until first interaction): footsteps, hang chime, stumble thud, clock tick in the last 10 s. Every audio cue also has a visual equivalent.
- Color is never the only signal. Sway has a gauge shape and a numeric tick, and hooks have lit/unlit shapes.

## 7. Scoring and replay

Single run, no meta-progress. Stars:

- ★ Win at all.
- ★★ Win with at least 8 s left.
- ★★★ Win with at least 8 s left and zero stumbles.

Best time is saved in `localStorage` (a single key). If storage is unavailable the game still works.

Replay value comes from different load plans and from trying for no stumbles. There is no randomness, so a run is fully learnable. This is deliberate for a one-minute game.

## 8. Tuning constants (starting values, to be playtested)

| Constant | Value |
|---|---|
| Hook positions | 10, 20, 30, 40, 50, 60 m |
| Base speed | 8 m/s |
| Speed multipliers (1/2/3 load) | 1.0 / 0.75 / 0.6 |
| Sway rate per second moving (1/2/3) | 0.05 / 0.11 / 0.25 (meter spans 0–1) |
| Sway recovery while still | 0.5 per second |
| Cobble spike | +0.25 (2 lanterns) / +0.4 (3 lanterns) |
| Load time | 0.5 s per lantern |
| Hang time | 1.2 s |
| Stumble penalty | 2 s frozen, meter resets to 0.4, one lantern returns to depot |
| Festival clock | 50 s |

All constants live in one config object so the balance can be changed without touching logic. Balance goal: pure singles should lose by a few seconds, the best plan should win with 5–12 s spare, and a plan with two or more stumbles should lose.

(Sway rate for load 1 is below recovery only in the sense that it never fills: moving continuously at 0.05/s would take 20 s to fill a meter. Since the single-lantern trip is at most 60 m ≈ 7.5 s, it cannot stumble. If playtests show otherwise, set it to 0.)

## 9. Technical notes (for the later build step)

- A single `index.html` with inline CSS and JS, no dependencies, no build step. Opens from `file://`.
- Canvas 2D at a fixed logical size (for example 960×540), scaled to fit with letterboxing. Touch buttons are DOM elements over the canvas, so they stay crisp.
- Fixed-timestep update (60 Hz) with `requestAnimationFrame` rendering. This keeps behaviour identical across devices and makes the logic testable.
- Game logic (movement, sway, load, hooks, clock) is a pure module-like section with no DOM access, so it can be exercised from the console.
- Input layer turns keyboard, pointer and touch into one `{left, right, actionPressed}` state.
- Respect `prefers-reduced-motion` by disabling screen shake and sky transitions.
- Pause on `visibilitychange`.

## 10. Acceptance checklist (for the later build step)

- A full run can be won using keyboard only, and using touch only.
- Pure single-lantern play loses on time. A sensible mixed plan wins.
- Carrying 3 across a cobble patch at high sway reliably causes a stumble. Pausing first avoids it.
- Dropped lanterns reappear at the depot and are re-deliverable, so the game is never unwinnable by a stumble alone (only by time).
- Pause, restart, win and lose all work from both input types.
- Layout works from 360 px wide portrait phones to desktop.
- No state persists except best time.

## 11. Out of scope

Multiple levels, upgrades, enemies, procedural streets, online leaderboards, accounts, and multiplayer.
