Bellsworne/sessionzero-resources
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

July 15 2025

Browse Source
This commit is contained in:
Chris Bell 2025-07-15 00:06:27 -05:00
parent b4792ca008
commit 765880da98
5 changed files with 956 additions and 124 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

192
design-doc.md
View File

@ -1,151 +1,95 @@
# Session Zero - Design Document
# SessionZero Design Doc
***© Bellsworne LLC 2025***
## 1. Core Philosophy
***Last modified by Christopher Bell on July 14th 2025***
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.
## About SessionZero
## 2. Core Features
SessionZero is a free and open-source TTRPG "companion" application for managing characters, templates, data, and game sessions. It allows you to utilize any TTRPG system by being **completely data-driven** with user-generated content.
### 2.1. Library (Datasets)
## Features
- **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.
SessionZero at its core is all about managing and creating data. Everything from sets of items or NPCs to characters themselves are all user-generated pieces of content that can be used throughout the application.
### 2.2. Template Builder
### Data Types
- **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.
The client allows you to Create, View, Manage, Import & Export, and even Download various data types:
### 2.3. Character Manager
#### Datasets
Datasets are flexible collections of user-defined data, such as items, NPCs, or monsters.
- The type and content are completely arbitrary and user-defined.
- Datasets contain "entries" with custom fields and values.
- Entries can be linked throughout SessionZero, including in Character Templates.
- **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.
#### Characters
Characters are made up of two parts: The **Template** and the **Character instance**.
### 2.4. Session Management
##### Template
The template is the blueprint for a character sheet and is completely user-defined. It allows you to:
- Create sections with custom fields (e.g., text, numbers, booleans).
- Set default values for fields.
- Define calculated values using formulas.
- Reference entries from one or more Datasets.
- Create special list-based sections for things like inventories or spellbooks.
- **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.
##### Character (Instance)
This is an instance of a character created from a template. You choose a template, fill in the values, and all calculated fields populate automatically.
## 3. Monetization and User Accounts
### Game Sessions
### 3.1. Account Tiers
SessionZero offers a simple yet robust system for managing game sessions. You can manage player characters, handle resources via datasets, use a turn tracker, and more.
- **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.
The application supports several modes:
## 4. Technical Stack
#### Default (Offline) Mode
By default, SessionZero works completely offline.
- You have total ownership over your locally stored session data.
- Manually manage characters for your players or use it for your own session notes.
- **Client Application:** The application is built in C# using Avalonia, a cross-platform UI framework. This allows for creation of a desktop application that can run on Windows, macOS, and Linux, and later be adapted for mobile platforms.
- **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.
#### Online Player
Connect to a SessionZero server to join sessions hosted by others.
- Access your character sheet, in-game chat, and session notes.
- All data updates in real-time.
- Keep private notes in your personal journal for each session.
## 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.
#### Online Game Master
Host an online session and invite others to join.
- Set a character template for the session.
- Manage all session data (NPCs, items, etc.).
- Make real-time updates to character sheets.
- Use tools like in-game chat, commands, and a turn tracker.
## 6. Development Roadmap
### SessionZeroDB
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).
SessionZeroDB is an online repository of user-created SZF data. When enabled, the application can automatically find and download required datasets and templates.
### SZF (SessionZero Format)
## 7. Technical Specifications
SessionZero uses a custom, human-readable data format called SZF for all data types. For more details, read the [SZF Docs](https://sessionzero.app/szf-docs.html).
### 7.1. Data Validation
- Field types are restricted to three basic types:
- Number (integer/float)
- Boolean (true/false)
- String (text)
- Each field must declare its type during creation
- Templates and datasets must validate their fields against these types
## Philosophy
### 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
### Free
SessionZero is **FREE**. No account or subscription fees are required for the core application.
### 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]
### Open Source
SessionZero is first and foremost **open-source software**. We believe in the right to see what's going on behind the scenes.
### 7.4. Import/Export
- Primary format: JSON for programmatic use
- Secondary format: Custom human-readable text format
- Easier for manual editing
- Simple key-value pair structure
- No direct import support from other systems
- All imported content must match the application's schema
### Offline-First
By default, SessionZero works **completely offline**. Your data is stored locally on your machine. No account required. No phoning home.
### 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
### No BS
No AI chatbots, no ads, no bloat. We promise.
# 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
## Online Accounts & Server Connections
All SessionZero accounts are created and managed on the official SessionZero servers, which is always free.
For hosting and playing in online game sessions, the application lets you choose which server to connect to. This is where the self-host option comes in:
* **Self-Hosted Server (Free):** Host our open-source server backend yourself. This allows you to create and join online sessions without a subscription.
* **Official Session Servers (Subscription):** For convenience, connect to the official SessionZero servers. Access for hosting and joining sessions requires a monthly subscription.
## Technical Details
- **Client:** Avalonia C#
- **Server:** ASP.NET, PostgreSQL

297
new-szf-docs.md Normal file
View File

@ -0,0 +1,297 @@
# **Session Zero Format (.szf) Specification**
## **1. Overview**
The Session Zero Format (.szf) is a structured, human-readable data format for defining and storing tabletop RPG data, including characters, templates, and game assets. It is designed to be simple to write by hand, easy to parse, and flexible enough to support a wide variety of game systems.
### **Core Principles**
* **Human-Readable:** The format uses plain text and a clear, indented structure that is easy to read and edit.
* **Structured & Typed:** Data is organized into logical sections with explicitly declared field types defined in templates.
* **Extensible:** The format can be extended with new fields and sections without breaking existing parsers.
* **Portable:** .szf files are self-contained and can be easily shared and used across different platforms.
## **2. File Structure**
Every .szf file consists of three main parts: a **Header**, a **Metadata Section**, and one or more **Content Sections**.
### **2.1. Header**
The header is mandatory and must be the first two lines of the file. It declares the file type and the schema version.
```
!type: [file_type]
!schema: [schema_version]
```
* **\!type**: Defines the purpose of the file. Valid types are:
* dataset: A collection of related game elements (e.g., items, spells).
* character\_template: A blueprint defining the structure of a character sheet.
* character: An instance of a character created from a template.
* session: Data related to a specific game session (future use).
* **\!schema**: The version of the .szf specification the file adheres to (e.g., 1.1.0).
### **2.2. Sections**
Data is organized into named sections. Sections create a hierarchical structure for organizing related fields.
**Syntax:** `[SectionName]`
* SectionName must be a single word, is case-sensitive, and must use **PascalCase** (e.g., AbilityScores, CharacterInfo).
### **2.3. Nested Sections**
Sections can be nested to create a logical hierarchy. The dot (.) notation is used to define a parent-child relationship.
**Syntax:** `[ParentSection.ChildSection]`
This indicates that ChildSection is a subsection within ParentSection.
```
[AbilityScores]
Strength (number) = 10
[AbilityScores.Modifiers]
StrengthMod (calculated) = (AbilityScores.Strength - 10) / 2
```
### **2.4. Fields**
Fields represent individual pieces of data within a section. Each field has a name, a type, and a value.
**Syntax:** `FieldName (type) = value`
* **FieldName**: The name of the field. Must be a single word, is case-sensitive, and must use **PascalCase** (e.g., CharacterName, MaxHealth).
* **(type)**: The data type of the field, enclosed in parentheses. See Section 3 for a full list of types.
* **=**: The assignment operator.
* **value**: The data assigned to the field. The format of the value depends on the field type.
### **2.5. Comments**
Comments are denoted by a hash symbol (#) at the beginning of a line. Parsers should ignore comments. In-line comments are not supported yet.
```
# This is a full-line comment.
FieldName (text) = Some Value
```
## **3. Field Types**
The .szf format supports a variety of field types to handle different kinds of data. These types are declared in character_template and dataset files.
| Type | Description | Example Value |
|:---------------------|:----------------------------------------------------------------|:---------------------------------------------|
| text | A single line of text. | Elara the Brave |
| text-field | A multi-line block of text. | A long sword forged by...\nIt glows faintly. |
| number | An integer or floating-point number. | 16 or 3.5 |
| bool | A boolean value. | true or false |
| calculated | A value derived from a formula. | (Strength - 10) / 2 |
| system | A special field that controls application behavior. | |
| entry-reference | A reference to a single entry from a dataset. | ClassData or ItemData.Longsword |
| entry-reference-list | A comma-separated list of references to entries from a dataset. | CoreFeats.PowerAttack, CoreFeats.Cleave |
## **4. File Type Specifications**
### **4.1. Dataset (!type: dataset)**
A dataset file is a collection of structured entries.
* **[Metadata] Section**: Contains information about the dataset.
* Name (text): The human-readable name of the dataset.
* Type (text): The category of the dataset (e.g., items, spells, classes, etc.). This is a completely arbitrary value, and user-definable, but should match the intended use of the dataset.
* Guid (text): A globally unique identifier. **Optional**: If left blank, the system can generate one.
* Version (text): The semantic version of the dataset.
* **[EntryName]/Section**: In datasets, sections are referred to as entries. Each entry represents a specific item, spell, or other game element.
* EntryName is the unique key for the entry within the dataset.
* Every entry must have a non-empty `Name (text)` field. This is the display name for the entry.
**Example: CoreItems.szf**
```
!type: dataset
!schema: 1.1.0
# Metadata for the entire item collection
[Metadata]
# Required metadata for datasets
Name (text) = Core Fantasy Items
Type (text) = items
Guid (text) = c3d4e5f6-g7h8-9012-cdef-123456789012
Version (text) = 1.0.0
# Optional metadata
Author (text) = Fantasy Creator
Description (text-field) = A collection of basic items for any fantasy campaign.
# Definition for a Longsword
[Longsword]
Name (text) = Longsword
Description (text-field) = A standard sword with a long blade and crossguard.
Category (text) = Weapon
[Longsword.Stats]
Damage (text) = 1d8 slashing
Weight (number) = 3
Cost (number) = 15
IsMartial (bool) = true
```
### **4.2. Character Template (!type: character_template)**
A character_template defines the structure, fields, and rules for a character sheet.
* **[Metadata] Section**: Contains information about the template.
* **[RequiredDatasets] Section**: Lists all datasets required by this template.
* The field name is a local alias for the dataset (e.g., CoreItems).
* The value is a pipe-separated string: DatasetName|GUID|Version.
* **[SectionName]**: Defines a section on the character sheet. Contains fields with types and default values.
* Subsections can be defined using dot notation (e.g., `[AbilityScores.Modifiers]`).
* **System Fields**: Special fields that modify the behavior of sections.
* `DatasetType (system)`: Restricts a section to hold references from datasets of a specific type (e.g., `items`).
* `DatasetReference (system)`: Restricts a section to hold references from a specific dataset, identified by its alias from `[RequiredDatasets]`.
* `AllowQuantity (system)`: When set, allows entry-reference fields within that section to have an associated quantity field.
**Example: FantasyTemplate.szf**
```
!type: character_template
!schema: 1.1.0
[Metadata]
# Required metadata for character templates
Name (text) = Standard Fantasy Character
Guid (text) = f9e8d7c6-b5a4-3210-9876-543210fedcba
Version (text) = 2.1.0
# Optional metadata
Author (text) = Template Master
# Datasets needed for this character sheet
[Required Datasets]
ClassData (text) = Core Classes|aaa-bbb-ccc|1.5.0
ItemData (text) = Core Fantasy Items|c3d4e5f6-g7h8-9012-cdef-123456789012|1.0.0
WeaponData (text) = Core Weapons|12345678-90ab-cdef-1234567890ab|1.0.0
# Character information section
[Info]
CharacterName (text) =
# This field expects a single entry from the 'ClassData' dataset.
Class (entry-reference) = ClassData
# Ability scores with default values
[AbilityScores]
Strength (number) = 10
Dexterity (number) = 10
[AbilityScores.Modifiers]
StrengthMod (calculated) = (AbilityScores.Strength - 10) / 2
DexterityMod (calculated) = (AbilityScores.Dexterity - 10) / 2
# An equipment section linked to a specific dataset `WeaponData`
# This section can only contain references to entries in the `WeaponData` dataset.
[Equipment]
DatasetReference (system) = WeaponData
# An inventory section that can hold multiple items from the `ItemData` dataset.
[Inventory]
DatasetType (system) = items
AllowQuantity (system) = true
```
### **4.3. Character (!type: character)**
A character file is an instance of a character_template filled with specific data. It **only contains values**, as the structure and types are defined by the template.
* **[Metadata] Section**: Contains information about the character.
* TemplateRef (text): A mandatory reference to the source template: TemplateName|GUID|Version.
* **Content Sections**: The sections defined in the template are populated with the character's specific values. Field types are not re-declared.
**Example: Elara.szf**
```
!type: character
!schema: 1.1.0
[Metadata]
# Required metadata for character files
Name = Aela the Huntress
Guid = a1b2c3d4-e5f6-7890-abcd-ef1234567890
Version = 1.0.0
TemplateRef = Standard Fantasy Character|f9e8d7c6-b5a4-3210-9876-543210fedcba|2.1.0
[Info]
CharacterName = Aela the Huntress
# The value 'Ranger' is an entry from the 'ClassData' dataset,
# as specified by the 'Class' field in the template.
Class = Ranger
[AbilityScores]
Strength = 16
Dexterity = 14
# Calculated values are not stored in the character file.
[Equipment]
# This section becomes an addable list of items with quantities restricted to the `WeaponData` dataset, as defined in the template.
# 'PrimaryWeapon' is a user-defined field name for the item.
# The value 'Longsword' refers to the 'Longsword' entry in the 'WeaponData' dataset.
PrimaryWeapon = ItemData.Longsword
PrimaryWeapon.Quantity = 1
[Inventory]
# This section becomes an addable list of items from any dataset of type 'items', and allows specifying quantities.
# 'HealingPotion' and 'HempRope' are user-defined field names for the items,
# collected from the 'ItemData' notated by the prefix.
HealingPotion = ItemData.HealingPotion
HealingPotion.Quantity = 5
HempRope = ItemData.HempRope
HempRope.Quantity = 2
```
## **5. Advanced Features**
### **5.1. System Properties**
System properties are special fields within a character_template that modify the behavior of a section.
* `DatasetType (system) = type`: Restricts a section to holding references from datasets of a specific type (e.g., items).
* `DatasetReference (system) = alias`: Restricts a section to holding references from a specific dataset, identified by its alias from `[RequiredDatasets]`.
* **Note:** A section can have DatasetType or DatasetReference, but not both.
* `AllowQuantity (system) = true`: When set, allows entry-reference fields within that section to have an associated quantity field.
### **5.2. Quantity Fields**
If a template section has `AllowQuantity (system) = true`, a character file can specify a quantity for any item referenced in that section.
**Syntax:** `ReferenceFieldName.Quantity = value`
The quantity field's name is constructed by appending .Quantity to the name of the corresponding entry-reference field.
### **5.3. Calculated Fields**
Fields of type `calculated` contain formulas that are evaluated by the application.
* Formulas can reference other fields using dot notation to access other sections (e.g., AbilityScores.Strength).
* Supported operations should include basic arithmetic (+, -, *, /), and parentheses for grouping.
### **5.4. Wildcard Calculations**
For sections where AllowQuantity is enabled, special wildcard syntax can be used in calculated fields to perform aggregate calculations.
* `SectionName.*.FieldName`: Refers to the FieldName property of *all* items referenced in SectionName.
**Example (in a template):**
```
[Inventory]
DatasetType (system) = items
AllowQuantity (system) = true
TotalWeight (calculated) = Inventory.*.Weight * Inventory.*.Quantity
```
## **6. Best Practices**
1. **GUIDs:** Leave this blank, and the system will generate a GUID for you. This ensures uniqueness across datasets and templates.
If you need to specify one, use a valid GUID format.
2. **Versioning:** Use semantic versioning for your files to manage updates and breaking changes.
3. **Naming Convention:** Strictly use **PascalCase** for all SectionNames and FieldNames.
4. **Nested sections/Sub-sections:** Use dot notation to create logical hierarchies but avoid excessive nesting to maintain readability.
5. **Dependencies:** Explicitly list all required datasets in templates.
6. **Validation:** Before use, validate that a file's structure is correct and all references are valid.

151
old-design-doc.md Normal file
View File

@ -0,0 +1,151 @@
# 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:** _NEED TO CHOOSE THIS_
- **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
- Field types are restricted to three basic types:
- Number (integer/float)
- Boolean (true/false)
- String (text)
- Each field must declare its type during creation
- Templates and datasets must validate their fields against these types
### 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. Import/Export
- Primary format: JSON for programmatic use
- Secondary format: Custom human-readable text format
- Easier for manual editing
- Simple key-value pair structure
- No direct import support from other systems
- All imported content must match the application's schema
### 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

365
technical-specifications.md Normal file
View File

@ -0,0 +1,365 @@
# Session Zero - Design Document
## Executive Summary
Session Zero is a comprehensive tabletop RPG management application designed with an "offline-first" philosophy. The application enables Game Masters and players to create custom game systems, manage characters, and run sessions with integrated resources. Core functionality operates entirely offline, with optional online features available through tiered accounts for enhanced collaboration and content sharing.
## Core Architecture
### Design Philosophy
The application follows a modular, data-driven approach where users define their own game systems rather than being locked into predefined rulesets. Everything is built around flexibility and user customization, with offline functionality as the primary focus.
### Key Principles
- **Offline First**: Full functionality without internet connection
- **User-Defined Systems**: No hardcoded game rules or restrictions
- **Modular Content**: Reusable datasets and templates
- **Progressive Enhancement**: Online features enhance but don't replace offline capabilities
## Feature Specifications
### 1. Library System (Content Management)
The Library serves as the central content repository, organized into modular datasets that can be mixed and matched across different games and sessions.
#### Dataset Structure
- **Purpose**: Logical groupings of related content (e.g., "Core Fantasy Items", "Homebrew Monsters")
- **Type System**: Arbitrary string identifiers for categorization ("items", "spells", "monsters", "npcs", etc.)
- **Content Entries**: Individual data records with name and structured key-value pairs
- **Flexibility**: Users can create custom dataset types beyond the built-in defaults
#### Field Types
- **Text**: Single-line string input
- **Text-Field**: Multi-line text areas
- **Number**: Integer or floating-point values
- **Boolean**: True/false checkboxes
- **Group**: Nested collections of related fields
- **Calculated**: Dynamically computed values based on mathematical formulas referencing other fields
- **System**: Special fields handled by the application framework for configuration purposes
- **Dataset-Reference**: Reference to a specific dataset identified by its unique identifier
- **Dataset-Type**: Generic reference to any dataset of a specified type (e.g., items, spells)
- **Dataset-Reference-Multiple**: Multiple selection reference to a specific dataset
- **Dataset-Type-Multiple**: Multiple selection reference to any dataset of a specified type
#### Data Management
- **Local Storage**: All datasets stored locally in LocalStorage for fast access
- **Cloud Sync**: Optional synchronization for paid accounts
- **Import/Export**: Native support for dataset backup and sharing via .szf files
- **Version Control**: Each dataset has unique GUID and semantic versioning
- **Online Library**: Community content hub (download free, upload requires paid account)
### 2. Template Builder (Character Sheet Designer)
Templates define the structure and layout of character sheets for specific game systems, providing the blueprint for character creation.
#### Template Components
- **Core Fields**: Basic character attributes (stats, names, etc.) with configurable types
- **Field Properties**: Required/optional flags, default values, validation rules
- **Grouped Data**: Hierarchical sections (e.g., "Skills" containing multiple skill entries)
- **Dataset Integration**: Link datasets to templates for contextual dropdowns and data binding
#### Field Types
- **Text**: Single-line string input
- **Text-Field**: Multi-line text areas
- **Number**: Integer or floating-point values
- **Boolean**: True/false checkboxes
- **Group**: Nested collections of related fields
#### Template Features
- **Section Management**: Organize character sheet into logical sections
- **Data Binding**: Connect sections to dataset types for searchable dropdowns
- **Validation**: Enforce required fields and data type constraints
- **Reusability**: One template can generate unlimited characters
#### Dataset Integration
- **Required Datasets**: Templates specify dependencies via Name|GUID|Version format
- **Reference Types**:
- **Dataset-Reference**: Direct reference to specific dataset entries by key
- **Dataset-Type**: Generic reference to any dataset of a specified type
- **Multiple Selection**: Support for selecting multiple items from datasets
- **Section Binding**: Entire sections can be bound to dataset types
- **Selection Modes**: Single selection, multiple selection with optional count limits
- **System Properties**: Special template properties handled by the application framework
#### Data Management
- **Local Storage**: All templates stored locally in LocalStorage for fast access
- **Cloud Sync**: Optional synchronization for paid accounts
- **Import/Export**: Native support for template backup and sharing via .szf files
- **Version Control**: Each template has unique GUID and semantic versioning
- **Online Library**: Community templates hub (download free, upload requires paid account)
#### Dataset Dependencies
- **Reference Format**: `Name|GUID|Version` triple identifies exact dataset requirements
- **Dependency Resolution**: Templates fetch dependencies from local storage by GUID and version
- **Fallback Behavior**: Missing dependencies prompt download from community library
- **Graceful Degradation**: Templates function with empty datasets if dependencies unavailable
- **Type Discovery**: Dataset types determined from metadata, not hardcoded in templates
### 3. Character Manager (Character Sheet Interface)
Character sheets are runtime instances of templates, populated with player data and linked to relevant datasets.
#### Character Sheet Structure
- **Core Data**: Template-defined attributes and basic information
- **Inventory System**: Dedicated item management linked to "items" datasets
- **Private Journal**: Freeform notes section for personal character development
- **Custom Sections**: Template-defined sections (spells, abilities, etc.)
- **Dynamic Content**: Real-time access to linked dataset entries
#### Character Operations
- **Creation**: Select template and populate initial data
- **Management**: Edit, duplicate, or delete existing characters
- **Data Validation**: Ensure character data conforms to template requirements
- **Asset Support**: Character portraits and custom images
#### Data Management
- **Local Storage**: All character sheets stored locally in LocalStorage for fast access
- **Cloud Sync**: Optional synchronization for paid accounts
- **Import/Export**: Native support for character backup and sharing via .szf files
### 4. Session Management (Game Runtime Environment)
Sessions provide the active gaming environment where GMs and players interact with characters, datasets, and shared resources.
#### Session Components
- **Session Identity**: Unique name/ID for organization
- **Active Datasets**: Loaded content libraries available during play
- **Session Notes**: GM workspace for encounter planning and event tracking
- **Character Roster**: Active participants and their character sheets
- **Session History**: Audit log of actions and changes during play
#### Operational Modes
**Offline Mode (Default)**
- Single-user environment (GM and Player roles combined)
- Manual character management and updates
- Local-only data access
- Full functionality without internet connection
**Online Mode (Future Implementation)**
- **GM Role**: Requires paid account to host sessions
- Control information visibility
- Push real-time updates to players
- Manage session flow and permissions
- **Player Role**: Requires free account to join hosted sessions
- Access personal character sheet
- Receive live updates from GM
- Participate in session chat
#### Future Online Features
- **Real-time Collaboration**: Live character sheet updates
- **Chat Integration**: Text communication with command support
- **Dice Rolling**: Built-in dice system with notation support
- **Information Control**: GM-managed visibility of content
## Technical Implementation
### Technology Stack
- **Frontend**: C# .NET Blazor Standalone WebAssembly (PWA-enabled)
- **Local Storage**: Browser LocalStorage for session data
- **Authentication**: ASP.NET Web API (future online features)
- **Online Database**: POSTGRESQL (for future online features)
- **File Format**: Custom .szf (Session Zero Format) for data interchange and storage
### Data Architecture
#### Storage Strategy
- **Local Primary**: LocalStorage for all local data
- **Runtime Loading**: Templates and datasets loaded dynamically from LocalStorage
- **Version Compatibility**: GUID-based references ensure data integrity across versions
- **Asset Management**: Local caching with size limits (2MB per image, 500MB total cache)
#### Validation System
- **Type Safety**: Strict enforcement of declared field types
- **Data Integrity**: No null values permitted, unique names within scope
- **Type Coercion**: Automatic conversion between compatible types
- **Hierarchical Validation**: Groups must contain at least one child entry
#### Calculated Fields
- **Formula Parsing**: Support for mathematical expressions with field references
- **Runtime Evaluation**: Formulas re-evaluated whenever dependency values change
- **Function Support**: Built-in math functions (SUM, MIN, MAX, etc.)
- **Cross-Field References**: Reference other fields by name in calculations
- **Nested References**: Access properties of referenced dataset entries (e.g., Equipment.Weight)
### File Format Specification (.szf)
Session Zero Format provides human-readable, structured data representation for all content types.
#### Dataset Example
```szf
!type: dataset
!schema: 1.0.0
[Metadata]
Name (text) = Core Fantasy Items
Type (text) = items
Version (text) = 1.0.0
Description (text-field) = Basic fantasy items for any campaign
[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
```
#### Template Example
```szf
!type: character_template
!schema: 1.0.0
[Metadata]
Name (text) = Fantasy Character Sheet
Version (text) = 2.0.0
GUID (text) = f9e8d7c6-b5a4-3210-9876-543210fedcba
Description (text-field) = Advanced character sheet for fantasy RPGs
Author (text) = Template Master
GameSystem (text) = Fantasy RPG Universal
[Required Datasets]
ClassesDataset (text) = Core Classes|c3d4e5f6-g7h8-9012-cdef-123456789012|1.5.0
RacesDataset (text) = Playable Races|d4e5f6g7-h8i9-0123-def0-234567890123|1.3.0
[Section: Core Identity]
Name (text) =
Race (dataset-reference) = RacesDataset
Class (dataset-reference) = ClassesDataset
Level (number) = 1
[Section: Ability Scores]
Strength (number) = 10
Dexterity (number) = 10
Constitution (number) = 10
[Section.Ability Scores.Modifiers]
StrengthMod (calculated) = (Strength - 10) / 2
DexterityMod (calculated) = (Dexterity - 10) / 2
[Section: Inventory]
DatasetType (system) = items
SelectionMode (system) = multiple
MaxItems (number) = 50
CarryingCapacity (calculated) = Strength * 15
[Section: Equipment]
PrimaryWeapon (dataset-type) = items
SecondaryWeapon (dataset-type) = items
[Section: Spellcasting]
DatasetType (system) = spells
SpellSaveDC (calculated) = 8 + ProficiencyBonus + IntelligenceMod
[Section.Spellcasting.Known Spells]
Cantrips (dataset-type-multiple) = spells
Level1Spells (dataset-type-multiple) = spells
```
## Business Model
### Account Tiers
**Guest (No Account) - $0**
- Full offline functionality
- Download community content
- Export/import for data
- PWA installation
**Free Account - $0**
- All Guest features
- Join online sessions hosted by paid users
- Basic profile management
**Paid Account - $5/month**
- All Free features
- Host unlimited online sessions
- Upload content to community library
- Cross-device data synchronization
- Priority support
### Monetization Strategy
- **Freemium Model**: Core functionality free, collaboration features paid
- **Content Ecosystem**: Revenue sharing with popular content creators
- **Enterprise Features**: Advanced GM tools and campaign management (future)
## Development Roadmap
### Phase 1: Core Foundation
- [] Library system implementation
- [] Template Builder functionality
- [] Character Manager interface
- [] Basic session framework
### Phase 2: Enhanced Sessions
- [ ] Dataset loading into sessions
- [ ] Advanced session management
- [ ] Character-session integration
- [ ] Offline GM/Player workflow
### Phase 3: Data Management
- [ ] Import/export functionality
- [ ] Asset management system
- [ ] Advanced validation
- [ ] Performance optimization
### Phase 4: Polish & Usability
- [ ] UI/UX refinement
- [ ] Mobile responsiveness
- [ ] Accessibility compliance
- [ ] User testing integration
### Phase 5: Online Features (Future)
- [ ] Account system implementation
- [ ] Community content library
- [ ] Real-time collaboration
- [ ] Advanced GM tools
## Platform Strategy
### Primary Targets
- **Desktop**: PWA for cross-platform desktop usage
- **Mobile**: PWA for mobile devices
### Distribution
- **PWA**: Progressive Web App for cross-platform compatibility
- **Web Access**: Browser-based access for quick usage
## Technical Considerations
### Performance Requirements
- **Startup Time**: < Needs testing
- **Database Operations**: < Needs testing
- **Memory Usage**: < Needs testing
- **Offline Capability**: Full functionality without network
### Security & Privacy
- **Local Data**: All personal data stored locally by default
- **Content Sharing**: Explicit user consent for uploads
- **Account Security**: Standard authentication practices for online features
- **Optional Sync**: Paid accounts can optionally opt-in to cloud synchronization of datasets and characters
### Scalability
- **Local Limits**: 1000+ characters, 100+ datasets per user
- **Online Sessions**: 10+ concurrent players per session
- **Content Library**: Community-driven growth model
## UI Design System
### Color Palette
- **Background**: #1a202e (Dark theme primary)
- **Primary**: #3a4f6f (Interactive elements)
- **Primary Light**: #4a5f7f (Hover states)
- **Secondary**: #2d3f5c (Secondary elements)
- **Accent**: #5b89b3 (Highlights and CTAs)
- **Text**: #ffffff (Primary text)
- **Headings**: #c5d5e6 (Section headers)
### Design Principles
- **Dark Theme**: Reduce eye strain during long gaming sessions
- **Clear Hierarchy**: Visual organization of complex information
- **Responsive**: Consistent experience across device sizes

75
tmp.txt Normal file
View File

@ -0,0 +1,75 @@
# SessionZero Design Doc
***© Bellsworne LLC 2025***
***Last modified by Christopher Bell on July 14th 2025***
## About SessionZero
SessionZero is a free and open-source TTRPG "companion" application for managing characters, templates, data, and game sessions. It allows you to utilize any TTRPG system by being complately data-driven with user generated content.
## Features
SessionZero at it's core is all about managing and creating data. Everything from sets of items or npcs to characters themselves are all user-generated pieces of content that can be used throughout the application.
### Data types
The client allows you to Create, View, Manage, Import & Export, and even Download the various data types:
#### Datasets
Datasets can be anything. Items, NPCs, monsters, etc. The dataset type and the content within are completely arbitrary and user defined. Datasets contain "entries" that have user-defined fields and values of various types that can be grouped under sub-sections within an entry.
These can be linked to various things throughout SessionZero, including Character Templates, to allow accessing the data within.
#### Characters
Characters are made up of two parts: The Template, and the Character instance.
##### Template
This is the main sauce of your game. The character template sets up everything about a character, and is completely arbitrary and user defined. You can create sections that have user-defined fields of various types that can have default values, calculated values (using formulas), or references to dataset(s) or dataset types. You can link datasets to a template to be used in dropdown fields. There are also some special section-level features such as making a section have multiple values of a type and optionally adding quantities. (See the SZF documentation for more info)
##### Character (instance)
This is the instance of a character template. You choose a template, and then choose all of the values, items, etc. Calculated fields will populate automatically.
### Game Sessions
SessionZero sessions are simple, yet robust. You can set a session-specific character template to create and manage player characters, manage 'datasets' for various resources (NPCs, items, locations, etc), use a turn tracker, run various built-in commands, and more.
The core application lets you manage your game sessions in a few different modes:
#### Default (Offline) mode
By deafult SessionZero works totally offline. This means each session you create, you have total ownership over. You can manually add characters for each of your players to keep track of them, and manage all other aspects yourself. You can also just use a session as a player to keep track of session-specific notes.
#### Online Player
If you have an account and are connected to a valid SessionZero server, you can join sessions created by others. You will have access to your character sheet, in-game chat, session notes, and other data that the GM gives you access to. All characters and session data update in real time as the session plays out. You can also take notes for each session in your personal journal.
#### Online Game Master
If you have an account and are connected to a valid SessionZero server, you can host an online session and invite others to join you. Set a character sheet template for players to use when creating their characters, manage session data, provide real-time updates to characters, use in-game chat and commands, manage turn order, and more.
### SessionZeroDB
SessionZeroDB is an online repository of user-created SZF data that can be downloaded. When enabled, SessionZero can automatically download dependencies from SessionZeroDB (if they exist).
### SZF
SessionZero uses a custom data format called SZF (SessionZero Format) for all of the data types mentioned previously. This specification is made to be more easily human readable with less clutter, easy syntax, and overall smaller file size. Read the [https://sessionzero.app/szf-docs.html](SZF Docs) for more information.
## Philosophy
### Free
SessionZero is FREE. No account or subscription fees required for the entire application.
### Open Source
SessionZero is first and foremost open-source software. We believe in the right of knowing whats going on behind the scenes.
### Offline first
By default SessionZero works completely offline. Your data is stored locally, on your machine. No account required. No phoning home. You only need an account when accessing online features (Such as hosting a session).
### No BS
No AI chatbots, no ads, no bloat. We promise.
## Online Accounts & Server Connections
All SessionZero accounts are created and managed on the official SessionZero servers, which is always free.
For hosting and playing in online game sessions, the application lets you choose which server to connect to. This is where the self-host option comes in:
* **Self-Hosted Server (Free):** Host our open-source server backend yourself. This allows you to create and join online sessions without a subscription.
* **Official Session Servers (Subscription):** For convenience, connect to the official SessionZero servers. Access for hosting and joining sessions requires a monthly subscription.
## Technical Details
- Client: Avalonia C#
- Server: ASP.NET, PostgreSQL