StreetQuest — real-world GPS war game

Three games stacked on one real-world map:

• Strategy (Generals: Zero Hour style) — pick a faction, plant a base where you stand, build power / supply / barracks / factory / airfield / turrets on real timers, train an army, capture oil derricks and siege rival bases. Battles are auto-resolved.

• Life sim (The Sims style) — your commander has Hunger, Energy, Social and Fun that drain in real time. Eat food you find, sleep at your base, hang out with nearby players or check in at real cafés, bars and parks. Time alone never drags a need below a floor, and a long break counts as a night's sleep, so coming back never means a miserable commander. Mood scales XP, combat HP and Street Empire income (all tunable in Admin → Game settings → Life sim).

• FPS (Counter-Strike / CoD style) — walk within 200 m of an enemy base while other players are online and you can breach it: a live first-person match (capture the zone or wipe the defenders + garrison bots, no respawns). World bosses roam the map with shared HP — raid them in first person or bombard them.

• RPG — your commander is a hero: pick a class (Vanguard, Marksman, Engineer, Quartermaster, Warlord), spend attribute points (STR/AGI/INT/CHA) each level, and loot gear (weapon/armor/gadget, 4 rarities, random affixes). The equipped weapon is your FPS gun (rifle, SMG, marksman rifle, LMG). Salvage gear for 🔩 scrap, forge it higher. A 13-chapter campaign plus 3 daily quests guide you through every system.

• Deeper RTS — unit counters (infantry / vehicle / air), Generals-style veterancy (Veteran → Elite → Heroic), a research tree paid in coins + scrap, General's Powers bought with Command Points (Supply Drop, Spy Drone, Paradrop, Artillery Barrage, Battle Cry…), and permanent outposts on the real map: capture them, garrison troops, collect tribute, fight the faction war.

• Clash of Clans rules — sieges score ★★★ by destruction %, loot scales with destruction, trophies and leagues (Bronze → Legend, league bonus loot), Army Camps cap housing space, Builder's Huts add concurrent builders, the Vault protects coins, Walls add HP, 💎 gems rush any timer, attacking breaks your shield, and you can take revenge from your battle reports.

• Tower defense on the real map — build towers where you stand inside your territory (🔫 MG Nest, 🎯 Sniper, 💣 Cannon, 🚀 SAM, ⚡ Tesla). Their range rings are on everyone's map and they shoot rival commanders who walk in: you have street HP, get downed (lose some coins to the tower owner, 3 min recovery), and rookies below level 3 are spared. Fight back by running in and planting C4 (hold to plant — closer means a bigger blast) or by marching a squad at it. Raider waves march on bases (HQ 2+) every hour or two — or provoke one for ×1.5 bounties. Towers, guard squads and base turrets (yours and your crew's) shoot them live on the map; commanders near the base call in ✈️ airstrikes; leakers steal coins.

• Real-time strategy on the map — deploy squads from your base. They march at unit speed (everyone sees them, enemy composition is fogged without Radar), guard a spot (shoot rival commanders, defend against raiders, reinforce nearby bases/outposts), or attack an enemy tower, squad, base or outpost. Redirect or recall them mid-march. Base buildings are drawn around every base so you can scout rivals.

• Street Empire (idle tycoon) — an AdVenture Capitalist-style idle game in 🎮 Play: 11 street businesses (hot dog cart → spaceport), tap to run a cycle or hire a manager to automate it, count milestones (speed ×2), cash upgrades, offline earnings (vault upgrades), fame stars (prestige, +2% each), empire ranks that pay coins and gems in the main game, and dividends every 4 h. 🔋 Power cells on the map double income for 30 min (stack to 4 h).

• Every step counts — a phone pedometer (accelerometer peaks gated by a walking rhythm, so shaking doesn't count) reports steps while the game is open; GPS distance on foot fills in when the sensor can't. Steps today boost empire income up to ×2 at 10,000; banked steps buy instant Step Rushes; step quests, milestones and a weekly world goal. The server caps every report by a believable cadence. (A web page can't count while it's closed — a native wrapper with HealthKit / Health Connect would be needed for that.)

• Chests open on the spot (with a celebration) and C4 is planted by holding a button — the closer you dare to stand to the tower, the bigger the blast (decided by the server from your position).

• Squad runs — start a run solo, as a 🏎️ race (podium pays +50% / +25%) or a 🤝 co-op run (+20% per teammate); squadmates' live positions show on the map. Crew pings (⚔️ attack / 🆘 help / 🚩 rally / 💰 loot) coordinate it all.

• Street combat — shoot rival commanders, enemy towers and squads within 60 m (headshots, cooldown, hero damage bonus). Downing someone takes coins and trophies. Rookies (< level 3) can't fight or be shot.

• Superweapons (Generals: Zero Hour) — Dragon ☢️ Nuclear Missile, Coalition 🔆 Particle Cannon, Insurgency 🚀 SCUD Storm. Built at HQ 4, charge for hours, hit anywhere within 5 km. Everyone near the target sees a public countdown and can run; SAM sites intercept missiles; the blast hits towers, squads, bases, garrisons and commanders; nukes and SCUDs leave radiation/toxins that keep hurting anyone who walks in.

• King of the hill flags — plant a flag on a real spot; it pays while you hold it. Rivals capture it by standing on it for 60 s while none of your crew is there.

• Bounties — put coins on a rival's head; whoever downs them (gun, tower, superweapon) collects.

• Photo & text posts pinned to places — only visible to players who walk there; likes pay XP, reports hide abuse.

• 3D art kit — every emoji in the game (UI, server messages, translations, map markers) is drawn as a glossy, outlined, top-lit vector icon with idle animations (src/components/art); preview them all with npx tsx scripts/art-preview.ts art.html.

• Polish — synthesized sound effects (Web Audio, no files; mute button), 3D game-feel animations, in-app dialogs instead of browser pop-ups, iPhone (notch/landscape) and iPad (side panels) layouts, achievements for every system.

• Story missions — an 8-chapter campaign played on real streets: waypoints are placed around wherever you are, with go (reach a marker), find (hidden spot, hot/cold detector only) and hold (stay in a zone) steps.

• GPS games — 🧭 Treasure Hunt (hot/cold, the spot never leaves the server), 🏃 Street Sprint (distance on foot; driving doesn't count) and 🏁 Checkpoint Rally.

• Goals — a weekly 🌍 world operation everyone works on together, a weekly faction goal (with a live faction race) and permanent personal milestones with tiers. Everyone who contributed claims the shared rewards.

• Store & sponsor spots — gem packs via Stripe Checkout, coin offers / instant heal / energy drink / base shield paid in gems, and rewarded sponsor spots (timed server-side, daily cap, views and clicks per sponsor).

• Live game settings — Admin → Game settings edits every tunable (reach radius, rewards, multipliers, timers, ranges, goals, gem packs, ads…) and Admin → Game data edits unit/building/tower/item/research stats. Changes go live within ~15 s, no redeploy.

Every layer feeds the others: hero bonuses change battle maths, build times, income and FPS stats; mood scales XP; loot funds research; territory funds the army.

• Real places — restaurants, cafés, shops, pharmacies, gyms and parks come from OpenStreetMap, with their real names. Jobs happen at them: a 🍔 burger delivery starts at a real burger joint and ends at another real place, a ☕ check-in is at a real café, and food spawns sit on real restaurants instead of random street corners.
• 3D city & play from home — tap 🚗 DRIVE to drive a cartoon car through your real streets in 3D (real building footprints and heights, roads, parks, water and store signs, storybook toon style with day/night). From home or in test mode the car is your commander: where you drive is where you are, jobs are beacons of light, loot is collected by driving through it (money and beacons whose map spot is inside a building move to the nearest street, so they're never hidden by walls or out of the car's reach). Walking with GPS, the car follows you. Cells without map data yet are drawn as a fantasy village. In the realistic style every building wears a material — the map's building:material (or the colour OpenMapTiles gives that material), else a guess for its kind and region: Tehran's travertine stone and brick blocks, plaster, concrete panels, metal-clad sheds — with its paint colour from the map when it has one. Blocks of flats get balconies on their street side and shop windows on the ground floor, flat roofs get a parapet and (in the Middle East) evaporative coolers and water tanks, pitched roofs are gabled, hipped (with a real ridge) or skillion, and places of worship in the region are mosques with a tiled onion dome and two minarets. Balconies and rooftop kit are drawn only within 320 m and never on lite phones (src/components/drive/tileMesh.ts, world3d.ts).
• Iran's streets in 3D — the traffic is what you see in Tehran: Prides everywhere, Peugeot 206 / 207 / Pars, Samands, Tibas, old Peykans, crossovers, yellow taxis with their roof sign and yellow plate, the blue Zamyad pickup (empty or stacked with fruit crates), the Khavar light truck under its tarp, red city buses and white minibuses on the main roads and motorbikes — commuters and delivery bikes with their box — riding by the kerb and leaning into corners (src/lib/fleet.ts: the mix, paints and sizes). Each model is built once from its side profile (wheel arches cut in) with its own lamps, grille, bumpers, mirrors and the Iranian number plate, and traffic draws every copy of a model instanced — a handful of draw calls for the whole street (src/components/drive/fleet3d.ts). Cars keep a bumper-to-bumper gap sized to what's ahead, stop at red lights and brake for you.
• Real 3D car models — the Pars (Peugeot 405), Samand (and the Samand taxi), Shahin, Tondar 90 (Dacia Logan), Xantia, the Zamyad pickup and the crossover are real models, built from CC BY 4.0 Sketchfab models by npm run assets:cars (; the sources are big and not in git — put them in ). The build bakes each texture into vertex colours, removes everything you can't see from outside (the cabin, engine and underside: it draws the car from 60 directions with the glass opaque), levels the car, scales it to the real car's length, finds its four wheels, sorts the rest into the parts traffic instances (paint, trim, glass, head lamps, tail lamps, wheel) and simplifies them to a near and a far version (~16–23k / ~3–7k triangles, 120–260 KB each, meshopt-compressed). Files are named by their hash (, listed in ) and served ; the service worker keeps them cache-first and drops a car's older build. In drive mode they download in the background while traffic shows the drawn models, then swap in () — full detail within 30 m, the far version beyond (and everywhere on lite phones). lists a source's materials and draws each one highlighted, draws the result; new cars go in the list with rules for their material names. Credits are on , linked from drive mode. Only CC BY models are used: NonCommercial ones (e.g. CC BY-NC-SA) aren't allowed in a game with paid features. People walk the pavements — men in shirts and jackets, women in a manteau and headscarf or a chador — turning back at walls or carrying on round the corner, and are solid (). The pavements also have blue-and-yellow charity boxes every block or two and green newspaper kiosks on the main roads.

Plus the original layer: Pokémon-GO-style spawns, GTA-style timed runs, real package deliveries, location messages, friends/chat/events, an admin panel and SEO/marketing tooling.

Run locally

npm install
docker compose up -d        # local Postgres
cp .env.example .env        # defaults match docker-compose
npx prisma db push          # create tables
npm run db:seed             # demo data (SEED_LAT=.. SEED_LNG=.. to seed near you)
npm run city:pack -- iran   # street detail and real places for the whole country (optional, ~4 min; or one city: tehran)
npm run dev                 # http://localhost:3000

No login: opening /play creates a guest commander automatically (saved in a 1-year cookie); players can rename their callsign in Profile. To become admin, set ADMIN_KEY and open /admin?key=<ADMIN_KEY> once in a browser that has played.

Test mode (no walking needed): anyone can tap 🕹️ (or "Test mode — no GPS" when location is off). Then tap the map to move, and every "Get closer" button becomes Teleport here. It's remembered in the browser until you switch it off. Set TEST_MODE=off in production to limit it to admins once the game is live.

Faster timers for testing: GAME_SPEED=600 npm run dev makes construction and training 600× faster (ignored in production). Jump straight into a live fight with /play?match=<id>.

Street Arena (live multiplayer): run the realtime server next to the app and point the app at it:

npm run rt                                          # ws://localhost:8787 (uses AUTH_SECRET from .env)
NEXT_PUBLIC_RT_URL=ws://localhost:8787 npm run dev  # or put NEXT_PUBLIC_RT_URL in .env
npm run rt:smoke                                    # two scripted players: open-city fight, then a match with bots
npm run rt:sim -- bomb                              # a whole match of bots in simulated time (tdm | ffa | bomb)

Without NEXT_PUBLIC_RT_URL the 3D city still works (driving, walking, other drivers over HTTP) but there's no fighting. The soldier and gun models are generated in Blender from assets/blender/arena.py: npm run assets:arena rebuilds public/models/arena/*.glb (add -- preview.png to render a preview).

Fast checks: npm test runs the unit tests, the typecheck and the translation check in about a minute. npm run test:unit alone runs tests/*.test.ts with Node's own test runner (no browser, no database): opening hours and name matching (localData), map styles (no keyed providers), the 3D city's buildings (materials, balconies, mosques, a triangle budget) and game balance (guns by range, match prizes, medals, economy defaults).

End-to-end tests (Playwright): npm run test:e2e starts its own dev server on port 3200 against a separate streetquest_e2e database (create it once: docker compose exec db createdb -U postgres streetquest_e2e; override with E2E_DATABASE_URL) and runs two suites:

• npm run test:e2e:api — server behaviour: accounts, bans, referrals, admin access, the economy (daily, store, ads, selling), base building, claims, lobbies, runs, play-from-home travel, SEO/health/security headers, store data from Snappfood / Torob / Divar (served by a stub: menus, hours, reviews, walk-in stores and their catalogs), who's online — including double-tap races (two identical requests at once must never charge or pay twice).
• npm run test:e2e:ui — the game in a phone-sized Chrome: first visit, GPS on/off, bottom nav, store, double-tap on buttons, the marker following GPS. Uses your installed Google Chrome (PW_CHANNEL=chromium for Playwright's own).

Older smoke scripts (need the dev server running, ideally with GAME_SPEED=600): npm run test:smoke, npm run test:features (settings, army delivery, bag multi-sell, goals, store, ads, GPS games, story) and npm run test:mp (lobbies, squad runs, towers shooting players, C4, squads, skirmishes, raider waves, pings).

Deployed and the store layers are empty? Open /api/health?ext=1: it says whether the server can reach Snappfood, Torob and Divar. Iranian sites often refuse servers abroad (Snappfood answers Vercel with 403) — run the relay in Iran (Deploy → Snappfood from abroad) and point SNAPPFOOD_URL (or TOROB_URL / DIVAR_URL) at it, or host in Iran.

On your phone: GPS only works on https:// or localhost. Run npm run tunnel and open the https://….trycloudflare.com link it prints.

How it works

Area	Where
Strategy rules: factions, buildings, power, units, auto-resolved battles (pure, shared client/server)	src/lib/rts.ts, src/app/api/{base,battle}
RPG: classes/attributes/bonus folding, gear rolls, quests, General's Powers (pure)	src/lib/{hero,gear,quests,powers}.ts, src/server/{hero,quests}.ts, src/app/api/{hero,powers}
Territory: deterministic outposts per ~900 m cell, only ownership + garrison stored	src/lib/outposts.ts, src/app/api/outposts
Life sim: needs decay computed from a stored snapshot + timestamp, so no background jobs; mood multiplies XP in grant()	src/lib/sims.ts, src/server/needs.ts, src/app/api/sims
World bosses: deterministic per ~1.3 km region and 2 h window like spawns; only damage is stored. The killing hit pays every contributor	src/lib/bosses.ts, src/server/boss.ts
FPS: the arena is generated from the match seed on every client. Clients POST position + hits ~7×/s; the server owns HP, kills, capture and the result. The first live human is the host and runs bot/boss AI; if it goes quiet the next player takes over	src/lib/arena.ts, src/server/match.ts, src/components/fps/Fps.tsx
Squad-run lobbies (race / co-op): one lobby per run spawn, state advances whenever a member polls (~1×/s)	src/lib/lobbies.ts, src/server/lobby.ts, src/app/api/lobby
Street Empire: pure economy rules shared by client and server; the server settles the stored snapshot to "now" on every request (no background jobs), the client runs the same maths between syncs	src/lib/idle.ts, src/server/empire.ts, src/app/api/empire, src/components/game/Empire.tsx
Steps: accelerometer pedometer in the browser, batched reports capped by cadence per day, GPS-distance fallback in /api/loc	src/components/game/steps.ts, src/lib/steps.ts, src/server/steps.ts, src/app/api/steps
Art kit: icons as vector shapes + shared gradient materials, one lazily-filled SVG sprite; a MutationObserver swaps emoji text for art without touching React's text nodes

Deploy

Vercel

1. Push this repo to GitHub, then on vercel.com: Add New → Project → import the repo.
2. In the project: Storage → Create Database → Neon (Postgres) and connect it. That sets DATABASE_URL and DATABASE_URL_UNPOOLED automatically.
3. Settings → Environment Variables: add AUTH_SECRET (openssl rand -base64 32), NEXT_PUBLIC_SITE_URL (e.g. https://your-app.vercel.app) and ADMIN_KEY (any long secret).
4. Deployments → Redeploy. Every build runs scripts/db-sync.mjs, which creates/updates the tables (and fails the build with a clear message if no database is connected).
5. Open https://your-app.vercel.app/api/health — it says exactly what's missing if anything is wrong.

Render

1. Push to GitHub, then on render.com: New → Blueprint and pick the repo. render.yaml creates the web service + Postgres and generates AUTH_SECRET.
2. Set NEXT_PUBLIC_SITE_URL to your https://….onrender.com URL when prompted.
3. The blueprint also creates streetquest-realtime (Street Arena). Set its APP_URL to the web app's URL and RT_ORIGINS to the same origin, and set the web app's NEXT_PUBLIC_RT_URL to wss://<realtime-service>.onrender.com, then redeploy the web app (NEXT_PUBLIC_ values are baked in at build time). It shares the web app's AUTH_SECRET.
4. Note: free web services sleep after 15 min idle (slow first load) — use a paid instance for the realtime server, or players wait for it to wake — and free Postgres expires after 30 days.

On Vercel, the app can't hold WebSockets: run npm run rt anywhere that can (Render, Fly.io, Railway, a VPS) with AUTH_SECRET (same as the app), APP_URL and RT_ORIGINS, and set NEXT_PUBLIC_RT_URL on Vercel.

After the first deploy, play once, then open /admin?key=<ADMIN_KEY> to make yourself admin. Don't run the demo seed in production.

Snappfood from abroad: the relay (ArvanCloud)

Snappfood refuses servers outside Iran: on Vercel the map shows no restaurants and no menus, and /api/health?ext=1 says snappfood (403). Browsers can't read it either (it only allows its own sites). relay/relay.mjs is a small relay with no dependencies (any Node 18+) that runs on a server in Iran; the app reads Snappfood through it.

1. In the ArvanCloud panel, create a Cloud Server in an Iranian region with Ubuntu 24.04 (the smallest size is plenty) and make sure port 80 is open in its security group.
2. From the repo: scp relay/relay.mjs relay/install.sh <user>@<server-ip>: then ssh -t <user>@<server-ip> sudo bash install.sh. It installs Node from Ubuntu's mirror, runs the relay as a service on port 80 with a random key (kept in /etc/streetquest-relay.env), checks that Snappfood answers the server (200 = good) and prints the SNAPPFOOD_URL to use. Run it again to update the relay; the key stays.
3. HTTPS (recommended — the key is part of the URL): put a (sub)domain on ArvanCloud CDN with an A record to the server, going through the CDN with HTTPS on. The relay marks every answer no-store, so the CDN doesn't cache them.
4. On Vercel: vercel env add SNAPPFOOD_URL production = https://<domain>/<key>/snappfood (or the http://<ip>/<key>/snappfood the script printed), then redeploy. /api/health?ext=1 should say snappfood 200.

The relay forwards only the endpoints the game calls (anything else, or a wrong key, is a 404), passes the app's User-Agent and nothing about the player, and logs no positions. Torob and Divar answer Vercel directly today; if one starts refusing, point TOROB_URL / DIVAR_URL at the same relay with /torob or /divar at the end.

Production checklist

• Installable app & offline: /sw.js (service worker) caches the app, map tiles you've seen and your last game state, so the game opens offline. It also keeps the heavy files on the phone so a launch never downloads them again: fonts, the arena's 3D models and the 3D decoder (fetched in the background on install and every launch), and the 3D city's street maps you've driven through (vector tiles a week, city-pack detail a day). The app asks the browser for persistent storage so Android doesn't clear it when space runs low. Every deploy gets a new version id, and players see "New version ready → Update". Offline, every message is in the player's language: the worker's "offline" answer is shown as the app's own translation (x-offline), and picking another language re-fetches the offline page and the game shell it keeps. A long-press on the installed icon offers shortcuts: Play, Story missions (/play?panel=play) and Drive the 3D city (/play?drive=1, straight into the car once there's a position to start from).

• Push notifications: set VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY and VAPID_SUBJECT (npx web-push generate-vapid-keys). Every in-game notification is also pushed to the phone when the player isn't in the app; Admin → Campaigns → live push can send to everyone. iPhone needs the app added to the Home Screen (iOS 16.4+).

• Real ads (Google AdSense): sign up at adsense.google.com with your production domain, then apply for H5 Games Ads (AdSense → Ads → By site → H5 games). Set ADSENSE_CLIENT="ca-pub-…" and redeploy: /ads.txt is served automatically and the store's Free gems button plays a Google rewarded video first. Where Google has no ad (Iran and other sanctioned countries, ad blockers, frequency caps) players get your sponsor spot instead, so the button always works. ADSENSE_TEST=on shows Google's test ads while you try it. Admin → Game settings → Store & ads → Google video ads on switches it live; views are counted as "Google video ads" in Admin → Revenue.

• City packs (3D street detail and real places): npm run city:pack:prod -- iran (the whole country — every town and the roads between them, ~118k places in ~35k cells, ~4 min to read; or single cities: tehran karaj mashhad isfahan shiraz tabriz) reads production settings from .env.prod (a copy of .env with the production DATABASE_URL and DATABASE_URL_UNPOOLED; git-ignored — keep .env on your local database; its values win over , and the first line printed is the database it writes to) and Geofabrik's daily Iran extract and stores every mapped tree, traffic light, crossing, bus stop, bench, fountain and sports pitch per cell (), and every named restaurant, café, shop and park () — without it, places only arrive with an Overpass tile, which is often busy. builds the three places with the most active players (any country — the right extract is found automatically), shows what's built and where players are. Re-run weekly to pick up map edits.

Before going big

• Real places / 3D city: public Overpass servers are slow and rate-limited. Tiles are cached a month per cell, but at scale run your own Overpass and point OVERPASS_URL at it. City packs cover places in the packed cities meanwhile.
• Store menus and ads: Snappfood, Torob and Divar are read through their unofficial web APIs, which can change or block servers outside Iran without notice — store cards then simply show no menu, and the map no vendors or ads. Check /api/local?near=1&lat=35.7&lng=51.4 and /api/local?divar=1&lat=35.7&lng=51.4 from the production server after deploying. Re-run the city packs (npm run city:pack:prod -- iran) so production places carry their contacts.
• Map tiles: the default public OSM tile server is for light use only. Set NEXT_PUBLIC_TILE_URL (+ NEXT_PUBLIC_TILE_ATTRIBUTION) to a provider like MapTiler or Stadia. It replaces the default street tiles (fantasy, street, night ops and the filtered looks); the satellite, terrain and CARTO styles use the free public servers of Esri, OpenTopoMap, CARTO and OSM France — fine for light use, check their terms before heavy traffic.
• Chat/notifications poll every few seconds. For instant delivery at scale, plug in a hosted realtime service (Ably, Pusher, Supabase Realtime) behind notify() and the chat route.
• Street Arena runs in one realtime process (in memory). One instance handles a few thousand players; past that, shard by region (each instance owns an area; route players with the ticket). Anti-cheat is server-refereed but movement is client-reported (speed-capped, no walking through buildings in matches), so it's casual-grade, not competitive: aim itself can't be verified. In the open city the server doesn't know the buildings, so shots there aren't checked for walls.
• Switch prisma db push in the build to prisma migrate deploy once you have real data.