# Downtown Outlaw 3D — build brief

This file is the specification for turning a clickable prototype into a real 3D game. AI coding agents read AGENTS.md automatically; humans should read it too.

- Prototype file: `prototype.html` in this folder (the clickable reference — keep its look, copy and behaviour).
- Prototype page: https://ideaxapp.com/app/downtown-outlaw-3d-8hvxn
- Target: Desktop (1440×900)
- Original idea: "a 3d game like gta 5, sound effects, day time"

## Summary
Downtown Outlaw 3D is a 3D open-world driving and action sandbox game where players navigate a city, collect cash, perform stunt jumps, and evade police heat. The core job it does for the player is delivering fast-paced urban driving thrills and arcade action directly in the browser.

## Who it is for
Action game and arcade driving fans looking for quick 3D sandbox sessions during breaks.

## Features (v1)
- Players can select from multiple heat levels (difficulty 1, 3, or 5)
- Players can choose between a fast Sports Car and a heavy SUV Truck
- Players can drive around a procedural 3D city grid with buildings, streets, and stunt ramps
- Players can accelerate, reverse, steer, and use a handbrake for drifting
- Players can collect pink cash briefcases scattered throughout the map for score
- Players can jump off stunt ramps for bonus cash and stunt points
- Players can evade AI police patrol cars that actively chase the player
- Players can avoid or crash into ambient city traffic and building blocks
- Players can monitor their health via an armor meter and track speed via a circular speedometer
- Players can pause the game or view detailed performance summaries upon car wrecking

## Screens
- **Main Menu** — Allows players to select heat level difficulty and vehicle type, view control instructions, and start the game.
- **HUD Overlay** — Displays real-time cash collected, armor strength, wanted stars, cop evasion timer, speedometer, and pause button.
- **Pause Screen** — Enables players to resume their session or quit back to the main menu.
- **Game Over Screen** — Shows wreckage stats including total cash stash, elapsed time, cops outrun, and stunts performed, with an option to replay.

## Data model
- **Player**: pos: Vector3, rot: number, vel: number, maxSpeed: number, accel: number, decel: number, steerSpeed: number, friction: number, width: number, length: number, isAirborne: boolean, airTime: number
- **GameState**: state: string, chosenCar: string, chosenHeat: number, score: number, armor: number, startTime: number, elapsedMs: number, copsOutrunCount: number, stuntCount: number
- **BuildingBlock**: minX: number, maxX: number, minZ: number, maxZ: number, height: number, isRamp: boolean
- **Collectable**: mesh: Object3D, radius: number
- **CopCar**: mesh: Object3D, lightBar: Object3D, sirenTimer: number, speed: number, width: number, length: number
- **TrafficCar**: mesh: Object3D, dir: number, speed: number, width: number, length: number

## Rules and behaviour
- Use W/A/S/D or Arrow keys to drive and steer the vehicle.
- Press Spacebar for handbrake sliding and drift mechanics.
- Hitting buildings or traffic reduces armor health; when armor hits 0%, the game ends.
- Collecting pink cash packages increases score by $250.
- Jumping off stunt ramps awards $100 and records a stunt.
- AI cop cars spawn based on selected heat level, tracking and chasing the player's position.
- Colliding with cop cars damages player armor and removes the cop.
- Press Escape or click the pause button to toggle the pause menu.

## Stack
Three.js with TypeScript and Vite
Three.js provides direct, lightweight WebGL rendering perfectly suited for performance-critical 3D arcade driving prototypes without unnecessary framework overhead.
Alternatives: Babylon.js; React Three Fiber

## Milestones
1. Milestone 1: Reproduce the prototype's core loop, menu screens, and Three.js 3D city scene with mock data.
2. Milestone 2: Implement vehicle physics, acceleration, friction, steering, and handbrake drift controls.
3. Milestone 3: Add collision detection for procedural building blocks and stunt ramps with jump physics.
4. Milestone 4: Implement AI cop pursuit mechanics, pathfinding towards player, and traffic spawning.
5. Milestone 5: Add Web Audio API procedural sound synthesizer for engine hums, crashes, sirens, and cash pickup chimes.
6. Milestone 6: Build HUD elements including wanted stars, speedometer, timer, and game over stats breakdown.
7. Milestone 7: Write basic unit tests for state management and deploy production build.

## Working agreements
- `prototype.html` is a single self-contained file with fake in-memory data. Use it as the reference for layout and interactions; do not ship its inline scripts as-is.
- Before coding, write a short numbered plan. Build milestone 1 first and stop for review.
- Keep a README with run and test instructions up to date. Add basic tests as you go.
- Accessibility floor: 16px+ text, 4.5:1 contrast, 44px touch targets, keyboard support.
- Ask only when something is genuinely ambiguous; otherwise make a sensible choice and note it in the README.

## Optional tool integrations (MCP)
If your agent supports MCP servers, these are the relevant ones (September 2026):
- Unity: official Unity MCP Server (Unity 6) or CoplayDev/unity-mcp — build the scene from prototype.html.
- Godot: @coding-solo/godot-mcp — scenes, nodes, run and debug.
- Blender: ahujasid/blender-mcp — models, materials, Rodin/Hunyuan3D mesh generation.
- 3D assets: Meshy MCP server (free tier) for generated meshes.
Prefer the browser build first; add engines and design tools only when the brief calls for them.

## Kickoff prompt
Read AGENTS.md and prototype.html thoroughly before starting. Create a short numbered plan to build a production-quality 3D browser game based on Downtown Outlaw 3D. Your first milestone is to replicate the exact core loop, UI screens, vehicle physics, and Three.js rendering setup found in the prototype. Maintain the exact styling, copy, and arcade driving mechanics. Ensure Web Audio API sound synthesis works correctly. Provide clear instructions in the README on how to run and test the application locally.

---
Prototype and brief released under CC0 via ideaxapp.com. Brief generated with Google Gemini (gemini-3.5-flash-lite); review before relying on it.