HOMESTRIKE :: DEVELOPER

internal capabilities & debugging surface · v0.50.0

▣ Quick Switches

?debug=true

Shows the green-on-black tech-nerd HUD pinned top-right of the page. Renders every IP provider attempt with status & latency, GPS state, boot stage, engine FPS/wave/state, OSM prefetch, MP init, screen × DPR, network class, console errors, and the last 60 internal events.

OPEN WITH DEBUG ›

?eager=1

Pre-boots the Babylon scene during page idle (off by default since R17B3 to avoid OOM-on-PLAY on commodity GPUs). Use only on machines you've tested.

OPEN EAGER ›

?join=<homecode>

Auto-flips overlay to JOIN tab and prefills the homecode field. Used by share links / QR codes.

?nogeoloc=1 (planned)

Will simulate denied geolocation deterministically without touching browser permissions — handy for testing IP fallback paths.

▣ IP Geolocation Fallback Chain

All requests fire from the user's browser in parallel (race-style). First success wins. Per-IP rate limits are NOT shared across users because the rig never proxies these calls.

Provider	Endpoint	Free quota
ipapi.co	`https://ipapi.co/json/`	1k req/day per IP
freeipapi.com	`https://freeipapi.com/api/json/`	60 req/min per IP
ipwho.is	`https://ipwho.is/`	10k req/month per IP
get.geojs.io	`https://get.geojs.io/v1/ip/geo.json`	unmetered (best-effort)
ipinfo.io	`https://ipinfo.io/json`	50k req/month per IP
iplocate	`https://www.iplocate.io/api/lookup/`	1k req/day per IP

▣ Homecode Format

hs-<lat36>-<lon36>-<rand4>
  lat36   = base36 of round((lat + 90)  * 1000)   range 0..180000  ≤4 chars
  lon36   = base36 of round((lon + 180) * 1000)   range 0..360000  ≤5 chars
  rand4   = 4-char base36 room salt

example: hs-2jjy-5ihh-hna9
  → lat = (parseInt('2jjy',36) / 1000) - 90  = 28.654
  → lon = (parseInt('5ihh',36) / 1000) - 180 = 77.237
  → room = 'hna9'
PeerJS peer-IDs require [A-Za-z0-9]+(?:[_-][A-Za-z0-9]+)*  (no dots, hyphens OK).

▣ Mobile Controls

PUBG-style touch HUD

Auto-shown on touch devices. Left thumb = move joystick. Right side = look (drag) + fire button + reload + jump + crouch + grenade. Source: src/ui/TouchControls.ts. Overlay tutorial fires on first deploy via tutorialHint() with a mobile-specific message.

▣ Keybindings

Action	Key	Action	Key
Move	`WASD`	Sprint	`Shift`
Jump	`Space`	Crouch	`Ctrl`
Fire	`LMB`	Aim	`RMB`
Reload	`R`	Grenade	`G`
Switch weapon	`1-3`	Cycle weapon	`Q`
Settings	`Tab`	Pause	`Esc`
Toggle keybindings	`K`	Stats overlay	`F3`
Inspector	`F4`

▣ Public Hooks

window.__homecode      // current overlay state {mode, callsign, lat, lon, cityName, homecode, ...}
window.__homecodeUtils // { encode(lat,lon), decode(raw), setMode(m) }
window.gameState       // { state, fps, hp, wave, enemies, ... }  (after PLAY)
window.debugCommands   // { startGame, killPlayer, spawnEnemy, fire, ... }  (after PLAY)

▣ Custom Events

Event	Detail	Fired by
`homecode:locationKnown`	{lat, lon, cityName}	overlay (GPS or IP success)
`homecode:ready`	full state	overlay (DEPLOY click)

▣ Build & Deploy

cd /root/repo/homestrike-v2
NODE_OPTIONS="--max-old-space-size=2048" npx vite build
rm -rf /root/docker/homestrike-v2/dist/*
cp -r dist/* /root/docker/homestrike-v2/dist/
cd /root/docker/homestrike-v2 && docker compose restart homestrike-v2