# 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-5b2f1
- Target: Desktop (1440×900)
- Original idea: "a 3d game like gta 5, sound effects, day time, easy to play game"

## Summary
Poly City Heist is a 3D low-poly open city driving and action game inspired by GTA. Players drive a getaway car through a procedurally generated city grid to collect cash bags while evading AI police cruisers before a timer runs out, then navigate to the central safehouse.

## Who it is for
Action arcade and retro racing fans who enjoy quick, casual 3D driving escapes on desktop browsers.

## Features (v1)
- Players can choose between Easy, Normal, and Hardcore difficulty settings modifying police aggression and timers.
- Players can steer, accelerate, reverse, and drift using keyboard inputs (WASD or Arrow keys + Spacebar).
- Players can collect 5 scattered golden cash bags worth $10,000 each across the city grid.
- Players can trigger the safehouse checkpoint beacon once all cash bags are secured.
- Players can evade police patrol and pursuit vehicles reacting with siren lights and chase AI.
- Players can monitor real-time vehicle speed, remaining timer, wanted level stars, and cash total via HUD.
- Players can view a radar minimap showing player position, loot bags, safehouse, and nearby cops.
- Players can toggle Web Audio API synthesizer sound effects and engine hums or mute audio.
- Players can pause, resume, and restart matches instantly through modal overlays.

## Screens
- **Start Menu** — Title screen with game overview, controls guide, difficulty selector, and 'Start Heist' button.
- **Gameplay HUD** — Active driving screen showing cash secured, countdown timer, bags remaining, wanted level stars, speed, minimap, and pause/mute controls.
- **Pause Menu** — Modal overlay allowing players to resume drive or restart the match.
- **Game Over / Victory Screen** — Displays final heist status (success or failure), total cash collected, remaining time, and a try again button.

## Data model
- **Game**: state: string, difficulty: number, timer: number, cash: number, bagsFound: number, totalBags: number, wantedLevel: number, gameTime: number
- **Player**: pos: Vector3, rot: number, speed: number, maxSpeed: number, accel: number, decel: number, turnSpeed: number, radius: number
- **Cop**: pos: Vector3, rot: number, speed: number, active: boolean, state: string, radius: number, targetTimer: number
- **LootBag**: position: Vector3, collected: boolean, radius: number
- **Safehouse**: pos: Vector3, radius: number, active: boolean

## Rules and behaviour
- Controls: W/ArrowUp accelerates, S/ArrowDown brakes/reverses, A/D or ArrowLeft/Right steers, Spacebar executes handbrake drift.
- Objective: Collect all 5 cash bags then reach the central safehouse before the 60s-90s timer expires.
- Police AI: In Normal and Hardcore modes, police units patrol the roads and pursue the player when within range, causing an immediate failed game over upon collision.
- Collision detection: Simple bounding box checks against city buildings and perimeter walls prevent driving through structures, applying a bounce-back velocity penalty.
- Audio: Procedural Web Audio API oscillator nodes synthesize engine hums, collection chimes, police sirens, and crash impacts without external audio files.

## Stack
Three.js with TypeScript and Vite
Three.js is lightweight, has zero complex compilation overhead for pure 3D arcade games, matches the single-file prototype architecture directly, and provides robust primitives and lighting support.
Alternatives: Babylon.js; Godot 4; React Three Fiber

## Milestones
1. Milestone 1: Scaffold Vite + Three.js project structure, reproduce prototype scene setup, lighting, procedural city grid generation, and player car controls.
2. Milestone 2: Implement vehicle physics, wall collision detection, camera follow interpolation, and dashboard speedometer.
3. Milestone 3: Add collectible cash bags, loot pickup logic, screen banner alerts, and radar minimap rendering.
4. Milestone 4: Implement AI police vehicles with patrol/pursuit states, siren lighting flash, and bust/collision triggers.
5. Milestone 5: Implement Web Audio API synthesizer sound engine for engine revs, sirens, chimes, and crash effects.
6. Milestone 6: Build UI screens (Start Menu, Pause Menu, Game Over / Victory Modal) and difficulty state management.
7. Milestone 7: Write unit and integration tests for game logic, add responsive canvas scaling, and prepare production build deployment.

## 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
Please read AGENTS.md and prototype.html first to understand the game requirements and design. Your task is to build a production-quality desktop 3D game called Poly City Heist based on the provided single-file HTML prototype. Create a clean TypeScript and Vite project using Three.js. Follow a structured plan: first set up the 3D scene, procedural city, and player vehicle controls; second, implement collision detection and smooth camera follow; third, add collectible cash bags, radar minimap, and HUD; fourth, integrate AI police patrol/pursuit behaviors and Web Audio API sound effects; fifth, build start, pause, and game over overlay screens matching the original color scheme and styling. Ensure the game is fully playable with smooth arcade physics, includes a README with clear run instructions, and contains basic tests. Preserve the original look, copy, and arcade behavior precisely.

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