# Skara Brae — Vision

`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).

## 1. Introduction

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.

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).

References: game design canon in `docs/game/`, OpenUP artifact set in `docs/openup/`,
EA model in `docs/openup/model/skara-brae.eapx`.

## 2. Positioning

### 2.1 Problem Statement

|  |  |
| --- | --- |
| 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 |

### 2.2 Product Position Statement

| 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.* |

## 3. Stakeholder Descriptions

### 3.1 Stakeholder Summary

| **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 |

### 3.2 User Environment

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 |