# Poly City Heist — 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/poly-city-heist-ih72q
- Target: Desktop (1440×900)
- Original idea: "a 3d game like gta 5"

## Summary
Poly City Heist is a 3D low-poly open-world arcade driving game where players evade police pursuit, collect hidden cash briefcases across a stylized city, perform stunt jumps, and reach the extraction safehouse.

## Who it is for
Casual arcade and driving game fans who enjoy low-poly open-world action during quick session breaks.

## Features (v1)
- Players can customize their getaway vehicle color and select wanted difficulty intensity.
- Players can drive, steer, accelerate, brake, reverse, and drift using keyboard controls.
- Players can collect 4 scattered cash briefcases with glowing beacon markers.
- Players can evade AI police cruisers that chase and ram the player vehicle.
- Players can unlock and navigate to the extraction safehouse after securing all briefcases.
- Players can toggle between three camera views: chase cam, top-down radar cam, and cinematic view.
- Players can flip or reset their vehicle position using the R key.
- Players can pause the game at any time to resume or restart.
- Players can view real-time stats including wanted star level, vehicle armor health, and cash secured on the HUD radar.

## Screens
- **Start / Menu Screen** — Displays game title, vehicle color and difficulty selectors, play button, and controls guide.
- **HUD Overlay** — Displays wanted stars, vehicle armor bar, cash secured, targets count, minimap radar, and objective text during gameplay.
- **Pause Screen** — Modal overlay to resume escape, restart heist, or exit to the main menu.
- **Game Over / Results Screen** — Displays heist success or failure status along with end-game statistics like cash stolen, briefcases recovered, and evaded cops.

## Data model
- **GameState**: playing: boolean, paused: boolean, difficulty: string, carColor: string, score: number, collectedBriefcases: number, totalBriefcases: number, armor: number, wantedLevel: number, copsCrashed: number, extractionActive: boolean, won: boolean
- **PlayerVehicle**: position: THREE.Vector3, velocity: THREE.Vector3, heading: number, mesh: THREE.Group
- **PoliceCar**: mesh: THREE.Group, velocity: THREE.Vector3, heading: number, sirenPulse: number, blueMesh: THREE.Mesh
- **Briefcase**: mesh: THREE.Group, x: number, z: number, collected: boolean
- **CollisionBox**: box: THREE.Box3, mesh: THREE.Mesh, type: string

## Rules and behaviour
- Controls: W/S/A/D or Arrow keys to drive and steer, Spacebar for handbrake drift, V to cycle camera, R to reset vehicle position, Escape to pause.
- Scoring: Collecting each briefcase awards $2,500 and increases wanted level; completing extraction awards a $10,000 bonus.
- Win Condition: Collect all 4 briefcases and reach the green safehouse extraction zone.
- Lose Condition: Player vehicle armor reaches 0 due to building collisions or police ramming attacks.
- Difficulty Ramp: Higher difficulty settings increase police chase speed and aggression.
- Physics & Collision: Axis-aligned and box collision checks prevent driving through buildings or outside city boundaries, triggering screen shake and armor damage on high-speed impact.

## Stack
Three.js with TypeScript and Vite
Three.js provides direct compatibility with the prototype's WebGL rendering approach, procedural geometry creation, camera systems, and minimal bundle overhead.
Alternatives: Babylon.js; Godot 4; Unity

## Milestones
1. Reproduce the prototype's core 3D scene, procedural city layout, and UI screens with real components and mock data.
2. Implement player vehicle physics, keyboard controls, drift mechanics, and camera view cycling.
3. Implement briefcase collection logic, minimap radar blips, and HUD score tracking.
4. Implement police AI chase behaviors, siren audio synthesis, and collision damage systems.
5. Implement extraction safehouse zone, win/loss flow, and end-game statistics screen.
6. Add automated unit and integration tests for game state transitions and collision rules.
7. Configure deployment pipeline and build instructions in README.

## 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 first. Write a short numbered plan to rebuild Poly City Heist as a production-quality 3D open-world driving game using Three.js, TypeScript, and Vite. Preserve the exact low-poly art style, UI styling, color themes, keyboard controls, police AI chase mechanics, and audio synthesis from the prototype. Ensure all game states (start, hud, pause, game over) function correctly with robust collision handling and responsive canvas sizing. Include a README with clear run instructions and basic tests.

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