bepis/Emberfall
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

step 9.5: done

Browse Source
This commit is contained in:
bepis
2026-10-21 11:45:36 +11:00
parent 2718f3944f
commit 1564615322
3 changed files with 141 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
HANDOFF.md
+9 -5
View File
@@ -4,8 +4,8 @@
> If this file disagrees with the code, trust the code and fix this file.
## 1. Where we are
- **Last completed step:** 9.5 (Final full run of "Definition of playable") — TICKED in STATUS.md
- **Next step:** Phase 9 — 9.6 (Update README with real run instructions)
- **Last completed step:** 9.6 (Update README with real run instructions) — TICKED in STATUS.md
- **Next step:** Phase 9 is complete. Ready to start Stretch Goals (S1–S7) or address Known Issues from STATUS.md.
- **Updated:** 2026-10-21
- **Was the last session cut off mid-task?** No
@@ -16,6 +16,7 @@
| `npm run migrate` | applies 001–006 / "nothing to do" |
| `npm test` | **176 passing, 0 failing** (85 unit + 91 integration incl. 1 e2e) |
| `npm run seed:dev` | creates demo user "demo"/"demo123", hero "Aldric" (warrior), starter gear |
| `npm start` + `curl localhost:3000/api/health` | `{"ok":true}` |
## 3. What exists now (files that matter)
- `public/game.html` — Dashboard with 3-col grid (stats | action | combat), mobile bottom nav (⚔️ Hunt / 🏕️ Trip / 🎒 Items), tabbed action area.
@@ -35,6 +36,7 @@
- `src/game/*` — Pure game logic.
- `tests/integration/*.test.js` — 91 integration tests (incl. e2e-playable.test.js).
- `tests/unit/*.test.js` — 85 unit tests.
- `README.md` — Updated with real run instructions, play-through steps, project structure, known issues.
## 4. Half-finished / fragile things
- No leaderboard UI yet (Phase 8 API done but no UI).
@@ -85,6 +87,8 @@
- Inventory sell endpoint (`POST /api/shop/sell`) only accepts `material`-type items.
- `handleListInventory` in `src/routes/inventory.js` — parameter name must be `res`, not `_res`.
## 7. Next-step briefing (9.6)
- **Goal:** Update README with real run instructions.
- Include: how to install, configure (.env), run migrations, seed dev data, start server, run tests, and basic play-through steps.
## 7. Next-step briefing
- **Phase 9 is complete.** All hardening and polish done.
- **Stretch Goals available:** S1 (PvP duels), S2 (Skills/talents), S3 (Guilds), S4 (Player market), S5 (Daily rewards/quests), S6 (In-game chat), S7 (Achievements).
- **Or address Known Issues:** Issue #2 (`GET /api/zones` missing — major), Issue #5 (equipment not in combat — minor), Issue #3 (`npm run seed` dead script — cosmetic).
- **Recommended next step:** Fix Known Issue #2 (`GET /api/zones`) since it's a documented API gap and would improve the hunt UI. Then consider S7 (Achievements) as it's a self-contained, low-risk stretch goal that adds meaningful gameplay.
README.md
+125 -24
View File
@@ -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
# 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.
STATUS.md
+6 -5
View File
@@ -7,10 +7,10 @@
> - Keep Session Log entries to one or two lines.
## Current Focus
- **Phase:** 9
- **Step:** 9.6
- **Phase:** Complete (Phase 9 done)
- **Step:** Stretch Goals
- **Blocked?** No
- **Last verified working command:** `npm test` — 176/176 passing (85 unit + 90 integration + 1 e2e), 2026-10-21 step 9.5
- **Last verified working command:** `npm test` — 176/176 passing (85 unit + 91 integration + 1 e2e), 2026-10-21 step 9.6
## Project Health
| Item | State |
@@ -111,10 +111,10 @@
*Acceptance:* `npm run seed:dev` creates migrations + demo user + hero + starter gear; safe to re-run; skipped in production.
- [x] **9.3** Global error pages / friendly UI error toasts. Loading states.
- [x] **9.4** Mobile-responsive pass (see UI_GUIDE).
- [ ] **9.5** Final full run of "Definition of playable" from NOTES.md §7. Record results below.
- [x] **9.5** Final full run of "Definition of playable" from NOTES.md §7. Record results below.
*Acceptance:* Full playable flow verified via integration test: register → login → create hero → see stats/energy → hunt → gain XP/gold/loot → level up → equip items → buy in shop → start+claim expedition → see leaderboard → log out → log back in → persistence verified.
- [ ] **9.6** Update README with real run instructions.
- [x] **9.6** Update README with real run instructions.
*Acceptance:* README includes install, configure, migrate, seed, start, test commands; play-through steps; project structure; known issues; architecture notes.
## Stretch Goals (only after Phase 9)
- [ ] S1 Async PvP duels (attack another hero's *snapshot*; cooldown; rating).
@@ -160,6 +160,7 @@ Severity: `blocker` / `major` / `minor` / `cosmetic`. Status: `open` / `fixing`
## Session Log
_Format:_ `YYYY-MM-DD | step | what changed | result`
- 2026-10-21 | 9.6 | Rewrote README.md: removed AI-agent meta, added real run instructions (install/configure/migrate/seed/start/test), play-through steps, project structure, known issues table, architecture notes | 176/176 tests pass
- 2026-10-21 | 9.5 | Created `tests/integration/e2e-playable.test.js` covering full playable flow (register → login → create hero → stats → hunt → level → equip → shop → expedition → leaderboard → logout → login → persistence); fixed `handleListInventory` bug (parameter `_res` vs `res` in `src/routes/inventory.js`); 176/176 tests pass
- 2026-10-21 | 9.4 | Mobile-responsive pass: game.html 3-col grid (stats | action | combat), mobile bottom nav (⚔️ Hunt / 🏕️ Trip / 🎒 Items), desktop tabs hidden < 700px, game-container padding for nav clearance, mobile stat-row stacking, inventory container stacks < 600px; 175/175 tests pass
- 2026-10-21 | 8.3 | Created public profile UI: `public/profile.html` + `public/js/profile.js` (fetches GET /api/heroes/:name via ?name=, displays hero name/class/level/gold/stats/equipment; 404 handling, URL-safe names); 5 integration tests | 172/172 tests pass