# 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

```bash
# 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

```bash
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

```bash
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.