Real-time combat · Clan warfare · Player-driven economy · One hostile 150×150 world
About · Quick Start · Systems · Controls · Development · Status
DarkFrame drops every player onto a shared 22,500-tile map — nine terrain types, no instancing, no safe zones. Gather metal and energy by day, defend what you've built by night, and remember one rule of the wasteland: if you can reach it, you can lose it.
| 🗺️ | 🎮 | ⚔️ | 🏰 |
|---|---|---|---|
| 150 × 150 persistent world | 8-direction movement | Server-enforced combat | Clans & alliances |
| 22,500 tiles · 9 terrain types · edge wrap-around | QWEASDZXC grid movement · reserved keys · zero misclicks |
position-checked attacks · factories · flag warfare · WMDs | treasury · territory income · diplomacy |
| System | What it does | |
|---|---|---|
| ⛏️ | Gathering | Harvest metal & energy fields; auto-farm with live telemetry |
| 🏭 | Factories | Produce units through sequential build slots; honest scarcity curve (400–1,750 slots) |
| 🍺 | Beer Bases | Roaming high-reward targets with power-band calibration. Their army, strength, and loot are hidden until you walk up and scan them — intel is earned, not given |
| 🚩 | Flag Warfare | Channel-and-flee steals (no HP battles); bearer bonus stack; 12h milestone |
| ☢️ | WMDs | Strategic weapons for clan-scale warfare (revived: real damage engine, lazy-tick scheduler) |
| 🏦 | Banking | Deposits, loans, interest — the economy has a spine |
| 🔨 | Auction House | Player-to-player trading with fee economics and real unit/money escrow |
| 🎓 | Progression | XP power curve · research points (census-anchored milestones) · doctrine specializations · mastery · achievements · VIP tiers |
| 💬 | Social | Global & clan chat, friends, DMs, bounties, referrals |
| 🛡️ | Moderation | Player inspection, session/activity tracking, flags & bans |
Node.js 20+ · PostgreSQL 14+ · (optional) Redis, Stripe CLI
git clone https://github.com/savant0x/DarkFrame.git
cd DarkFrame
npm installCreate .env.local (git-ignored — never commit real credentials):
# ── Required ────────────────────────────────────────
DATABASE_URL=postgresql://user:password@host:5432/darkframe
JWT_SECRET=change-me-to-a-long-random-string
# ── Owner account (created by db:setup) ─────────────
OWNER_USERNAME=yourname
OWNER_EMAIL=you@example.com
OWNER_PASSWORD=change-me
# ── Optional ────────────────────────────────────────
PORT=3000
REDIS_URL=redis://localhost:6379
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
LOG_LEVEL=infonpm run db:setupOne stop — generates the 22,500-tile map (idempotent) and creates your owner account.
npm run dev:serverOpen http://localhost:3000 and log in.
npm run devstarts Next.js alone — fine for UI work, but no realtime or world jobs.
📄 Full command reference
| Command | What it does |
|---|---|
npm run dev:server |
Full game server — Next + Socket.io + background jobs |
npm run dev |
Next.js dev server only |
npm run db:setup |
Generate map + owner account (idempotent) |
npm run map:rebuild |
--yes required) |
npm run create-indexes |
Create DB performance indexes |
npm run test:ci |
Full test suite (Vitest, 865 tests) |
npm run lint |
ESLint (0 errors; no-console + import guards enforced) |
npx tsc --noEmit |
TypeScript check (0 errors, strict) |
npm run stripe:listen |
Stripe webhook forwarding (expects C:\stripe\stripe.exe) |
npm run validate-referrals |
Referral validation cron |
One key, one action. The movement keys are reserved — no panel or feature can ever fire when you press them. Every other action has exactly one binding; panel toggles use Shift + key. Rebind in-game via the admin Hotkey Manager.
| QWE ASD ZXC |
🧭 | Move — 8 directions (S stops) |
| G / ⇧Shift+V | ⛏️ | Harvest field / harvest cave & forest |
| R | ⚔️ | Attack factory (you must stand on it) |
| ⇧Shift+E | 🍺 | Beer Bases panel |
| B · N · U | 🏛️ | Bank · Shrine · Unit build (tile-gated) |
| ⇧Shift+C / L | 👥 | Clan view / leaderboards |
| ⇧Shift+X / ⇧Shift+D | 🤖 | Bot scanner / Discovery log |
| I / ⇧Shift+P | 🎒 | Inventory / Progression |
DarkFrame/
├── app/ Next.js App Router — pages & 230+ API routes
├── components/ Game canvas, panels, admin modals (NEON NOIR token system)
├── lib/ ~90 game services · Drizzle schema + migrations · jobs · websocket
├── types/ Shared TypeScript contracts (single-source catalogs)
├── scripts/ Setup, E2E drivers & economy simulators (run the real engine)
├── docs/ Player + design docs (audited 2026-09-15; history in dev/archives/)
├── dev/ Working notes — sessions, FIDs + archive, audits, protocol
└── SCOPE.md Authoritative scope & audit trail
Stack: Next.js 16 (App Router) · React 18 · TypeScript strict · custom Node server hosting Next + Socket.io + scheduled jobs · PostgreSQL via Drizzle ORM · JWT auth (jose, bcrypt) · Stripe subscriptions · Redis rate-limiting · Sentry · Vitest
# verify your change before pushing — all three gates must pass
npx tsc --noEmit # types (0 errors)
npm run lint # style (0 errors)
npm run test:ci # behavior (865 tests)Workflow: direct to main — no PR flow. A pre-commit hook runs the
ladder-truth gate whenever game-math sources are staged; documented
game-math tables are CI-pinned (comment drift fails the suite).
Project docs live in dev/:
| Doc | Read it for |
|---|---|
SCOPE.md |
Every change — what, why, when — plus the open decision queue |
CHANGELOG.md |
Release-by-release record of what shipped |
dev/session-summaries/ |
Per-session engineering records |
dev/fids/archive/ |
Closed feature/bug records with evidence |
Note on the DB layer: Postgres is authoritative. A Mongo-style API shim (
lib/mongodb.ts) bridges service code left over from earlier pivots and is being retired incrementally. Known rough edges are tracked openly inSCOPE.md— nothing is silently broken.
✅ PLAYABLE — GATES GREEN
Combat rebalance shipped (sequential resolution, power-proportional HP, balance executes in-combat) · economy v2 live (census-anchored milestones, shared tech catalog, 600k WMD track, battle-RP pacing) · bot vaults regrow linearly · 0 open FIDs · tsc 0 / lint 0 / 865 tests green.
Honest, per-session progress in SCOPE.md — no marketing numbers.
DarkFrame — crafted by @savant0x
All rights reserved · reuse requires permission