# Session Zero - Design Document

## 1. Core Philosophy

Session Zero is an application designed to help Game Masters (GMs) and players manage tabletop role-playing games (TTRPGs). The core idea is to provide a flexible, modular system where users can define their own game systems, create characters, and run sessions with integrated custom resources. The application is designed to be fully functional offline first by default. Optional online features, such as data synchronization and collaborative sessions, are available through a tiered account system to enhance the user experience.

## 2. Core Features

### 2.1. Library (Datasets)

-   **Concept:** The Library is the foundational content repository. It allows users to create, edit, and delete individual pieces of information, such as spells, items, locations, lore entries, or rules.
-   **Structure:** Each library entry is a standalone piece of data with a name and a set of key-value pairs (e.g., Item Name, Description, Cost, Weight).
-   **Datasets:** The Library isn't monolithic. Users can group library entries into "Datasets" (e.g., "Core Fantasy Rules," "Sci-Fi Weapons Pack," "My Homebrew Monsters"). These datasets can be selectively loaded into game sessions.
- **Dataset Types:** The 'type' of a dataset is an arbitrary string that defines its purpose (e.g., "items," "spells," "monsters"). This allows for flexible categorization and retrieval of data. The application uses a few default dataset types, such as "items," "spells," "monsters," and "npcs" for specific functionality, but users can create custom types as needed.
-   **Data Management:** Users can import and export their datasets as local files, allowing for easy backups and sharing outside of the application.
-   **Online Library:** An online content library will be available for users to share and download Datasets and Templates. Downloading content is free for all users, but uploading requires a paid account.

### 2.2. Template Builder

-   **Concept:** This feature allows users to define the structure of a character sheet for a specific game system.
-   **Functionality:**
    -   **Core Fields:** Users can create a template by adding, naming, and ordering fields for the character's basic data (e.g., "Strength," "Dexterity," "Health Points"). Each field has a defined type (text, number, text area).
      - Fields can be set as required or optional, and can have default values.
      - Fields can also contain grouped data, such as a "Skills" section that contains multiple skill entries.
    -   **Custom Sections:** Users can define additional sections for the character sheet, such as a "Spells" or "Abilities" list. These sections can also link "Datasets" from the library, enabling features like searchable drop-downs to add items (e.g., spells from a "Magic" dataset) directly to the character sheet.
-   **Outcome:** A saved template is used as the blueprint for creating new characters, complete with all its defined sections and data links.

### 2.3. Character Manager

-   **Concept:** This is where users create and manage their characters based on the templates they've built.
-   **Structure:** A character sheet will be composed of distinct sections:
    -   **Core Data:** A section for the character's core attributes and information as defined by the template's basic fields.
    -   **Inventory:** A dedicated section for managing items. The template can be configured to link this section to one or more "item" type datasets.
    -   **Journal:** A private, freeform notes section for players to track their character's personal story, thoughts, and important information.
    -   **Custom Sections:** Any additional sections defined in the character's template will appear here (e.g., a "Spells" section for a wizard).
-   **Functionality:** Users can create new characters by selecting a template and filling in the data. They can view, edit, and delete existing characters.

### 2.4. Session Management

-   **Concept:** A "Session" is the central hub for running a game. It brings together characters, rules, and notes for a specific adventure or campaign.
-   **Structure:** Each Session will contain:
    -   A unique name/ID.
    -   **Loaded Datasets:** A list of active Datasets from the Library, making their content available within the session.
    -   **Session Notes:** A freeform text area for the GM to track events, plan encounters, etc.
    -   **Characters:** A list of characters participating in the session.
    -   **Online features:**
        -   **GM Mode:** The GM can control visibility of information, push updates to players, and manage session flow.
        -   **Player Mode:** Players can view their character sheets and receive updates from the GM.
        -   **Real-time Updates:** In the future, this will allow GMs to push updates to players' character sheets and session notes in real-time.
        -   **Chat Functionality:** A chat feature for GMs and players to communicate during the session.
        -   **Session History:** A log of actions taken during the session, such as character updates, notes added, and events triggered.
        -   **Chat Command Integration:** GMs and Players can use chat commands to trigger specific actions or updates within the session (e.g., rolling dice, updating character stats).
-   **Modes of Interaction:**
    -   **Offline Mode (Default):** The user acts as both GM and Player. All updates are manual. Characters from the Character Manager can be manually added to a session.
    -   **Online Mode (Future):** This mode introduces distinct GM and Player roles, managed through an account system.
        -   **GM (Host):** Requires a paid account to host a session. The GM manages the session, controls information visibility, and pushes real-time updates.
        -   **Player (Participant):** Requires a free account to join a session hosted by a GM. Players can interact with their character sheet and receive live updates.

## 3. Monetization and User Accounts

### 3.1. Account Tiers

-   **Guest (No Account):** This is the default state. The application is fully functional offline as a PWA. Guests can create and manage all local data, and download content from the online library, but cannot use other online features.
-   **Free Account:** The primary benefit is the ability to join online sessions hosted by a paid user.
-   **Paid Account:** Priced at approximately $5 USD/month, this tier provides full access to all online features, including:
    -   Hosting online sessions.
    -   Uploading content to the online library.
    -   Cross-device data synchronization.
    -   Access to other future perks.

## 4. Technical Stack

-   **Client Application:** The application is built in C# and .NET Blazor as a standalone webassembly application, with PWA enabled for offline use.
-  **Data Storage:** The application uses SQLite for local data storage, ensuring fast access and reliability. Data is stored in a structured format that allows for easy retrieval and manipulation.
- **Authentication Service:** Built using ASP web API, providing secure user account management and data synchronization.

## 5. Target Platforms
-   **Desktop:** The primary platform, with a focus on Windows and Linux, with macOS support planned.
-  **Mobile:** Future plans include adapting the application for mobile devices, allowing users to manage their games on the go.

## 6. Development Roadmap

1.  **[Done]** Implement the Library for creating raw data entries.
2.  **[Done]** Implement the Template Builder.
3.  **[Done]** Implement the Character Manager.
4.  **[Current]** Implement the initial `SessionsView` with basic note-taking.
5.  Refine the `Session` model to be more robust. **First, we will focus on allowing "Datasets" from the Library to be loaded into a Session.**
6.  Enhance Character Sheets with Inventory, Journal, and custom sections.
7.  Integrate Characters into a Session.
8.  Build out the GM/Player views within an offline session.
9.  Implement local Dataset Import/Export.
10. UI/UX Polish Pass.
11. (Future) Implement User Account System (Guest, Free, Paid).
12. (Future) Develop Online Content Library (Download for all, Upload for Paid).
13. (Future) Explore and implement backend solutions for online collaboration (session hosting, data sync).


## 7. Technical Specifications

### 7.1. Data Validation

#### Basic Value Types
- All data in the system must conform to one of these value types:
    - **Text**: Single-line string input
    - **Text-Field**: Multi-line string input for longer content
    - **Number**: Numeric values (integer or floating-point)
    - **Boolean**: True/false values
    - **Group**: Collection of nested key-value pairs

#### Validation Rules
- Each field must declare its type during creation
- All fields must have a non-empty name
- Names must be unique within their scope
- No null values are permitted
- Numbers must be valid integer or floating-point values
- Groups must contain at least one child entry
- Templates and datasets must validate their fields against these types
- Text fields have no length restriction by default, but specific implementations may impose limits

#### Type Coercion
- String to Number: Must be parseable as integer or float
- String to Boolean: "true"/"false" (case insensitive)
- Number to String: Standard string representation
- Boolean to String: Lowercase "true"/"false"

### 7.1.1 Dataset Entries
- Each entry consists of a string name and an associated value
- Value types are limited to:
    - **Text**: Single-line text input
    - **Text-Field**: Multi-line text input
    - **Number**: Integer or floating-point values
    - **Boolean**: True/false values
    - **Group**: A collection of nested entries sharing a common purpose
        - Example: A "Stats" group might contain entries for "Strength", "Dexterity", etc.
        - Groups can be nested to create hierarchical data structures
- Entry Requirements:
    - Names must be unique within their scope (either at root level or within a group)
    - Groups must have at least one child entry
    - Values must match their declared type
    - Null values are not permitted
- Example Structure:
    ```json
    {
        "Name": "Longsword",
        "Description": "A standard sword with a long blade",
        "Stats": {
            "Damage": "1d8",
            "Weight": 3,
            "IsMartial": true
        }
    }
    ```

### 7.2. Version Control
- Each dataset and template has a unique GUID identifier
- Version tracking uses semantic versioning (MAJOR.MINOR.PATCH)
- References to datasets/templates are dynamic:
    - Characters load template data at runtime
    - Sessions load dataset data at runtime
    - This ensures compatibility across versions

### 7.3. Asset Management
- Supported assets:
    - Character portraits
    - Dataset entry images (items, monsters, etc.)
- Storage specifications:
    - Local cache for offline use
    - Remote storage for online library
    - Size limits:
        - Individual images: [suggest 2MB]
        - Total cache size: [suggest 500MB]
- Format restrictions:
    - Allowed formats: PNG, JPEG
    - Maximum dimensions: [suggest 1024x1024]

### 7.4. Data Format

#### SZF (Session Zero Format)
- Primary format for all dataset files and templates
- Human-readable and easily editable
- Used for import/export operations
- File extension: `.szf`

##### Dataset Format Example
```szf
    !type: dataset
    !schema: 1.0.0
    # Dataset Metadata
    [Metadata]
    Name (text) = Core Fantasy Items
    Type (text) = items
    Version (text) = 1.0.0
    Description (text-field) = Basic fantasy items for any campaign
    
    # First Entry (Longsword)
    [Entry: Longsword]
    Name (text) = Longsword
    Description (text-field) = A standard sword with a long blade
    Category (text) = Weapon
    
    [Entry.Longsword.Stats]
    Damage (text) = 1d8
    Weight (number) = 3
    IsMartial (bool) = true
    
    # Second Entry (Health Potion)
    [Entry: Health Potion]
    Name (text) = Health Potion
    Description (text-field) = Restores health when consumed
    Category (text) = Consumable
    
    [Entry.Health Potion.Properties]
    HealingAmount (number) = 10
    Consumable (bool) = true
```

##### Character Sheet Template Example
```szf
    !type: character_template
    !schema: 1.0.
    
    # Template Metadata
    [Metadata]
    Name (text) = Fantasy Character Sheet
    Version (text) = 1.0.0
    Description (text-field) = A character sheet template for fantasy RPGs
    
    # Dataset References
    [Datasets]
    ## TODO: Declare datasets to be linked to this template somehow
    
    # Core Info Section
    [Section: Info]
    Strength (number) = 10
    Dexterity (number) = 10
    Constitution (number) = 10
    Intelligence (number) = 10
    Wisdom (number) = 10
    Charisma (number) = 10
    
    # Inventory Section
    [Section: Inventory]
    
    [Section.Inventory.Items] 
    ## This section will link to all "items" datasets bound to this template with drop-downs for adding to entries somehow
    ## and a value for how many
    
    [Section.Inventory.Weapons]
    ## This section will link to all "weapons" datasets bound to this template with drop-downs for adding to entries somehow
    ## and a value for how many

    # Journal Section
    [Section: Journal]
    Notes (text-field) = ""
    
    # Custom Section for Spells
    [Section: Spells]
    SpellsList (group) = []
```

### 7.5. Dice System (Initial Implementation)
- Basic dice notation support (e.g., "2d6", "1d20")
- Simple modifiers (e.g., "1d20+5")
- Results displayed in chat when implemented

# UI Design Specifications
### Colors
- background-color: #1a202e    
- primary-color: #3a4f6f    
- primary-color-light: #4a5f7f    
- secondary-color: #2d3f5c     
- accent-color: #5b89b3        
- text-color: #ffffff            
- heading-color: #c5d5e6