commit bd3f0d99ee7f32b566961241b55b0fc0ee9934b2 Author: Lexical Bits Date: Mon Jul 27 10:02:54 2026 -0400 chore: initial plan diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 0000000..a7f41e3 --- /dev/null +++ b/PLAN.md @@ -0,0 +1,269 @@ +# Pot Patrol — Plan + +A single-screen, sprite-based, widescreen browser game built with **Kaplay** +(the JS/TS game library, successor to Kaboom.js). Link (AI) rampages across a +procedurally generated scene smashing pots; you (the player) chase him and sweep +up the shards before he leaves the screen. + +--- + +## 1. Concept & core loop + +- **Actors:** `Link` (computer-controlled) and `Player` (you). +- **Link's behavior:** wander toward the nearest pot, pick it up, and throw it in + a random direction. The pot flies 2–3 tiles, shatters, and scatters 1–3 shards + onto nearby tiles. Along the way Link gets **distracted**: + - **Grass** — he detours to cut it. + - **Chickens** — he hits one once, then it chases him, so he **flees briefly** + before resuming. +- **Player's job:** follow Link and clean up shards by touching them. +- **Win:** zero shards remain at the moment Link leaves the screen (or after his + last pot, once the board is clear). +- **Lose:** Link leaves the screen with shards still on the ground. +- **Balance:** Link is slightly faster than the player, but loses time to + distractions — that lost time is the player's window to catch up. + +--- + +## 2. Tech: Kaplay + +Kaplay gives us the game loop, rendering, sprites, input, collision, scenes, +timers, tweens, vectors, and seeded RNG out of the box — so most of the old +"engine" work disappears and we focus on game logic. + +- **Load:** ES-module import from a CDN, keeping a no-build setup: + ```html + + ``` + Serve over HTTP for module loading: `python3 -m http.server` → `http://localhost:8000`. + *(Alternative, better DX: `npm create kaplay@latest` scaffolds a Vite project. + We can switch to that if we want bundling/TS; the plan below is engine-API + identical either way.)* +- **Init:** `kaplay({ width: 960, height: 560, background: [...], letterbox: true, global: false })`. + `letterbox` keeps the widescreen aspect ratio and scales to the window. +- **Seeded RNG:** `randSeed(seed)` + `rand()`, `randi()`, `choose()` — reproducible + scenes for debugging and "retry same level" (no custom PRNG needed). +- **Delta time:** `dt()` for frame-independent movement. +- **Depth:** set `obj.z = obj.pos.y` each frame for top-down y-sorting. + +Kaplay features we lean on hardest: + +- **`state()` component** — a built-in finite state machine, ideal for Link's AI + (`onStateEnter/Update/End`). +- **`addLevel()`** — turns an ASCII tile map into game objects, matching our + procedural grid. +- **`area()` + `onCollide` / `body({ isStatic })`** — collision & obstacle + blocking (top-down, gravity 0). +- **`scene()` / `go()`** — game / win / lose screens. +- **`tween()`** — pot throw arc, sweep juice. + +--- + +## 3. Coordinate system + +- Tile-based grid, continuous pixel positions (Kaplay `vec2`). +- Config constants (tunable in `config.js`): + - `TILE = 40` px + - `COLS = 24`, `ROWS = 14` → `960 × 560` canvas (≈16:9 widescreen). +- AI reasoning in tile coordinates; movement continuous. `addLevel` uses + `tileWidth/tileHeight = TILE`. + +--- + +## 4. File structure + +``` +index.html # imports src/main.js as a module +styles.css # page bg, canvas centering +src/ + config.js # tunable constants (sizes, speeds, counts, radii) + main.js # kaplay() init, load assets, register scenes, go("game") + gen.js # seeded procedural tile map + entity placement + sprites.js # loadSprite / placeholder object factories + scenes/ + game.js # main scene: build level, spawn actors, wire collisions + end.js # win & lose scenes (result + retry / new-seed) + actors/ + player.js # player object + input-driven movement + link.js # link object + state() FSM (the AI) + chicken.js # chicken idle + chase behavior + pots.js # pickup, throw arc, shatter, shard spawning + hud.js # shard counter, pots-remaining, dev state readout +``` + +Kaplay's built-in RNG/loop/render/input mean no `rng.js`, `render.js`, or +`input.js` — that logic is inline via Kaplay APIs. + +--- + +## 5. Procedural scene generation (`gen.js`) + +Seeded via `randSeed(seed)`. Produce a level the game scene consumes: + +1. **Grid & ground:** fill a `COLS × ROWS` map with floor tiles (optionally 2 + variants for noise). +2. **Obstacles:** scatter impassable decor (rocks/trees), light count (6–12), + keeping the interior open. Border walkable except one **exit gap** (§9). +3. **Pots:** place `POT_COUNT` (5–8) on random passable, unoccupied tiles. +4. **Grass:** place `GRASS_COUNT` (8–15). +5. **Chickens:** place `CHICKEN_COUNT` (2–4). +6. **Spawns:** Link at one edge; player opposite/center. Keep spawn tiles + their + neighbors clear. +7. **Validation:** flood-fill from Link's spawn; reroll any unreachable pot (or + regenerate) so the level is always solvable. + +Two build options (either works — leaning toward **B** for dynamic control): +- **A.** Emit an ASCII map and hand it to `addLevel()` with a `tiles` map of + component factories per symbol. +- **B.** Emit a data structure (tile types + entity list) and `add()` each object + directly — more flexible for entities that move, spawn, and despawn at runtime. + +--- + +## 6. Entity model — Kaplay components + +Every actor is a Kaplay game object: `add([...components, "tag"])`. + +- **Player:** `[sprite/placeholder, pos, area(), body(), anchor("center"), "player"]`, + moved from input; `PLAYER_SPEED`. +- **Link:** `[..., area(), body(), state("seek", [...]), "link"]`; `LINK_SPEED` + (≈1.15× player). AI in the `state()` FSM (§8). +- **Pot:** `[..., area(), "pot"]`; static until targeted, then handled by `pots.js`. +- **Shard:** `[..., area(), "shard"]`; removed on player overlap. +- **Grass:** `[..., area(), "grass"]`; destroyed/stubbed when cut. +- **Chicken:** `[..., area(), body(), state("idle",[...]), "chicken"]` (§chickens). +- **Obstacles:** `[..., area(), body({ isStatic: true }), "obstacle"]` — block movers. + +Movement helper: `obj.move(dir.scale(speed))` toward a target `vec2`; `body` +resolves collisions against static obstacles. Update `z = pos.y` for depth. + +--- + +## 7. Pots, throwing & shards (`pots.js`) + +- **Target:** Link's FSM picks the nearest `"pot"` still on the board + (`get("pot")` + min distance). +- **Pickup:** within `INTERACT_DIST`, pot attaches to Link (brief wind-up). +- **Throw:** pick a random 8-way direction and **2–3 tiles** distance. Animate + with `tween()`: linear travel along the path **plus** a parabolic height offset + (tween a `z-height` up then down, drawn as vertical sprite offset + a shadow) so + it visibly arcs. +- **Shatter on land:** spawn **1–3 shards** on the landing tile + random adjacent + passable tiles (dedupe to one per tile). `addKaboom()` / small particle pop + + `shake()` for juice. +- If the target tile is impassable, land on the nearest passable tile. + +--- + +## 8. Link AI (`link.js`) — `state()` FSM + +States, checked by priority each `onStateUpdate`: + +1. **`flee`** — active for `FLEE_TIME` after hitting a chicken; run away from the + nearest chasing chicken, then return to `seek`. +2. **`distracted`** — if grass/chicken within `DISTRACT_RADIUS`, with per-tick + probability divert: + - grass → move adjacent → **cut** (destroy grass), brief pause → `seek`. + - chicken → move adjacent → **hit** once → triggers chicken chase + Link `flee`. +3. **`seek`** — move to nearest pot → transition to `throw`. +4. **`throw`** — run the throw sequence (§7) → back to `seek`. +5. **`leave`** — no pots remain (or a max-time fuse fires): walk to the exit gap + and off-screen → end the round (§9). Detected with `offscreen()`. + +"More distractions" = generous `DISTRACT_RADIUS` + divert probability + flee +detours, so Link squanders his speed edge. `enterState()` transitions log to +console in dev; HUD shows current state. + +--- + +## 9. Win / lose (`scenes/`) + +- `game` scene tracks `shardCount` (count of `"shard"` objects) live in the HUD. +- **Link leaves:** his `leave` state + `offscreen()` ends the round; evaluate: + - `shardCount === 0` → `go("win")`. + - `shardCount > 0` → `go("lose", { left: shardCount })`. +- **Early win:** last pot thrown **and** `shardCount` hits 0 before he exits → win + immediately. +- End scenes show result + **Retry (same seed)** and **New scene (new seed)** + (`go("game", { seed })`), driven by key press. + +--- + +## 10. Player input & shard cleanup + +- Kaplay input: `onKeyDown("left"/"a"/…)` or `isKeyDown()` to build a direction + `vec2`; normalize so diagonals aren't faster; `player.move(dir.scale(PLAYER_SPEED))`. +- Cleanup: `player.onCollide("shard", (s) => { destroy(s); shardCount--; })`, + with an optional sweep tween. +- Obstacle blocking handled by `body()` vs static obstacle bodies. + +--- + +## 11. Rendering & HUD + +Kaplay renders automatically; we control **order via `z`** (set each frame to +`pos.y` for actors/chickens; fixed low `z` for ground/decor, high `z` for the +flying pot + HUD). Sprites via `loadSprite`; **placeholders** first so it's +playable immediately: + +- Placeholder glyphs with `text()` — Link 🧝, player 🧹, pot 🏺, shard 🔶, + grass 🌿, chicken 🐔, rock 🪨 — or colored `rect()`/`circle()` components. +- HUD (`hud.js`): shard counter, pots remaining, Link state (dev), win/lose + banner — `add([text(), fixed(), z(top)])`. +- `image-rendering: pixelated` on the canvas for crisp sprites. + +--- + +## 12. Milestones (build order) + +1. **Skeleton:** `index.html` + `main.js` with `kaplay()` init, empty `game` + scene, letterboxed canvas. Runs via local server. +2. **Procgen:** `gen.js` builds a seeded level; `game` scene renders ground, + obstacles, pots, grass, chickens, spawns; reachability validated. +3. **Player:** input-driven movement + obstacle collision via `body()`. +4. **Link seek+move:** `state()` FSM with `seek` targeting nearest pot (no throw). +5. **Throw + shards:** pickup → `tween` arc → shatter → 1–3 shards. +6. **Cleanup + HUD:** `onCollide` shard pickup; live counter. +7. **Distractions:** grass cut; chicken hit → chase → Link `flee`. +8. **End states:** `leave` + `offscreen` → win/lose scenes + retry/new-seed. +9. **Polish:** real sprite atlas, `addKaboom`/particles, sfx (`loadSound`/`play`), + `shake()`, tuning pass on speeds / radii / counts. + +Each milestone is independently runnable for playtesting. + +--- + +## 13. Tunable constants (initial guesses, `config.js`) + +| Constant | Value | Meaning | +|--------------------|--------------|-------------------------------------------| +| `TILE` | 40 px | tile size | +| `COLS × ROWS` | 24 × 14 | grid → 960×560 canvas | +| `PLAYER_SPEED` | 130 px/s | player movement | +| `LINK_SPEED` | ~150 px/s | ≈1.15× player | +| `POT_COUNT` | 5–8 | pots per scene | +| `GRASS_COUNT` | 8–15 | grass tufts | +| `CHICKEN_COUNT` | 2–4 | chickens | +| `THROW_TILES` | 2–3 | pot flight distance | +| `SHARDS_PER_POT` | 1–3 | shards on shatter | +| `DISTRACT_RADIUS` | ~4 tiles | how far grass/chickens tempt Link | +| `FLEE_TIME` | ~1.5 s | how long Link flees after hitting chicken | + +First-pass numbers; §12 step 9 tunes them against playtests. + +--- + +## 14. Assumptions & open questions + +- **"Your PC"** = the player-controlled character (Link is the AI). Assumed. +- **Kaplay delivery:** CDN ES-module import for a no-build start; can switch to + `npm create kaplay` + Vite for bundling/TypeScript if we want it. +- **Sprites:** no Zelda art bundled; starting with emoji/`text()` and shape + placeholders, swappable for a real atlas via `loadSprite` later. +- **Link leaves when** out of pots (max-time fuse as backstop); a fixed round + timer is a one-line alternative in `config.js`. +- **Chicken chase:** only the hit chicken chases (simplest); could expand later. +- Audio is polish (step 9), not core.