jankenbots/memory.md

# memory — JANKENBOTS

Durable memory for this project. Read at session start, update before session end. Date format: `YYYY-MM-DD`. Deep design detail lives in `DESIGN.md` (the full record carried over from the idea's `plan.md`); this file is the distilled decisions + live work.

> **Location:** this project lives at **`/mnt/f/jankenbots/jankenbots`** (Windows `F:\jankenbots\jankenbots`) so the Unity Editor (Windows-only) and the git repo/docs share one folder. `~/claude/projects/jankenbots` is a **symlink** to it. Work from either path. **Name:** the game is **JANKENBOTS** (working title was JANKENSTEIN; the archived idea folder keeps the old name at `~/claude/archive/ideas/jankenstein/`).

## Decisions & rationale

- **Concept (locked).** ~25-player friendslop build-brawl: teams build a janky physics robot from themed scrap; **each teammate pilots one functional part** (pillar #6 — "you build your control scheme, not a robot"); death → free-roaming ragdoll **gremlin**. 8 design pillars in `DESIGN.md`.
- **Engine: Unity** (2026-07-10). Decided after a 3-angle netcode/prior-art study. The physics-party genre is overwhelmingly Unity (Fall Guys, Gang Beasts, Human Fall Flat, PEAK, Lethal Company, Party Animals, Stumble Guys, Trailmakers, Besiege, Robocraft); the two UE physics-heavy titles both swapped UE physics for Bullet. An earlier Unreal-MCP-tooling edge was correctly overridden. **The defining risk is networked physics at ~25-player scale — no shipped game occupies that quadrant.**
- **Control feel v0.1 — driving = symmetric** (2026-07-10). Each locomotion part = one pilot applying *literal force* ("you are the left tread") — the only model that generalises to arbitrary scrap contraptions and the one that keeps pillar #6. Tread pilot verbs: **snap-to-cruise throttle** (both slam forward = easy straight; coordination lives in the in-between), **lock-pivot** (called-play turns), **passive lean** (nobody idle). Asymmetric (throttle/steer split) held as the fallback if the prototype groans.
- **Weapons = three-body call-and-response** (2026-07-10). A weapon pilot perturbs the drivers' world → turn simultaneous chaos into rhythm: wind-up **telegraphs a brace**, a **braced bonus** makes drive+strike a combo, weapon doubles as engine/counterweight. Generalises to **5 archetypes** — Punch / Grinder / Grip (later tier) / Guard / Passive. The **weapon mix is a build-time chaos dial** (over-building self-punishes = pillar #6 made mechanical).
- **Team size & lobby math** (2026-07-10). Team **3–5** (3 = smallest full driver+driver+weapon triangle; 5 = coordination/budget ceiling); lobby **≥2 teams**; sweet spot 5 teams of 5. Unequal sizes balanced by a **flat build budget** (small team = concentrated & nimble; big team = distributed & tippy → equal power, different character), reinforced by physics (bigness = top-heavy, self-limiting) + coordination tax; matchmaking buckets pre-made friend groups & prefers equal sizes, NPC-fills the rest. **No living "roamer" — everyone is in the bot; off-bot = gremlins (dead) only.** Style vote needs ≥3 teams (2-team lobbies use fight-result + spectator vote).
- **Prototype netcode = Unity NGO + Relay, host-authoritative** (2026-07-10). Chosen for the *throwaway* first prototype (free, first-party, friends join by code, no port-forwarding). **This does NOT commit the final architecture** — server-authoritative state sync vs Photon Quantum deterministic lockstep is still deferred until the game is proven fun.

## Open questions / TODOs

- [ ] **Build Milestone 1** — networked shared bot, each player one tread (see `docs/prototype-plan.md`). The immediate work.
- [x] **Project location decided** — unified on `F:\jankenstein` (git + Unity + docs together), symlinked from `~/claude/projects/jankenstein`. Unity `.gitignore`/`.gitattributes` in place.
- [ ] **Create the Unity project** in `F:\jankenstein` (Unity LTS) and add the **NGO + Relay + Lobby** packages.
- [x] **Unity MCP working** — CoplayDev server on `127.0.0.1:8067`, portproxy `8068→8067`, `.mcp.json` → `172.27.208.1:8068/mcp`; handshake verified. (Load the `unity` tools by starting Claude *from the project folder*.)
- [ ] **Netcode architecture (deferred, the real risk)** — dedicated server-authoritative state sync (Robocraft 2 blueprint) vs Photon Quantum lockstep (Stumble Guys precedent). Decide *after* the fun is proven + the 25-player physics spike. Netcode target ≈ 25–30 primary rigid bodies + gremlins/debris.
- [ ] **The 25-player physics/netcode spike** — two ~30-joint bots colliding at arena scale, ≥100 ms latency, min-spec. The make-or-break gate before scaling up.
- [ ] Remaining **design** questions (detail in `DESIGN.md`): build-coupling tightness, hidden per-player agenda, at-scale voting, part taxonomy, scavenge-contest rules, art style, progression (cosmetic-only), final name (working title JANKENSTEIN; alts BODGEBOTS / SCRAPYARD SCRUM / CLANKERS / RUSTBUCKETS / JALOPY WARS).

## Session log

### 2026-07-10
- **Promoted from `ideas/jankenstein` to a real project.** Scaffolded the WSL-side project home (this repo): filled `CLAUDE.md`, seeded this `memory.md` from the idea's `plan.md`, carried the full design record over as `DESIGN.md`, added `docs/prototype-plan.md`. Idea folder archived to `archive/ideas/jankenstein`.
- Decided to build a **basic networked prototype first** (user wants to test the coordination feel with real friends — local split-screen won't capture the social/voice-chat core). Stack: **Unity NGO + Relay**, host-authoritative, throwaway netcode. Milestone 1 = one shared bot, each player one tread.
- **Consolidated the project + seeded Unity MCP config** (`.mcp.json` → `unity` HTTP server at `172.27.208.1:8080/mcp`, `.claude/settings.local.json`, `docs/mcp-setup.md` runbook), Unity `.gitignore`/`.gitattributes` (no LFS yet).
- **Renamed JANKENSTEIN → JANKENBOTS and unified folders.** User created the Unity project at `F:\jankenbots\jankenbots` (named it jankenbots). Moved the seeded repo (git history + docs + `.mcp.json`) **into** the Unity project root so it's one folder; renamed the Forgejo repo `jankenstein → jankenbots` + updated the remote; re-pointed the symlink to `~/claude/projects/jankenbots`. Unity project is a fresh URP/Input-System template (has `Assets/`, `SampleScene`, `InputSystem_Actions`). **MCP status: ✅ WORKING (verified 2026-07-10, mcp-for-unity-server v3.4.4).** Server binds `127.0.0.1:8067` (HTTP mode), bridged to WSL via `netsh portproxy 0.0.0.0:8068→127.0.0.1:8067`; Claude reaches `http://172.27.208.1:8068/mcp` (`.mcp.json`). **Key gotcha:** 8080 is unusable — it's in a Hyper-V/WinNAT reserved range (WSL2), bind fails with WSAEACCES/Errno 13; use a non-reserved port + a *distinct* proxy port. Full detail in `docs/mcp-setup.md`. **Next:** start a fresh Claude session from the project folder (loads the `unity` tools at session start), then build Milestone 1.

## External references

- Full design record: `DESIGN.md` (this repo) — control feel v0.1, weapon archetypes, lobby math, tech direction, netcode prior art.
- Prototype build-plan: `docs/prototype-plan.md`.
- Wiki (orientation): http://192.168.1.249:6876/projects/jankenbots
- Idea-phase history: `~/claude/archive/ideas/jankenstein/` (original brainstorm `plan.md` + session logs).
- Netcode prior art (Rocket League GDC talk, Fall Guys/Robocraft/Stumble Guys case studies, Gaffer On Games) — cited in `DESIGN.md` → References.
- **Unity MCP setup runbook:** `docs/mcp-setup.md`. Server = CoplayDev/unity-mcp in **HTTP mode host-side**; Claude (WSL) connects at `http://172.27.208.1:8080/mcp` (`.mcp.json` committed). Bridge pattern mirrors the UE servers (host-side HTTP + host-IP). Not yet stood up — needs the editor + package installed.