HUNKER BUNKER
Crash in. Scavenge O2. Upgrade your suit. Survive the depths.
Hunker Bunker is a retro-futuristic tactical survival game where you navigate ice-locked subterranean corridors, balance failing life support, uncover lost telemetry, and decide what leaves the planet with you.
🎮 Play Live Browser Build • 💬 Join Discord Server • 📚 Documentation Map
Status (2026-10-26): v2.4.18-beta (Sprint 53) is in review as a PR from dev/sprint-53 to mothership. Packaged PvE, PvP, Steam Deck, performance, cloud and operations acceptance is still open.
Sprint 53 highlights:
- The Definitive First Expedition: fresh profiles enter Sector 0 directly, learn the survival loop through five authored phases, and cross the blast threshold continuously into Ring 1. Returning players retain an explicit onboarding skip.
- Field Recalibration: safe-camp workbenches now offer one curated build-defining recalibration per camp, including Cryo Overclock, Biometric Siphon, and Kinetic Spalling, with deterministic rerolls and squad replication.
- Elemental and enemy grammar: Sub-Zero Necrosis fuses cryo and bio-corrosion; Mycelium Stalkers flank, telegraph, pounce, react to light and gunfire, and retreat to darkness. Scuttler and Spore Mortar encounters received complementary combat passes.
- Camps and cinematics: interaction gating, dialogue telemetry, physical walk-to interactions, fallback staging, doors, and all 32 cinematic cards now form a clearer authored event chain.
- Multiplayer parity: moving and breakable props, items, enemy state, deaths, redeploys, and recalibration effects use host-authoritative replication paths.
- Feel and performance: hit-stop, footsteps, combat audio, arcade/achievement integration, bounded light pools, scene batching, mixer culling, deferred boot assets, and mobile Lighthouse 93/93 clearance.
Read the release notes, PR description, and master verification plan. Acceptance remains open until the evidence gates in that plan pass.
📸 Sprint 53 Candidate Showcase
🎮 Current Build and Cinematic Captures
| Cryo Expedition Route | Live Combat and Current HUD | Camp Narrative Cinematic |
|---|
| | |
The cryo-route and combat frames were recaptured from the local validation working tree after the floor, prop-repetition, and wall-fixture finish fixes. Both use the deterministic trailer harness. They document the working visual state; packaged hardware acceptance is tracked separately in the Sprint 53 master plan.
🏧 Terminals You Walk Up To
Every terminal is a physical machine in the bunker: the Fabrication Auto-Mart, the Meridian service terminal and the Black-Ice 21 cabinet, with the live game blurred around them. Their keypads, bolts and coin returns work (try 0451, or unscrew the four corner bolts). Captured in a real run on Steam Deck and PC:
| Fabrication Auto-Mart | Meridian Service Terminal | Black-Ice 21 |
|---|
| | |
Deck beside PC for every machine: docs/screenshots/.
🌌 Deep Crust Lore & Interstitials
| Warmth Beneath the Ice | Gigawatt Goliath (Apex Threat) | The Cave Was Breathing |
|---|
| | |
🖼️ Steam Store & Library Art
| Library Capsule | Vertical Capsule | Small Capsule & Logo |
|---|
| | |
All store and library art lives in steam/store/ (English slots; replacements use the same file names).
⚡ Core Features
- Authored First Expedition: New profiles deploy into Sector 0's Impact Zone instead of a random maze. Five guided phases teach movement, O₂, salvage, combat, and extraction before a continuous transition into Ring 1; returning operators can skip onboarding from pause.
- Safe-Camp Field Recalibration: Once per camp, reshape the current build with a strong benefit and a meaningful cost. Deterministic card offers, scrap rerolls, and host-authoritative squad broadcasts keep the choice legible and synchronized.
- Reactive Combat Ecosystem: Freeze plus bio-corrosion triggers Sub-Zero Necrosis novas, while Stalkers use cover, light sensitivity, flanking, readable pre-pounce cues, and retreat behavior instead of relying on raw health alone.
- Physical Camp Storytelling: Camp progression connects item pickup, location, player and NPC movement, staged interaction, dialogue choice, cinematic first/last frames, and persistent consequences through explicit event gates and telemetry.
- Persistent Campaigns, Seeded Expeditions: A campaign keeps one world — its rings, gates, camps and hives — while every deployment rolls its own condition (gale, spore bloom, resin surge, geothermal arc, stillness) with real gameplay effects, fresh corridor rubble and a briefing. New campaigns get their own route shape, gate challenges and an optional objective package for each ship goal, with a reward and a lasting consequence.
- A World That Remembers: Bridge the canyon, fortify a camp's perimeter, bond with or harvest a hive — each choice changes the map for the rest of the campaign. Overnight, hive creep spreads and camps strain; radar scans lift the fog on the tactical map as they sweep.
- Deep Localization (7 Languages): Complete localization across English (
en), German (de), Latin American Spanish (es-419), Japanese (ja), Brazilian Portuguese (pt-BR), Russian (ru), and Simplified Chinese (zh-CN) — 0 unannotated markup, 0 unlocalized runtime strings, 1,898 keys per locale at exact parity, live in-session switching, and a coverage ratchet (npm run i18n:audit) that fails CI if any of those regress.
- Alternate Radio Voice Banks & Personas: Equip the grizzled Soviet Sub-Commander (
4148) or tactical AI AURA (4149) with 104 callout slots (208 authentic takes), intro cutscene HUD persona cards, and customized opening crash dialogue.
- : Survivor encounters, faction standing with the Meridian/Tallow/Vesper camps, and hive diplomacy determine which of ten fully-rendered 3D motion cinematic endings with dedicated audio beds you achieve.
🛡️ Specialist Classes
| SCOUT | TANK | ENGINEER |
|---|
| | |
| Active Ability: Sprint BurstFast recon & high-risk salvage runs. | Active Ability: Heavy BraceAbsorbs punishment & clears corridors. | Active Ability: Systems RerouteHacks terminals & maximizes extraction. |
🕹️ Controls
Full map of every menu, sub-menu and tab, the input model and the UI
improvement plan: docs/design/ui-surfaces-menu-map-and-controller-navigation.md.
Gameplay Controls
| Action | Keyboard / Mouse | Steam Deck / Gamepad (official layout) |
|---|
| Move | WASD / Arrow keys | Left stick |
| Aim & Fire | Mouse + left click | Right stick or trackpad + RT |
| Interact | E (or Enter) | A |
| Dodge | — | B |
| Reload | R | X / D-pad ◀ |
| Smash / Class Ability | F | Y / D-pad ▶ |
| Scan | Q | LB / D-pad ▼ |
| Tactical Map | M or Tab | RB / D-pad ▲ / View |
| Sprint | Shift | Left stick click |
| Melee | V | — |
| Tactical Ping | T (with a squadmate in the room, T also opens trade) | — |
| Pause / Settings | Esc | ☰ Menu |
| Chat | HUD CHAT button, or Pause → Settings → Session → Room Chat | Pause → Settings → Session → Room Chat |
| Dev Telemetry | ~ | — |
🎮 Controller Navigation & Menu Accessibility
Every menu is built for the Steam Deck stage (1280×800) and driven by one
focus system shared by the pad, the keyboard and the mouse. Every surface is
registered in MENU_FOCUS_ROOT_IDS (src/inputActions.js) and covered by the
menu-reachability, controller-focus and menu-tab-switching browser suites.
| Action | Steam Deck / Gamepad | Keyboard | Function |
|---|
| Navigate | D-pad / left stick | W A S D or arrows | Spatial focus across buttons, cards and slots; wraps at the edges. |
| Activate | A or RT | Enter / Space | Equips gear, buys upgrades, selects an operative; A on a dropdown opens its full list. |
| Back / Close | B | Esc | Closes the topmost surface and returns focus to the button that opened it. |
| Switch Tabs | LB / RB (also X / Y) | Q / E | Settings, Archive, Foundry hub / Vault, Dossier, ship terminal; class cards on the operator menu and in the Armory. |
| Adjust Values | D-pad ◀ ▶ (focused) | A / D or ◀ ▶ | Sliders, volume, UI scale, dropdowns. |
| Scroll Text | D-pad ▲ ▼ | W / S or ▲ ▼ | Scrolls lore, codex detail and commentary text that has nothing to focus. |
| Enter Text | A (Steam keyboard; in-game keyboard fallback) | type | Callsign and chat. |
| Pointer | Right trackpad / stick cursor + A | Mouse | Optional; never the only way to reach a control. |
🚀 Quickstart & Setup
Prerequisites
- Node.js: v22 or newer (matches CI)
- npm: the version bundled with Node.js 22 or newer
# Clone the repository
git clone https://github.com/grounded-play/hunker-bunker.git
cd hunker-bunker
# Install dependencies & launch dev server
npm install
npm run dev
Open http://localhost:5173 in your browser.
For the desktop shell, npm run electron:dev runs Electron against the dev server with DevTools detached and the F12 / Ctrl+Shift+I and F5 / Ctrl+R shortcuts. Set HB_DEVTOOLS_OPEN=0 to keep DevTools closed, or list Chrome Web Store extension IDs in HB_DEVTOOLS_EXTENSIONS (comma-separated) to install them.
🧪 Verification & Build
npm test # Run the complete unit and integration test suite
npm run coverage # Run tests and generate the coverage report
npm run lint # Check formatting & code safety
npm run build # Compile production WebGL bundle
npx playwright test tests/e2e/<spec>.spec.js # Browser specs (each cold-boots the game; allow ~30s–3m per test)
Other agents or editors changing src/ make a watched Vite server reload the page mid-test; run browser specs against a server without HMR when the tree is busy.
The badges above report the latest merged mothership workflow results. Pull
request checks may be newer; use the PR checks view when validating an
unmerged branch.
🛠️ Tech Architecture
- WebGL 3D Engine: Powered by Three.js (r186) with procedural dungeon generation, dynamic fog of war, and WebAudio spatial soundscapes.
- 3D & Surface Pipeline: Zero-detail-loss 25,000 triangle GLTF assets optimized with
gltfpack meshopt vertex compression and Basis Universal KTX2 textures (KHR_texture_basisu). Dual-array BC7 KTX2 floor surfaces with multi-layer height-blend shaders, procedural noise jitter, and deterministic BFS traffic wear mapping.
- Desktop & Steam Shell: Built with Electron featuring native Steamworks integration for Steam Cloud saves, Steam Input, real Steam Lobbies (Friends invite, Join Game, Rich Presence), and 24 Steam Achievements.
- Trusted Relay Server: Node.js & Express server running in Docker Compose behind Caddy (
steam.tuesdaycinema.club), enforcing verified score validation for 5 Steam Leaderboards and Steam-session-authenticated multiplayer.
🤝 Join the Team
Hunker Bunker is built in the open. Whether you write code or just want first
crack at every new drop, there's a seat for you.
Playtesters & community — the fastest way in. Jump into Discord, play the
live browser build, break things, and tell us what you found. Community
feedback has directly shaped classes, endings, and the economy in this repo.
Contributors — this is a real MIT-licensed open-source project, not a
mirror. Bug fixes, balance tuning, new content, tooling — all welcome.
- Read
CONTRIBUTING.md for the fork/branch/PR workflow.
- Check open issues for
something to grab, or file a bug report /
feature request.
npm test && npm run lint before you open a PR — CI runs the same checks.
📄 License & Contact
Distributed under the MIT License. Built with ❤️ by Tuesday Cinema Club.
