docs: PROJECT-BRIEF.md — game/design/resource orientation for Claude
CI / quality (push) Failing after 51s
CI / quality (push) Failing after 51s
CLAUDE.md covers tool operation; this covers what the game IS, where it sits in the roadmap, and where reference assets actually live. Also fixes a stale NAS path in README (RX-7 reference dir is 001-original-images/001-1993-Mazda-RX-7, not a top-level spaced name).
This commit is contained in:
@@ -0,0 +1,274 @@
|
|||||||
|
# PROJECT-BRIEF.md — What we're building and where everything is
|
||||||
|
|
||||||
|
> **Read this first, before `CLAUDE.md`.**
|
||||||
|
> `CLAUDE.md` tells you *how to operate the tools safely*.
|
||||||
|
> This file tells you *what the game is, why it's built this way, and where the
|
||||||
|
> resources live*. You need both.
|
||||||
|
>
|
||||||
|
> Verified against the live repo, the NAS, and Gitea on **2026-08-06**. Every
|
||||||
|
> path and number below was checked, not recalled.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. The game in one paragraph
|
||||||
|
|
||||||
|
**Tokyo Wangan Racing** is a Roblox night-driving game set on a neon Tokyo
|
||||||
|
expressway, built around a real 1993 Mazda RX-7 the owner actually owns. It is
|
||||||
|
modelled on **Tokyo Xtreme Racer**, not on lap-racing games: **Daikoku Futo PA
|
||||||
|
(the parking area) is the hub.** You park, choose how you want to run, and drive
|
||||||
|
out onto the Wangan. You never "join a match."
|
||||||
|
|
||||||
|
The core bet: **driving feel is the whole game.** Racing, economy, and
|
||||||
|
progression are all deliberately deferred until the car is genuinely fun to just
|
||||||
|
drive around. Do not add game layers on top of a car that doesn't feel good yet.
|
||||||
|
|
||||||
|
### The three modes
|
||||||
|
|
||||||
|
Selected in the PA, armed when you cross the exit gate, ended when you pull back
|
||||||
|
into the PA. Defined in `src/shared/Modes.luau`.
|
||||||
|
|
||||||
|
| Mode | 日本語 | What it is | Challenges? | Timed? |
|
||||||
|
|---|---|---|---|---|
|
||||||
|
| **CRUISE** | 流し | Free roam, bank kilometres, meet drivers | yes | no |
|
||||||
|
| **DUEL** | バトル | Open a gap and *hold* it — who breaks first | yes | no |
|
||||||
|
| **TIME ATTACK** | タイムアタック | Solo flying lap, sector splits, personal best | **no** | yes |
|
||||||
|
|
||||||
|
Cruise and Duel both allow challenges, so a cruise turns into a battle
|
||||||
|
organically. **Time Attack opts out on purpose** so a hot lap is never ruined —
|
||||||
|
that's a design decision, not an oversight. Don't "fix" it.
|
||||||
|
|
||||||
|
### The circuit
|
||||||
|
|
||||||
|
Closed loop, **~49,400 studs (13.8 km)**, samples evenly spaced 60 studs apart so
|
||||||
|
the loop closes seamlessly. Roughly a 2:46 lap at 300 km/h. Scale is
|
||||||
|
**1 stud = 0.28 m**. Coordinates: `+X = east`, `+Z = north`.
|
||||||
|
|
||||||
|
Landmark zones (themed, **not** geographically accurate): Daikoku Futo PA,
|
||||||
|
Rainbow Bridge, Odaiba (Unicorn Gundam + ferris wheel), Yamate-style tunnel,
|
||||||
|
Tokyo Tower replica, Tatsumi PA, bilingual green signage (大黒PA, レインボーブリッジ,
|
||||||
|
お台場, 辰巳PA).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Where you are in the plan
|
||||||
|
|
||||||
|
Source of truth: `docs/ROADMAP.md` and `docs/GDD.md`. Current position:
|
||||||
|
|
||||||
|
- **M0 — drive-only MVP: DONE.** Spawn, drive, switch cars, respawn, persistence.
|
||||||
|
- **M1 — make driving feel GOOD: IN PROGRESS. This is the current work.**
|
||||||
|
- done: constraint chassis (springs, prismatic suspension, servo steering,
|
||||||
|
motor wheels, engine braking), chase camera, two-layer engine sound
|
||||||
|
- **not done: import the real RX-7 mesh** (`docs/MESH_SWAP.md`)
|
||||||
|
- **not done: real 13B rotary audio** from the owner's actual car
|
||||||
|
(`docs/ROTARY_SOUND.md`) — current loops are stand-ins
|
||||||
|
- **not done: tune accel curve + grip** — needs a Studio playtest
|
||||||
|
- **M2 — more cars + map polish:** map v3 and ambience done; more meshes pending.
|
||||||
|
- **M3+ — racing, economy, hardening, traffic AI:** deliberately not started.
|
||||||
|
|
||||||
|
> **M1's exit test:** *the RX-7 is genuinely fun to just drive around.*
|
||||||
|
> Ship nothing else until that's true. If asked to build a racing/economy
|
||||||
|
> feature, flag that it's M3/M4 and confirm before starting.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Repo layout and architecture
|
||||||
|
|
||||||
|
Repo: `~/roblox/tokyo-wangan-racing` (Git Bash path on this box).
|
||||||
|
|
||||||
|
**Server-authoritative: clients request, the server decides.** The RX-7
|
||||||
|
allowlist and anti-cheat are server-side. Keep the client dumb.
|
||||||
|
|
||||||
|
```
|
||||||
|
ReplicatedStorage/Shared src/shared GameConfig, Cars, Circuit, Modes,
|
||||||
|
Chassis, Remotes, ProfileTemplate
|
||||||
|
ServerScriptService/Server src/server init.server + managers
|
||||||
|
ServerScriptService/ServerPackages ServerPackages ProfileStore (Wally)
|
||||||
|
StarterPlayerScripts/Client src/client HUD, car picker, controllers
|
||||||
|
```
|
||||||
|
|
||||||
|
Mapping is declared in `default.project.json` (Rojo).
|
||||||
|
|
||||||
|
| Module | Responsibility |
|
||||||
|
|---|---|
|
||||||
|
| `src/server/MapBuilder.luau` | **3,479 lines — the big one.** Procedurally builds the entire expressway, PA, ramps, barriers, signage. |
|
||||||
|
| `src/server/CarManager.luau` | Spawns the equipped car; enforces the RX-7 allowlist |
|
||||||
|
| `src/server/ModeManager.luau` | Mode selection, exit-gate arming, mode end |
|
||||||
|
| `src/server/DataManager.luau` | ProfileStore wrapper — session lock, reconcile, Studio mock |
|
||||||
|
| `src/server/AntiCheat.luau` | Speed/teleport sanity check — a speed bump, not a fortress |
|
||||||
|
| `src/server/Ambience.luau` | Atmosphere haze, bloom, 22:00→03:00 clock drift |
|
||||||
|
| `src/shared/Circuit.luau` | The 1,050-line circuit spline — sample positions, PA geometry |
|
||||||
|
| `src/shared/Chassis.luau` | Shared chassis tuning constants |
|
||||||
|
| `src/client/ChassisController.luau` | Drives the chassis client-side (driver owns network physics) |
|
||||||
|
| `src/client/CameraController.luau` | Damped chase cam, flat horizon, speed FOV kick |
|
||||||
|
| `src/client/SoundController.luau` | Two-layer engine crossfade + tyre squeal |
|
||||||
|
|
||||||
|
**Cars:** RX-7 (restricted), City Runabout (public default), Silvia S15, Skyline
|
||||||
|
GT-R R34, stylized hypercar. The **RX-7 is demo-locked** to the owner + his son
|
||||||
|
via `GameConfig.RX7AllowedUserIds`, enforced in `CarManager` and the `EquipCar`
|
||||||
|
remote. Stats only affect feel — no prices, no unlocks in the MVP.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Resources you can reach — and how
|
||||||
|
|
||||||
|
### 4a. Live Roblox Studio (this machine, local)
|
||||||
|
|
||||||
|
Two channels, different jobs. **Use [A] to verify what [B] did.**
|
||||||
|
|
||||||
|
```
|
||||||
|
[A] MCP bridge -> READ run Luau in the datamodel, screenshot the viewport
|
||||||
|
[B] Rojo -> WRITE push .luau source into Studio (~1 s)
|
||||||
|
```
|
||||||
|
|
||||||
|
- `mcp__roblox_studio__execute_luau` — `datamodel_type` **must be `"Edit"`**,
|
||||||
|
never `"Server"` (Server edits a throwaway Play copy that dies on stop).
|
||||||
|
- `mcp__roblox_studio__screen_capture` — Studio's **3D viewport only**. Not the
|
||||||
|
desktop, not Explorer, not Blender.
|
||||||
|
- Rojo: `rojo serve default.project.json --port 34872`, then **somebody must
|
||||||
|
click Rojo → Connect in Studio.** It never auto-connects, and an ESTABLISHED
|
||||||
|
socket on 34872 is idle heartbeat, *not* a sync session.
|
||||||
|
|
||||||
|
Full operational detail, version pins, and the failure decoder: **`CLAUDE.md`**.
|
||||||
|
|
||||||
|
### 4b. Reference material on the NAS (1.5 GB, verified present)
|
||||||
|
|
||||||
|
Host `unraid-1` (10.10.10.43), reachable over SSH. Base path:
|
||||||
|
|
||||||
|
```
|
||||||
|
/mnt/user/data/yy-roblox-games/0-tokyo-wangan-racing/
|
||||||
|
```
|
||||||
|
|
||||||
|
| Folder | Contents (verified counts) |
|
||||||
|
|---|---|
|
||||||
|
| `001-original-images/001-1993-Mazda-RX-7/` | **12 files** — the real car, for the mesh swap |
|
||||||
|
| `001-original-images/002-1993-Nissan-Skyline-GT-R/` | **38 files** |
|
||||||
|
| `003-google-earth-images/` | **12 files** — `daikoku-futo-01..12.png`, aerial geometry |
|
||||||
|
| `004-video-reference/` | `aerial/`, `contact-sheets/`, `docs/`, `entrance-routes/` |
|
||||||
|
| `002-completed-models/` | empty — finished models land here |
|
||||||
|
|
||||||
|
> ⚠️ **The README currently prints a stale path** for the RX-7 reference
|
||||||
|
> (`001-1993 Mazda RX-7/` with spaces, at the top level). The real path is
|
||||||
|
> `001-original-images/001-1993-Mazda-RX-7/` with hyphens. Use the real one.
|
||||||
|
|
||||||
|
Copy a file over rather than working blind:
|
||||||
|
```bash
|
||||||
|
scp unraid-1:'/mnt/user/data/yy-roblox-games/0-tokyo-wangan-racing/003-google-earth-images/daikoku-futo-01.png' /tmp/
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4c. Reference material committed in-repo
|
||||||
|
|
||||||
|
- `reference/ramps/` — 12 integrity-checked photos of Daikoku/Oi/Heiwajima/
|
||||||
|
Shibaura PAs, plus `INDEX.md`, `BUILD_SPEC.md`, and OSM/satellite scripts.
|
||||||
|
**All CC BY / CC BY-SA — reference-only for shape study. Do not trace directly
|
||||||
|
into shipped assets without attribution.**
|
||||||
|
- `docs/daikoku-reference-spec.md` — measured spec for the PA entrance geometry
|
||||||
|
- `docs/japanese-road-standards.md` — real road-geometry standards
|
||||||
|
- `docs/CAR_PHYSICS_REFERENCE.txt`, `docs/MESH_SWAP.md`, `docs/ROTARY_SOUND.md`
|
||||||
|
- `assets/audio/` — current stand-in RX-7 loops (idle / rev / whistle)
|
||||||
|
- `audio-work/` — raw recordings from real car meets, for the rotary audio work
|
||||||
|
- `c1_georeference.json` — georeferencing data behind the circuit
|
||||||
|
|
||||||
|
### 4d. Git / CI
|
||||||
|
|
||||||
|
Remote: `ssh://[email protected]:2222/jesse/tokyo-wangan-racing.git`
|
||||||
|
(self-hosted Gitea on UNRAID-1, SSH key auth already working from this box).
|
||||||
|
|
||||||
|
CI runs on a **self-hosted Gitea Actions runner** (`.gitea/workflows/ci.yml`),
|
||||||
|
Ubuntu 24.04 job container — rojo's binary needs glibc 2.39.
|
||||||
|
|
||||||
|
### 4e. Existing tooling — check before writing new probes
|
||||||
|
|
||||||
|
`tools/` already holds **109 files, 58 of them diagnostic/verification scripts**
|
||||||
|
(`diag_*.luau`, `verify_*.luau`, `capture_*.py`, `check_*.luau`). There is a
|
||||||
|
very high chance a probe already exists for what
|
||||||
|
you need — `verify_auxlane.luau`, `verify_shared_ramps.luau`,
|
||||||
|
`check_live_source.luau`, `scripts/verify_map.luau`, and capture helpers for
|
||||||
|
flyovers/ramps/defects. **Look there first.**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Quality gates — CI enforces all three
|
||||||
|
|
||||||
|
```bash
|
||||||
|
stylua --check src/ # formatting
|
||||||
|
selene src/ # lint
|
||||||
|
rojo build --output build.rbxl # must compile
|
||||||
|
```
|
||||||
|
|
||||||
|
Conventions:
|
||||||
|
- Tunables go in `GameConfig`, not scattered magic numbers.
|
||||||
|
- Add a save key by adding it to `ProfileTemplate` (auto-reconciles). Never
|
||||||
|
remove a key without a migration.
|
||||||
|
- Test in Studio after every server change (ProfileStore uses a mock in Studio).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. The things that will bite you
|
||||||
|
|
||||||
|
These are compressed from hard-won experience. The long versions live in
|
||||||
|
`CLAUDE.md` — but these three matter most:
|
||||||
|
|
||||||
|
### Never regenerate hand-deleted work
|
||||||
|
**The single most important rule on this project.** If the user deleted
|
||||||
|
something in Studio, the *source* must honor it or the next rebuild silently
|
||||||
|
resurrects it — and they will catch it immediately.
|
||||||
|
|
||||||
|
Live example, currently in `MapBuilder.luau`:
|
||||||
|
```lua
|
||||||
|
AUX_SUPPRESS_FROM = 525 -- user deleted this aux-lane stretch
|
||||||
|
AUX_SUPPRESS_TO = 550
|
||||||
|
AUX_BLEND = 5 -- smoothstep; a hard cut caused a 26-stud fence jog
|
||||||
|
```
|
||||||
|
**Do not remove that suppression.** Hand-placed assets live in
|
||||||
|
`workspace.PAProps`, which the builder never touches. Before any rebuild, ask:
|
||||||
|
*does this regenerate something removed by hand?*
|
||||||
|
|
||||||
|
### Measure before reasoning, and re-measure after
|
||||||
|
Write a **read-only probe**, get real numbers, *then* form a theory. A code
|
||||||
|
change is not proof — verify against the bug's signature. Enumerate names, not
|
||||||
|
just totals: a raw count hides a partial removal.
|
||||||
|
|
||||||
|
### Beat the `require()` cache
|
||||||
|
After a Rojo sync the datamodel still holds **old bytecode** — no error, no
|
||||||
|
warning, and you will measure the previous build and believe it:
|
||||||
|
```lua
|
||||||
|
local tmp = game.ServerScriptService.Server.MapBuilder:Clone()
|
||||||
|
tmp.Parent = game.ServerScriptService
|
||||||
|
local MapBuilder = require(tmp) -- fresh bytecode, guaranteed
|
||||||
|
```
|
||||||
|
|
||||||
|
### Verified-good baseline (2026-08-06) — regression-check against these
|
||||||
|
|
||||||
|
| metric | value |
|
||||||
|
|---|---|
|
||||||
|
| total parts | 16,788 |
|
||||||
|
| PAWestSlip | 60 segs, 34.4° total bend, worst 1.4°, 0 kinks >5° |
|
||||||
|
| PAEastSlip | 60 segs, 30.7° total bend, worst 1.3°, 0 kinks >5° |
|
||||||
|
| AuxLane parts | 30 — **samples 525–550 deliberately absent (user-deleted)** |
|
||||||
|
| barrier coverage | 823 samples, 0 unguarded |
|
||||||
|
| fence jogs >10 studs | 0 |
|
||||||
|
|
||||||
|
### Never fabricate
|
||||||
|
If Studio is closed, say "Studio is closed." Never invent a screenshot, a part
|
||||||
|
count, or a measurement you didn't obtain. `{'error': '', 'isError': True}` on
|
||||||
|
every MCP call means **Studio is closed** — not that your script is broken.
|
||||||
|
Reporting a blocker honestly always beats a plausible-looking fake.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. First five minutes in a new session
|
||||||
|
|
||||||
|
```bash
|
||||||
|
tasklist | findstr /I "Roblox" # 1. is Studio even running?
|
||||||
|
claude mcp list # 2. bridge registered + connected?
|
||||||
|
curl -s http://127.0.0.1:34872/api/rojo # 3. rojo serving?
|
||||||
|
cd ~/roblox/tokyo-wangan-racing && git status --short && git log --oneline -5
|
||||||
|
```
|
||||||
|
|
||||||
|
Then read `docs/ROADMAP.md` to confirm what milestone is active, and check
|
||||||
|
`tools/` for an existing probe before writing a new one.
|
||||||
|
|
||||||
|
**Working state as of 2026-08-06:** clean tree, 0 uncommitted files, HEAD at
|
||||||
|
`dc0df91`. (An older note in `START-HERE.md` warns about "36 uncommitted files"
|
||||||
|
on the Linux box — that has since been committed and pushed. Trust `git status`
|
||||||
|
over that note.)
|
||||||
@@ -102,4 +102,5 @@ the `EquipCar` remote).
|
|||||||
|
|
||||||
One function changes: `CarManager.buildCarModel`. Full step-by-step in
|
One function changes: `CarManager.buildCarModel`. Full step-by-step in
|
||||||
`docs/MESH_SWAP.md`. Reference photos live on the NAS at
|
`docs/MESH_SWAP.md`. Reference photos live on the NAS at
|
||||||
`unraid-1:/mnt/user/data/yy-roblox-games/0-tokyo-wangan-racing/001-1993 Mazda RX-7/`.
|
`unraid-1:/mnt/user/data/yy-roblox-games/0-tokyo-wangan-racing/001-original-images/001-1993-Mazda-RX-7/`
|
||||||
|
(12 files). See `PROJECT-BRIEF.md` for the full reference-asset inventory.
|
||||||
|
|||||||
Reference in New Issue
Block a user