Emberfall — A Fantasy PBBG

A persistent browser-based game (PBBG): players register, create a hero, spend regenerating Energy on actions (hunting, expeditions, training), fight monsters, collect loot, and climb leaderboards. Progress persists between sessions and continues to "happen" while the player is offline (timers, energy regen).

Stack: Node.js, Express, SQLite (better-sqlite3), vanilla HTML/CSS/JS.

---

Quick Start

# 1. Clone & install
git clone <repo>
cd Emberfall
npm install

# 2. Configure
cp .env.example .env
# Edit .env — at minimum change SESSION_SECRET to a long random string

# 3. Set up the database
npm run migrate        # creates tables; safe to run multiple times

# 4. Seed a demo account (development only)
npm run seed:dev       # creates user "demo" / "demo123" with hero "Aldric"

# 5. Start the server
npm start              # http://localhost:3000

# 6. Run tests
npm test               # all unit + integration + e2e tests

Development

npm run dev            # auto-restart on file changes (node --watch)

---

How to Play

1. Register a new account at http://localhost:3000/register.html (or log in with demo / demo123 if seeded).
2. Create a hero — choose a class (Warrior, Mage, Rogue). Each class has different base stats and bonuses.
3. Hunt monsters — select a zone, spend 10 energy to fight. Victories award XP, gold, and loot. Defeat costs energy but no more.
4. Level up — earn XP to gain levels and stat points. Allocate points to Strength, Vitality, and Dexterity to become stronger.
5. Equip items — open the Inventory tab to see equipment and consumables. Click to equip weapons, armor, and trinkets. Use potions to heal or restore energy.
6. Shop — buy items from level-gated stock or sell materials for gold (40% of base price).
7. Expeditions — start a timed expedition before leaving. Claim rewards (XP, gold, loot) when you return after the duration elapses. Only one active expedition per hero at a time.
8. Leaderboards — view the top 50 heroes by level, gold, or kills.
9. Log out and back in — everything persists. Your energy continues regenerating while you were offline.

---

Project Structure

src/
  app.js              Express app (middleware, routes, error handling)
  server.js           Entry point (listens on PORT)
  config/index.js     Environment config (validates required vars)
  db/index.js         SQLite connection (WAL, FK ON)
  db/migrations/      Numbered .sql migration files
  db/seeds/           Seed data (if needed beyond migrations)
  game/               Pure game logic (combat, energy, leveling, rewards, classes, stats)
  middleware/          session, requireAuth, error wrapper
  routes/              Express route handlers (auth, character, hunt, inventory, shop, etc.)
  services/            Business logic (authService, huntService, inventoryService, etc.)
  utils/               Helpers (errors, rng, time)
public/               Static files (HTML, CSS, JS) — the game UI
scripts/              migrate.js, seed-dev.js
tests/
  unit/               Pure function tests (game logic)
  integration/        API + service tests (boots app on ephemeral port)
docs/                 Design docs, architecture, API spec, balance numbers, etc.

---

Available Scripts

Script	Description
npm start	Start the server on PORT from .env
npm run dev	Start with auto-restart on file changes
npm test	Run all unit + integration + e2e tests
npm run migrate	Run pending migrations
npm run seed:dev	Create demo account + hero + starter gear (skips in production)

---

Testing

npm test

Runs all *.test.js files via node --test. Tests use a shared SQLite file in data/ (WAL mode). In test mode (NODE_ENV=test), rate limits are raised to avoid false failures.

---

Known Issues

#	Description	Severity
1	Level-1 heroes win 100% of Meadows fights (target ≈80%). Tune monster stats via a new migration.	minor
2	GET /api/zones documented in API.md but not implemented.	major
3	npm run seed script points to nonexistent scripts/seed.js. Remove or create the file.	cosmetic
4	No test proves sessions survive a server restart.	minor
5	Hero equipment bonuses not yet passed into combat resolution.	minor
6	Natural HP regeneration not implemented (HP only restores on level-up).	minor

---

Architecture Notes

• Server is the only source of truth. Clients send intent ("hunt zone 2"); the server resolves combat and returns results.
• Lazy evaluation. Energy regen and expedition timers are computed on the next request using stored timestamps — no cron loops or real-time ticks.
• All SQL uses prepared statements. No string concatenation for queries.
• Game logic is pure functions in src/game/ — no DB, no Express. Fully unit-testable.