Skip to content

MARKDOWN SOURCE

Raw
# Zombie Sniper

A first-person 3D sniper game built with **Three.js + Vite**. You are holed up in a building.
The zombies cannot attack you. Your job is to snipe the dead in the windows across the street,
on the road, and in the blocks beyond, then spend the loot on better guns at your workbench.

Everything is procedural (boxes, cylinders, and generated sounds), so there are no asset files
to download and nothing to model in Blender. Graphics are intentionally simple.

## Run it

With [mise](https://mise.jdx.dev) installed (it also provides bun):

```bash
mise run dev      # installs dependencies if needed, then starts the dev server
mise run build    # production build into dist/
```

Or with bun directly:

```bash
bun install
bun run dev        # open the URL it prints (http://localhost:5173)
bun run build      # production build into dist/
```

Pick a map on the main menu (**New run** or **Continue**). Your mouse is captured. Press **Esc** to pause.

## Controls

| Input | Action |
| --- | --- |
| WASD | Move (walls and furniture block you) |
| Mouse | Look |
| Left click | Fire (hold for the carbine) |
| Right click | Toggle scope |
| Mouse wheel (scoped) | Change magnification |
| Shift (hold) | Sprint (not while scoped). While scoped, hold to steady the shot: limited breath, recharges when released. Longer with the Tripod |
| R | Reload |
| 1-6 | Switch weapon |
| E (near the workbench, top floor west room) | Open the workbench |
| Esc | Pause / close the workbench |

## What's in the game

**The world**
- A city grid of procedural buildings (1-5 storeys) with real window openings, so bullets fly
  through windows and walls and stop at solid masonry.
- Your building is three floors tall, but you only ever use the top floor. You start in the sniper
  nest about 7 m up. The lower floors are out of reach. The base room with the workbench is on the
  top floor, through the door in the west room.
- About 45 abandoned cars act as cover in the streets.
- Buildings differ. Each one rolls its own fascia, window bars, AC units, window boxes, entrances, downpipes,
  roof kit, antenna and water tower from its position, so no two look the same. Wall, fascia and awning colours vary too.
- Windows are either open, so you can see furniture inside (beds, sofas, bookcases, fridges, TVs, desks, lamps), or
  **boarded**. Boarded windows have a solid sheet behind the planks, so bullets and zombies stop there.
- About 30% of buildings are **half destroyed**. The far side of a cut loses everything above a storey, leaving
  exposed floors and a broken edge, with rubble on the ground.
- Every block has the same street kit: sidewalk joints, a tree in a grate, a streetlight, a bin, a utility pole
  with power lines to the next block, and a traffic signal at each intersection. Manholes, road patches, hydrants,
  benches and signs still vary. The top-floor base has a planked floor, beams, a workbench with
  drawers, tools and a pegboard, a rifle cabinet, sandbags on the sniper table and a wall map.

- A dusk sky with a warm horizon that the fog blends into. Low sun with shadows.

**The Wall** (a second map, picked on the main menu)
- A concrete wall twelve metres high runs through the map, with a walkway along its top. Forest lies on one side
  (where the dead are) and a compound with shipping containers on the other.
- Your shack sits on the walkway: a stove, a workbench, the pill table and a doorway onto the walkway. The only
  opening to the forest is a slit in the north wall, about 0.2 m wide, so you shoot out through it. Bullets go
  through the slit and stop at the solid timber everywhere else.
- Outside the shack you lose **warmth**. The stove refills it. If it runs out, you die. The run ends where you stand
  and its prestige points are banked, but prestige only rises from the pill after a win.
- About a thousand zombies live in the forest. Trees hide some of them. Trunks are solid, so they stop rounds
  and zombies walk round them. The crowns only hide. Zombies near you have full bodies. The rest are drawn as
  silhouettes, which keeps the frame rate steady with that many on screen.

**Sound** (all procedural, through a shared reverb)
- Each weapon has its own report. Bolt guns cycle the bolt, reloads click the magazine out and
  back in, and spent brass rattles on the street.
- Wind gusts through the streets. Every so often a car alarm goes off somewhere far away.
- Zombies moan at you from across the streets, panned left or right to where they stand.
  Gunshots make nearby zombies turn toward the sound.

**Feedback**
- Shell casings tumble out of the ejection port and bounce on the ground.
- Rounds that hit walls throw dust and chips. Hits on bodies throw blood, and each kill leaves
  a blood pool that stays on the street.
- Hit zombies stagger, with a head hit snapping them back harder.
- Dead zombies fall away from the shot, then sink into the street after a few seconds.
- Kill messages carry the zombie's name, range and a short line of flavour.

**Zombies (they never attack)**
- **Walker**: slow, common. Pays the least, drops scrap and sometimes powder.
- **Runner**: fast, weak. Drops powder.
- **Brute**: large, tough (220 HP). Drops steel and sometimes optics.
- Every body has its own skin and clothing shade, so the crowd does not look cloned.
- About 35% stand idle in other buildings' rooms. The rest wander the streets.
- Gunshots alert zombies within about 220 m. Suppressed weapons do not alert anyone.
- Zombies respawn out of your line of sight, so the population stays around 70.

**Ballistics**
- Bullets are real projectiles with travel time and gravity drop. Rifles are zeroed at 150 m.
- Hit zones: head (2.5x damage, 2x money), torso (1x), legs (0.5x).
- Money scales with range: `reward * (1 + distance / 250)`.
- Sway and recoil are real. Hold breath, and use the scope's wider reticle to compensate.

**Weapons** (6 in total)

| Weapon | Ammo | Notes |
| --- | --- | --- |
| Hunting Rifle | .308 | Starter bolt-action |
| DMR-7 Marksman | .308 | Semi-auto, 4-8x |
| Ghost .22 Suppressed | .22 | Silent. Does not alert zombies |
| AR Carbine 5.56 | 5.56 | Fully automatic, low damage |
| LRM-50 Magnum | .50 | Heavy hitter at range |
| Prototype Railgun | Power cell | Near-flat trajectory, very high damage |

**Progression**
- Craft new weapons with money and salvage.
- Five mods per weapon, three levels each: Barrel (damage), Trigger (fire rate), Stock
  (sway and spread), Scope (more magnification), Magazine (capacity).
- Base upgrades: **Radar Dish** (zombie blips on your HUD), **Reloading Bench** (-20% reload),
  **Tripod Mount** (longer breath hold, less sway).
- Ammo press: craft .22, 5.56, .308, .50 and power cells from salvage.
- Trader: sell scrap, powder, steel and optics for cash.
- Eight contracts (kill counts, headshots, long-range kills, shot counts) with cash and
  salvage rewards.
- **Main menu**: each map has its own run, which you can start or continue. The **Prestige shop** is only here.
- **Prestige**: points come from 5 headshots in a row (`PRESTIGE.streak`) and a 3% chance on each kill to be lucky.
  They count toward the current run and are banked when you take the pill on the small table by the sniper nest.
  The pill works at any time, and ends the run back at the main menu. On the wall, freezing to death also ends the run
  and banks its points, but does not raise the prestige level. Spend banked points in the **Prestige shop**
  on perks that every later run starts with: weapons, the Radar Dish and other base upgrades, starting cash, and
  starting ammo (`PERKS`). Taking the pill after you win also raises the prestige level, and each level cuts
  zombie HP by 5%, up to 40%. The **Unstuck** button in the Esc menu teleports you back to the sniper nest.
- **Win condition**: kill 50 zombies on the street, or 100 on the wall (`winKills` in `MAPS`, `src/config.js`). The HUD shows your kill count, and a win screen appears once. You can keep playing afterward.
- **Settings** (main menu or pause screen): mouse and scope sensitivity, invert vertical look, field of view,
  brightness, resolution scale, shadows, frame rate cap, FPS counter, volume. Saved in `localStorage`
  separately from progress, and applied as soon as you change them.
- Progress saves to `localStorage` automatically. Prestige is saved separately from runs.

## Project layout

```
index.html            HUD, main menu, prestige shop, pause screen, workbench panel, death screen
src/style.css         Styling
src/main.js           Entry point: renderer, lights and shadows, input, game loop, map loading, death
src/config.js         All tuning data: maps, warmth, weapons, mods, zombies, ammo, contracts, pause tips
src/city.js           The street: buildings, streets, cars, plus the shared collision grid and merged mesh
src/wall.js           The wall: walkway, shack, forest and compound
src/warmth.js         Body warmth for the wall: drain outside, refill by the stove, the cold warning
src/detail.js         Facade, street, roof, interior and car decoration
src/atmosphere.js     Sky dome and fog colour
src/particles.js      Casings, debris, dust puffs and blood spray
src/zombies.js        Zombie spawning, wandering/alert AI, hit spheres, falls and blood pools, full bodies near you and silhouettes further out
src/player.js         First-person movement with wall collision
src/combat.js         Weapon stats, firing, ballistics, scope, sway, rewards
src/economy.js        Money, resources, ownership, upgrades, contracts, save/load
src/menu.js           Main menu: map list, prestige bar and prestige shop
src/ui.js             HUD, radar, scope, notifications, warmth gauge, workbench menu
src/settings.js       Saved options (sensitivity, FOV, graphics, audio) and the list the menu shows
src/settingsMenu.js   Settings screen: builds the controls and opens/closes it
src/audio.js          Procedural gunshots, reverb, groans, wind and ambience (Web Audio, no files)
```

Shadows are the most expensive visual feature. On a weak GPU, open **Settings** (from the main menu or
pause screen) and turn off Shadows or lower the Resolution scale.

## Tuning and extending

Most balance lives in `src/config.js`: weapon damage, cooldown, velocity and zoom; zombie
HP, speed and drop tables; ammo recipes; mod costs; contracts; and the warmth rates. Add a weapon by adding an
entry to `WEAPONS` and its id to `WEAPON_ORDER`. Add a contract by adding a `metric` key that
exists in `state.stats`. Each map in `MAPS` sets its zombie population, how close zombies get a full body,
its win kill count, and whether it has warmth. A new map also needs a builder in `src/`, wired up in `loadWorld`
in `src/main.js`.

Ideas for the next pass: day/night cycle with zombie waves, a real sniper nest with bipod
placement, bullet wind drift, and a zombie that can hear footsteps as well as shots.

## Debugging

`window.zombieSniper` exposes the running game (player, zombies, combat, state, warmth, UI, and the
current `world`) for poking at from the browser console.

Zombie Sniper

A first-person 3D sniper game built with Three.js + Vite. You are holed up in a building. The zombies cannot attack you. Your job is to snipe the dead in the windows across the street, on the road, and in the blocks beyond, then spend the loot on better guns at your workbench.

Everything is procedural (boxes, cylinders, and generated sounds), so there are no asset files to download and nothing to model in Blender. Graphics are intentionally simple.

Run it

With mise installed (it also provides bun):

mise run dev      # installs dependencies if needed, then starts the dev server
mise run build    # production build into dist/

Or with bun directly:

bun install
bun run dev        # open the URL it prints (http://localhost:5173)
bun run build      # production build into dist/

Pick a map on the main menu (New run or Continue). Your mouse is captured. Press Esc to pause.

Controls

InputAction
WASDMove (walls and furniture block you)
MouseLook
Left clickFire (hold for the carbine)
Right clickToggle scope
Mouse wheel (scoped)Change magnification
Shift (hold)Sprint (not while scoped). While scoped, hold to steady the shot: limited breath, recharges when released. Longer with the Tripod
RReload
1-6Switch weapon
E (near the workbench, top floor west room)Open the workbench
EscPause / close the workbench

What's in the game

The world

  • A city grid of procedural buildings (1-5 storeys) with real window openings, so bullets fly through windows and walls and stop at solid masonry.

  • Your building is three floors tall, but you only ever use the top floor. You start in the sniper nest about 7 m up. The lower floors are out of reach. The base room with the workbench is on the top floor, through the door in the west room.

  • About 45 abandoned cars act as cover in the streets.

  • Buildings differ. Each one rolls its own fascia, window bars, AC units, window boxes, entrances, downpipes, roof kit, antenna and water tower from its position, so no two look the same. Wall, fascia and awning colours vary too.

  • Windows are either open, so you can see furniture inside (beds, sofas, bookcases, fridges, TVs, desks, lamps), or boarded. Boarded windows have a solid sheet behind the planks, so bullets and zombies stop there.

  • About 30% of buildings are half destroyed. The far side of a cut loses everything above a storey, leaving exposed floors and a broken edge, with rubble on the ground.

  • Every block has the same street kit: sidewalk joints, a tree in a grate, a streetlight, a bin, a utility pole with power lines to the next block, and a traffic signal at each intersection. Manholes, road patches, hydrants, benches and signs still vary. The top-floor base has a planked floor, beams, a workbench with drawers, tools and a pegboard, a rifle cabinet, sandbags on the sniper table and a wall map.

  • A dusk sky with a warm horizon that the fog blends into. Low sun with shadows.

The Wall (a second map, picked on the main menu)

  • A concrete wall twelve metres high runs through the map, with a walkway along its top. Forest lies on one side (where the dead are) and a compound with shipping containers on the other.
  • Your shack sits on the walkway: a stove, a workbench, the pill table and a doorway onto the walkway. The only opening to the forest is a slit in the north wall, about 0.2 m wide, so you shoot out through it. Bullets go through the slit and stop at the solid timber everywhere else.
  • Outside the shack you lose warmth. The stove refills it. If it runs out, you die. The run ends where you stand and its prestige points are banked, but prestige only rises from the pill after a win.
  • About a thousand zombies live in the forest. Trees hide some of them. Trunks are solid, so they stop rounds and zombies walk round them. The crowns only hide. Zombies near you have full bodies. The rest are drawn as silhouettes, which keeps the frame rate steady with that many on screen.

Sound (all procedural, through a shared reverb)

  • Each weapon has its own report. Bolt guns cycle the bolt, reloads click the magazine out and back in, and spent brass rattles on the street.
  • Wind gusts through the streets. Every so often a car alarm goes off somewhere far away.
  • Zombies moan at you from across the streets, panned left or right to where they stand. Gunshots make nearby zombies turn toward the sound.

Feedback

  • Shell casings tumble out of the ejection port and bounce on the ground.
  • Rounds that hit walls throw dust and chips. Hits on bodies throw blood, and each kill leaves a blood pool that stays on the street.
  • Hit zombies stagger, with a head hit snapping them back harder.
  • Dead zombies fall away from the shot, then sink into the street after a few seconds.
  • Kill messages carry the zombie's name, range and a short line of flavour.

Zombies (they never attack)

  • Walker: slow, common. Pays the least, drops scrap and sometimes powder.
  • Runner: fast, weak. Drops powder.
  • Brute: large, tough (220 HP). Drops steel and sometimes optics.
  • Every body has its own skin and clothing shade, so the crowd does not look cloned.
  • About 35% stand idle in other buildings' rooms. The rest wander the streets.
  • Gunshots alert zombies within about 220 m. Suppressed weapons do not alert anyone.
  • Zombies respawn out of your line of sight, so the population stays around 70.

Ballistics

  • Bullets are real projectiles with travel time and gravity drop. Rifles are zeroed at 150 m.
  • Hit zones: head (2.5x damage, 2x money), torso (1x), legs (0.5x).
  • Money scales with range: reward * (1 + distance / 250).
  • Sway and recoil are real. Hold breath, and use the scope's wider reticle to compensate.

Weapons (6 in total)

WeaponAmmoNotes
Hunting Rifle.308Starter bolt-action
DMR-7 Marksman.308Semi-auto, 4-8x
Ghost .22 Suppressed.22Silent. Does not alert zombies
AR Carbine 5.565.56Fully automatic, low damage
LRM-50 Magnum.50Heavy hitter at range
Prototype RailgunPower cellNear-flat trajectory, very high damage

Progression

  • Craft new weapons with money and salvage.
  • Five mods per weapon, three levels each: Barrel (damage), Trigger (fire rate), Stock (sway and spread), Scope (more magnification), Magazine (capacity).
  • Base upgrades: Radar Dish (zombie blips on your HUD), Reloading Bench (-20% reload), Tripod Mount (longer breath hold, less sway).
  • Ammo press: craft .22, 5.56, .308, .50 and power cells from salvage.
  • Trader: sell scrap, powder, steel and optics for cash.
  • Eight contracts (kill counts, headshots, long-range kills, shot counts) with cash and salvage rewards.
  • Main menu: each map has its own run, which you can start or continue. The Prestige shop is only here.
  • Prestige: points come from 5 headshots in a row (PRESTIGE.streak) and a 3% chance on each kill to be lucky. They count toward the current run and are banked when you take the pill on the small table by the sniper nest. The pill works at any time, and ends the run back at the main menu. On the wall, freezing to death also ends the run and banks its points, but does not raise the prestige level. Spend banked points in the Prestige shop on perks that every later run starts with: weapons, the Radar Dish and other base upgrades, starting cash, and starting ammo (PERKS). Taking the pill after you win also raises the prestige level, and each level cuts zombie HP by 5%, up to 40%. The Unstuck button in the Esc menu teleports you back to the sniper nest.
  • Win condition: kill 50 zombies on the street, or 100 on the wall (winKills in MAPS, src/config.js). The HUD shows your kill count, and a win screen appears once. You can keep playing afterward.
  • Settings (main menu or pause screen): mouse and scope sensitivity, invert vertical look, field of view, brightness, resolution scale, shadows, frame rate cap, FPS counter, volume. Saved in localStorage separately from progress, and applied as soon as you change them.
  • Progress saves to localStorage automatically. Prestige is saved separately from runs.

Project layout

index.html            HUD, main menu, prestige shop, pause screen, workbench panel, death screen
src/style.css         Styling
src/main.js           Entry point: renderer, lights and shadows, input, game loop, map loading, death
src/config.js         All tuning data: maps, warmth, weapons, mods, zombies, ammo, contracts, pause tips
src/city.js           The street: buildings, streets, cars, plus the shared collision grid and merged mesh
src/wall.js           The wall: walkway, shack, forest and compound
src/warmth.js         Body warmth for the wall: drain outside, refill by the stove, the cold warning
src/detail.js         Facade, street, roof, interior and car decoration
src/atmosphere.js     Sky dome and fog colour
src/particles.js      Casings, debris, dust puffs and blood spray
src/zombies.js        Zombie spawning, wandering/alert AI, hit spheres, falls and blood pools, full bodies near you and silhouettes further out
src/player.js         First-person movement with wall collision
src/combat.js         Weapon stats, firing, ballistics, scope, sway, rewards
src/economy.js        Money, resources, ownership, upgrades, contracts, save/load
src/menu.js           Main menu: map list, prestige bar and prestige shop
src/ui.js             HUD, radar, scope, notifications, warmth gauge, workbench menu
src/settings.js       Saved options (sensitivity, FOV, graphics, audio) and the list the menu shows
src/settingsMenu.js   Settings screen: builds the controls and opens/closes it
src/audio.js          Procedural gunshots, reverb, groans, wind and ambience (Web Audio, no files)

Shadows are the most expensive visual feature. On a weak GPU, open Settings (from the main menu or pause screen) and turn off Shadows or lower the Resolution scale.

Tuning and extending

Most balance lives in src/config.js: weapon damage, cooldown, velocity and zoom; zombie HP, speed and drop tables; ammo recipes; mod costs; contracts; and the warmth rates. Add a weapon by adding an entry to WEAPONS and its id to WEAPON_ORDER. Add a contract by adding a metric key that exists in state.stats. Each map in MAPS sets its zombie population, how close zombies get a full body, its win kill count, and whether it has warmth. A new map also needs a builder in src/, wired up in loadWorld in src/main.js.

Ideas for the next pass: day/night cycle with zombie waves, a real sniper nest with bipod placement, bullet wind drift, and a zombie that can hear footsteps as well as shots.

Debugging

window.zombieSniper exposes the running game (player, zombies, combat, state, warmth, UI, and the current world) for poking at from the browser console.