From cd87d7378dfbc3901a02c1a051ef18b25fdb8c19 Mon Sep 17 00:00:00 2001 From: Frank Tovar Date: Tue, 24 Feb 2026 22:01:48 +0100 Subject: [PATCH] Updated docs --- AGENTS.md | 2 +- REQUIREMENTS.md | 301 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 302 insertions(+), 1 deletion(-) create mode 100644 REQUIREMENTS.md diff --git a/AGENTS.md b/AGENTS.md index bd1c2e1..c186522 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Agent Guide -Also see the other related technical documentation: TECH.md and possibly other markdown files. +Also see the other related technical documentation: TECH.md, REQUIREMENTS.md and possibly other markdown files. ## Rules diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md new file mode 100644 index 0000000..6bb5ba2 --- /dev/null +++ b/REQUIREMENTS.md @@ -0,0 +1,301 @@ +# 1. Stakeholders + +### Primary Actors + +* **Player** + + * Owns and manages characters + * Participates in campaigns + * Performs skill checks (dice rolls) + +* **Game Master (GM)** + + * Like a player (with regards to owning and managing characters) + * Owns and manages campaigns + * Oversees gameplay within a campaign + * Has visibility into all rolls (including private ones) + +* **System / Platform** + + * Enforces rulesets + * Manages state (active character, current campaign) + * Stores logs and configurations + +--- + +### Secondary Stakeholders + +* **Ruleset Designers / Maintainers** + + * Define dice mechanics (e.g., d6, D&D 5e) + * Configure skill roll formulas and constraints + +* **Observers (future optional role)** + + * View campaign logs without participating + +--- + +# 2. Core Domain Model (Refined) + +### User + +* Attributes: + + * username (unique) + * password (secured) + * displayName +* Relationships: + + * Owns multiple **Characters** + * Owns multiple **Campaigns** (as GM) + +--- + +### Campaign + +* Attributes: + + * name + * ruleset (exactly one) +* Relationships: + + * Owned by one **User (GM)** + * Contains multiple **Characters** + * Has a **shared log** + +--- + +### Ruleset + +* Predefined initially: + + * d6 system + * D&D 5e +* Defines: + + * Dice notation rules + * Skill behavior constraints + +--- + +### Character + +* Attributes: + + * name +* Relationships: + + * Owned by one **User (Player)** + * Belongs to one **Campaign** + * Has multiple **Skills** + +--- + +### Skill + +* Attributes: + + * name + * diceRollDefinition (ruleset-compliant expression, e.g. `5D+4`, `2d12+2`) +* Behavior: + + * Can be rolled + * Can be edited by Player or GM + +--- + +### Dice Roll + +* Attributes: + + * result + * visibility (public | private) + * timestamp +* Relationships: + + * Linked to a **Skill** + * Logged in **Campaign Log** + +--- + +### Campaign Log + +* Contains: + + * Chronological list of dice rolls +* Visibility: + + * Visible to all users in the campaign + * Private rolls visible only to: + + * roller + * GM + +--- + +# 3. Functional Requirements (Expanded) + +### User Management + +* Users must be able to: + + * Register with username, password, display name + * Authenticate securely +* System must: + + * Enforce unique usernames + * Store passwords securely (hashed) + +--- + +### Campaign Management + +* A GM can: + + * Create campaigns + * Assign a ruleset to a campaign + * Manage participating characters +* A campaign: + + * Must always have exactly one GM + * Must always use exactly one ruleset + +--- + +### Character Management + +* A Player can: + + * Create characters + * Assign characters to campaigns + * Edit character details +* Constraints: + + * A character belongs to exactly one campaign + * A player may have multiple characters across campaigns + +--- + +### Active Character Context + +* A Player can: + + * Activate one character at a time +* System must: + + * Enforce **at most one active character per player** + * Derive the **current campaign** from the active character + +--- + +### Skill Management + +* Players and GMs can: + + * Create skills for characters + * Edit skill definitions +* System must: + + * Validate dice expressions against the campaign ruleset + +--- + +### Dice Rolling + +* Players and GMs can: + + * Roll dice for a skill + * Choose visibility: + + * Public → visible to all + * Private → visible only to roller + GM +* System must: + + * Evaluate dice expressions deterministically and fairly + * Record all rolls in the campaign log + +--- + +### Campaign Log + +* System must: + + * Maintain a chronological log of all dice rolls +* Users can: + + * View the log of the current campaign +* Visibility rules: + + * Public rolls → visible to all participants + * Private rolls → restricted to roller + GM + +--- + +# 4. User Stories + +### User / Account + +* As a **user**, I want to register with a username and password so that I can access the system. +* As a **user**, I want a display name so that others can identify me in campaigns. + +--- + +### Campaign (GM) + +* As a **GM**, I want to create a campaign so that I can run a game session. +* As a **GM**, I want to activate a campaign so that the system knows my current context. +* As a **GM**, I want to select a ruleset so that gameplay follows a defined system. +* As a **GM**, I want to manage which characters participate so that I control the session. +* As a **GM**, I want to see all characters of my current campaign, including all of their skills. + +--- + +### Character (Player) + +* As a **player**, I want to create characters so that I can participate in campaigns. +* As a **player**, I want to assign my character to a campaign so that I can join a game. +* As a **player**, I want to activate one campaign so that the system knows my current context. +* As a **player**, I want to see all my characters of the current current campaign, including all of their skills. + +--- + +### Skills + +* As a **player**, I want to define skills with dice formulas so that I can perform actions. +* As a **GM**, I want to edit character skills so that I can enforce or adjust rules. + +--- + +### Dice Rolling + +* As a **player**, I want to roll dice for a skill so that I can resolve actions. +* As a **user**, I want to choose whether a roll is public or private so that I can control information visibility. +* As a **GM**, I want to see all rolls (including private ones) so that I can oversee the game. + +--- + +### Campaign Log + +* As a **user**, I want to see the campaign log so that I can track what happened. +* As a **user**, I want the log to update in real time so that I stay synchronized with the session. +* As a **user**, I want private rolls hidden unless permitted so that secrecy is preserved. + +--- + +# 5. Implicit Constraints & Edge Cases + +* A player cannot: + + * Activate multiple campaigns simultaneously + * Join a campaign without a character +* A character cannot: + + * Exist without an owner + * Belong to multiple campaigns simultaneously +* Dice expressions must: + + * Be validated per ruleset (no cross-system syntax leakage) +* Log integrity: + + * Must be append-only (no tampering with past rolls)