jan/skara-brae-common
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

openup: doc restructure - template alignment + design sequences (non-PSP)

Browse source 
Align the OpenUP markdown set to the blank templates (process-data repo,
templates/openup/) per BUILD-CHECKLIST 7. Scenario step text unchanged;
the EA model needs no change (brief descriptions already live in the
model's UC/actor notes).

- vision.md: positioning tables, stakeholder summary, user environment,
  needs-and-features table (R1/R2), other product requirements
- use-case-model.md: per-UC specification sections (brief description,
  actor descriptions, named alternative/exception subsections with
  numbered steps, post-conditions, special requirements)
- supplementary-specifications.md: category tables with priority and
  use-case columns + reverse coverage matrix; IDs unchanged
- test/quality-check-procedure.md: migrated from Joplin (single content
  home); stale open items marked resolved (WI-1/WI-2)
- analysis-design/sequences/: 12 PlantUML design sequences (lifelines =
  analysis classes, messages = design elements; per the PlantUML layout
  style guide) + PNG renders; embedded in Architecture Notebook 9.3
- Joplin consolidated: project content notes deleted (all live in
  docs/game + docs/openup); Joplin keeps the status note only
This commit is contained in:
Jan-Peter von Hunnius 2026-10-05 11:22:38 +02:00
parent 93bb034752
commit 193562cbc4
30 changed files with 1200 additions and 124 deletions
Download patch file Download diff file Expand all files Collapse all files

93
docs/openup/requirements/vision.md
View file

@ -1,41 +1,84 @@
# Skara Brae — Vision
Version 1.0 (WI-2, 2026-10-03) · OpenUP artifact: `requirements/vision.md` · Canonical home: **skara-brae-common repo**, `docs/openup/` (decision reversed 2026-10-03; drafts move verbatim from skara-brae-server/docs/)
`Skara Brae` — OpenUP Requirements · Vision · version 2.0 (2026-10-05, restructured to the
OpenUP vision template; content unchanged in substance from version 1.0, WI-2).
Canonical home: **skara-brae-common repo**, `docs/openup/` (decision 2026-10-03).
## Problem / Opportunity
## 1. Introduction
Text-based browser MMORPGs have proven retention and monetization for two decades (Torn City, since 2004), but incumbents carry 2000s-era engines. There is room for a modern, API-first, type-safe implementation of the formula: deep numeric progression, player-driven economy, idle-friendly pacing, real-time feedback.
This Vision describes Skara Brae, a text-based browser MMORPG built as a modern
re-implementation of a proven formula. The document is maintained alongside an
implemented, growing system: the server MVP (accounts, characters, training, adventures,
economy, magic, progression) is live at `main` with the OpenUP artifact set generated from
it; later-phase features are committed in intent but not built.
## Product Vision
The product comprises three repositories: `skara-brae-server` (Rust/Axum backend),
`skara-brae-client` (Vue 3 SPA) and `skara-brae-common` (bilingual game-data package and
OpenUP artifact home). In the tables below, R1 denotes the delivered server MVP and R2 the
later-phase features (not yet committed to dates).
**Skara Brae** is a fantasy text-based/idle MMORPG set in an ancient, labyrinthine city of stone and sorcery (The Bard's Tale I inspiration, dark-fantasy tone). It transplants **Torn City's proven loop** — energy-gated activities, training, economy, social systems — into that setting, adds **idle-RPG elements** (offline progression, hireable workers, pets; Idle Fantasy inspiration), and grounds combat in a **RoleMaster-inspired critical-hit system** (open-ended d100, crit tables with bleed/stun effects, level-gap damage caps).
References: game design canon in `docs/game/`, OpenUP artifact set in `docs/openup/`,
EA model in `docs/openup/model/skara-brae.eapx`.
**Tagline:** *Set your hero to work. Close the app. Come back to loot.*
## 2. Positioning
## Stakeholders
### 2.1 Problem Statement
- **Owner/developer (solo)** — builds and operates the game on self-hosted infrastructure (Forgejo/Jenkins pipeline).
- **Players** — web/PWA users; the API-first contract also serves future community tools.
| | |
| --- | --- |
| The problem of | 2000s-era engines under proven text-based browser MMORPGs |
| affects | players of the genre (retention-heavy games with dated UX and closed stacks) and a solo developer wanting a type-safe, API-first base for community tooling |
| the impact of which is | incumbents carry legacy engines; no modern reference implementation exists for the formula with real-time feedback, idle-friendly pacing and an open API |
| a successful solution would be | a 2026-era, type-safe full-stack implementation: instant feedback, mobile-first PWA, API-first design, offline-friendly idle progression, self-hostable by one operator |
## Key Features (committed MVP scope, Phase 1)
### 2.2 Product Position Statement
1. Accounts (register/login, JWT) and character creation (5 races, 10 classes).
2. Stat training with escalating gold costs; energy/nerve/HP resources with lazy timed regeneration.
3. Adventures (energy/nerve-gated zone runs) with turn-based combat, crit tables, XP/gold/loot.
4. Economy: shop (buy/sell, stock), equipment slots, inventory.
5. Magic (class-gated spell levels, spell points) and bard songs (combat buffs).
6. Level-up review board; temple healing.
7. REST API (Rust/Axum) + Vue 3 client; WebSocket notifications.
| For | players of deep, numeric-progression browser games and the solo operator building for them |
| --- | --- |
| Who | need a modern, maintainable instance of the proven Torn-style loop |
| Skara Brae | is a fantasy text-based/idle MMORPG set in an ancient city of stone and sorcery (The Bard's Tale I inspiration, dark-fantasy tone) |
| That | transplants the proven loop — energy-gated activities, training, economy — into that setting, adds idle-RPG elements (offline progression, hireable workers, pets) and grounds combat in a RoleMaster-inspired crit system |
| Unlike | incumbent PHP-era engines with closed APIs |
| Our product | ships a Rust/Axum REST API, a Vue 3 PWA client, language-neutral game data, and a self-hosted Forgejo/Jenkins pipeline — with the tagline: *Set your hero to work. Close the app. Come back to loot.* |
Later phases (not committed): PvP, guilds, properties, crafting, pets, blessings, offline workers, tower endgame.
## 3. Stakeholder Descriptions
## Constraints & Quality Bars
### 3.1 Stakeholder Summary
- Behavior continuity: refactors must be wire-format and game-semantics identical (WI-2 governs).
- Quality gates: `cargo fmt --check`, `cargo clippy --all-targets -- -D warnings`, full test suite — zero-warning policy.
- Game data lives in the shared `skara-brae-common` repo as language-neutral JSON (single source of truth for server, client, and a future generated wiki).
- BIGINT (`i64`) stat growth; stats only ever go up.
| **Name** | **Description** | **Responsibilities** |
| --- | --- | --- |
| Owner/developer (solo) | Builds and operates the game on self-hosted infrastructure | Scope, releases, quality gate, external hosting (Forgejo/Jenkins pipeline) |
| Players | Web/PWA users; the API-first contract also serves future community tools | Play; consume the public API within its contract |
## Success Criteria (current iteration)
### 3.2 User Environment
WI-1 delivered injectable RNG (deterministic domain tests). This iteration (WI-2) delivers an architecture cleanup that makes the codebase safe to grow on: typed responses, domain-extracted adventure service, named game-balance constants, one domain error taxonomy, fmt baseline — with all 45 existing tests green and zero behavior change. Longer term: a playable MVP per the feature list above.
Players use a browser or installed PWA against the hosted Vue 3 SPA; the client polls the
REST API (assumed refresh cadence ~15 s; server behavior is poll-frequency-independent by
design). The operator runs a single Rust process per deployment (systemd), with optional
write-through SQLite persistence, behind Caddy TLS; game state otherwise lives in memory.
All game content ships compiled-in from `skara-brae-common` JSON — no external data
services for R1.
## 4. Product Overview
### 4.1 Needs and Features
| **Need** | **Priority** | **Features** | **Planned Release** |
| --- | --- | --- | --- |
| Progress a character | High | Accounts (register/login, JWT), character creation (5 races, 10 classes), stat training with escalating gold costs, level-up review board | R1 |
| Adventure and fight | High | Energy/nerve-gated zone adventures, turn-based combat with open-ended d100 rolls and RoleMaster crit tables, XP/gold/loot | R1 |
| Run an economy | High | Shop (buy/sell, rotating stock), equipment slots, inventory | R1 |
| Wield magic and song | High | Class-gated spell levels with spell points, bard songs with combat effects | R1 |
| Regenerate over time | High | Energy/nerve/HP resources with lazy timed regeneration; temple healing | R1 |
| Consume the game programmatically | High | REST JSON API (Rust/Axum), Vue 3 client; WebSocket notifications | R1 (WS: later R1+) |
| Play idly | Medium | Offline progression, hireable workers, pets; further endgame (tower, guilds, properties, crafting, blessings, PvP) | R2 |
## 5. Other Product Requirements
| **Requirement** | **Priority** | **Planned Release** |
| --- | --- | --- |
| Behavior continuity: refactors must be wire-format and game-semantics identical | High | R1 (standing) |
| Quality gates: `cargo fmt --check`, `cargo clippy --all-targets -- -D warnings`, full test suite — zero-warning policy | High | R1 (standing) |
| Game data lives in the shared `skara-brae-common` repo as language-neutral JSON (single source of truth for server, client and future generated wiki) | High | R1 |
| BIGINT (`i64`) stat growth; stats only ever go up | High | R1 |
| Self-hosted pipeline: Forgejo (git), Jenkins CI, systemd + Caddy deployment | Medium | R1 |