Case Study 06
Adventure Game
THE ARCHIVE — a full-stack text adventure
THE ARCHIVE is a full-stack text adventure: React frontend (choices, 18ms typewriter, ambient backgrounds, JWT auth, leaderboard) and Spring Boot backend (38-scene story service, gated choices, achievements, scoring, leaderboard). An Archivist chases the Pale Archivist across 3 chapters.
01 · Overview
Overview
- Read the scene, pick a choice, unlock items/flags, chase seals and endings.
- Demonstrates OOP, state machines, auth and client-server flow inside a game, not CRUD.
- For choice-fiction players and reviewers of game-state logic.
- Scene graph with gating, score/health deltas, 6 achievements, top-10 leaderboard, protected routing.
02 · The Problem
The Problem
- Logic, narrative and state tangle when hardcoded in UI.
- Choices need gating, scoring and endings without breaking the graph.
- Auth must persist across 38 scenes.
03 · The Solution
The Solution
- Content as data: GameScene + Choice (nextSceneId, requiresItem/Flag, scoreBonus).
- Service: validate → check items → score/health → advance → grant items → achievements → track.
- Client: skip-able typewriter, gating UI, HUD, restart/exit, ending summary.
04 · How It Works
How It Works
01 · 1. Login → JWT Bearer; 401 returns to /login; /game protected.-
1. Login → JWT Bearer; 401 returns to /login; /game protected.
02 · 2. Read+
18ms/char typewriter, click to skip; ambiance backdrops.
03 · 3. Choose+
gated until narrativeDone; missing items hide/block.
04 · 4. Resolve+
score/bonus, health, inventory, flags, achievements, timestamps.
05 · 5. End/restart+
victory endings (+100/+60) with summary; reset bumps deaths.
Select a stage to expand it. Every stage maps to code in the repository.
05 · System Architecture
System Architecture
React 18 + Router 6 + axios + framer-motion; GameScreen, api.js, useTypewriter, HUD, modals.
Spring Boot 3.2 + Java 17 + Security/JWT; GameService, Controller, 38-scene DataService.
Player state + scene graph; leaderboard top 10 by score.
06 · Core Features
Core Features
38 scenes: Awakening (riddle 'Memory'), Burning Library ('Truth'), Heart ('To witness' → true ending).
38 scenes: Awakening (riddle 'Memory'), Burning Library ('Truth'), Heart ('To witness' → true ending).
Gated choices via items/flags.
Gated choices via items/flags.
Score + health deltas.
Score + health deltas.
6 achievements including high_scorer (200+).
6 achievements including high_scorer (200+).
JWT leaderboard + auth.
JWT leaderboard + auth.
Cinematic UI with skip, HUD, summaries.
Cinematic UI with skip, HUD, summaries.
07 · Technical Implementation
Technical Implementation
- react 18.2, router 6.21, axios, react-scripts, framer-motion; proxy :8081.
- Spring Boot 3.2.0 (web, jpa, security, validation), Lombok, jjwt; postgres/h2/mysql drivers.
- docker-compose, env/CORS, run scripts, workflow dir.
08 · My Contribution
My Contribution
- 38-scene graph with chapters, ambiances, riddles, endings.
- Choice validation, gating, scoring, achievements, leaderboard, reset.
- Typewriter, gating UI, HUD, auth routing, modals.
- Kept scope shippable.
09 · Tech Stack
Tech Stack
- Frontend
- React 18 · Router 6 · axios.
- Backend
- Java 17 · Spring Boot 3.2 · JWT.
- Data
- player + scene graph · leaderboard.
- Ops
- Docker Compose · env config.
10 · Challenges & Decisions
Challenges & Decisions
- Tangle → content-as-data + resolver → story edits avoid UI code.
- Pacing → gate until done + skip → readable control.
- Scope → 3 chapters, two victory endings → finishable game.
11 · Result
Result
- 3 chapters, 38 scenes, gating, items, achievements, scoring, leaderboard, auth, cinematic UI.
- Learned: state machines, content-as-data, guarded routing, client-server flow, scoping.
12 · Links