step 9.5: done
This commit is contained in:
bepis
@@ -5,34 +5,135 @@ 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).
|
||||
|
||||
## For the AI agent building this
|
||||
**Start with `NOTES.md`, then `STATUS.md`.** Do not read every doc up front.
|
||||
Open only the docs referenced by the step you are working on.
|
||||
**Stack:** Node.js, Express, SQLite (`better-sqlite3`), vanilla HTML/CSS/JS.
|
||||
|
||||
## Doc map
|
||||
| File | Read it when... |
|
||||
|---|---|
|
||||
| `NOTES.md` | ALWAYS first. Rules, stack, constraints. |
|
||||
| `STATUS.md` | ALWAYS second. Pick the next unchecked step. Update it when done. |
|
||||
| `docs/WORKFLOW.md` | You are unsure how to work or what "done" means. |
|
||||
| `docs/ARCHITECTURE.md` | Creating or moving files; deciding where code goes. |
|
||||
| `docs/DATABASE.md` | Touching the database or writing migrations. |
|
||||
| `docs/API.md` | Writing or calling any route. |
|
||||
| `docs/GAME_DESIGN.md` | Implementing any game mechanic. |
|
||||
| `docs/BALANCE.md` | Writing formulas, numbers, loot tables, monsters. |
|
||||
| `docs/SECURITY.md` | Auth, input handling, anything user-facing. |
|
||||
| `docs/UI_GUIDE.md` | Building pages/CSS/frontend JS. |
|
||||
| `docs/CODING_STANDARDS.md` | Style, naming, error handling. |
|
||||
| `docs/TESTING.md` | Writing or running tests. |
|
||||
| `docs/DECISIONS.md` | Making a choice that deviates from the docs. |
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
## For the human
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# 1. Clone & install
|
||||
git clone <repo>
|
||||
cd Emberfall
|
||||
npm install
|
||||
npm run migrate
|
||||
npm run seed
|
||||
npm start # http://localhost:3000
|
||||
|
||||
# 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
|
||||
```
|
||||
(These scripts are created by the agent in STATUS.md Phase 0.)
|
||||
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user