140 lines
5.0 KiB
Markdown
140 lines
5.0 KiB
Markdown
# 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.
|