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

Updates to sessionzero resources

Browse Source
This commit is contained in:
Chris Bell
2026-04-07 21:58:12 -05:00
parent 57524f5af7
commit bac8ed6af9
5 changed files with 944 additions and 388 deletions
Download Patch File Download Diff File Expand all files Collapse all files

184
design-doc.md
View File

@@ -1,95 +1,149 @@
# SessionZero Design Doc
***© Bellsworne LLC 2025***
# SessionZero Design Doc `WIP`
***Last modified by Christopher Bell on July 14th 2025***
## Overview
SessionZero is designed to be a supplimentary companion app for TTRPG games, both in-person and digital. The core of the system revolves around it's fully data-driven system that uses solely user-generated content, therefore there is no storefront for officially licensed material or systems, and can be used for ANY game system.
## About SessionZero
## Definitions:
- **Game**: A Game is the core of all game sessions, housing all of the game and player data.
- **Game Template**: A template for a Game containing ***Datapacks***, ***Modules***, and other metadata.
- **Datapack**: A Datapack is a collection of related ***Datasets***, ***Templates***, used to serve a ***Game*** with data.
- **Dataset**: A collection of ***SZ Objects*** and associated resource files (images, etc).
- **SZ Object Template**: A template used to define an ***SZ Object***, like a blueprint, holding a set of fields and their expected value type, as well as allowing fields that can be populated by other ***SZ Objects*** of a defined type/template.
- **SZ Object**: An "instanced" data object that holds a set of fields and values of various types, defined by an ***SZObjectTemplate***.
- **Game Character Template**: A special ***SZ Object Template*** for a ***Game Character***, specifying the fields and value type, and serving as the main source of truth for a ***Game***, acting like a "Player Sheet".
- **Game Character**: A special **SZ Object** instance defined by a ***Game Character Template***.
- **The Archives**: A database of user-generated-content where users can upload or download data for games.
- **Module**: A module is akin to a plugin or game modification, and contains application logic/functionality, UI, etc, and can be created and shared by anyone.
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.
## Features
## Game
A 'Game' is the core part of the application. It contains the Character Template and any data needed for the chosen game, as well as all individual player data and session data. These can be ran offline or in an online game session as either the Game Master or just a player. Games also have a built in chat where you can run commands or chat with other players (These chats are not encrypted in any way and are stored in the game's save data).
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.
### Play-by-Post `WIP`
A special online-only Game type where gameplay is conducted asyncronously by each player ***`More details are needed for this Game type`***.
### Data Types
## Client and Server relation
The core application is designed to be ran locally with no internet connection or account required. This mainly includes managing offline Games utilizing the data-creation tools, and any other capability provided by Modules.
The client allows you to Create, View, Manage, Import & Export, and even Download various data types:
For online games, you connect to the server that is hosting that particular game, and create/use a profile unique to that specific game. This hosting capabilty comes in three forms, a self-hostable dedicated server, a temporary server ran on the host machine (requires port forwarding and sharing of personal IP address, or alternatively a VPN), or using the official SessionZero server (limited availibily, more details need to be added for possible pricing or if this is even feasible).
#### 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.
For downloading Datapacks, Game Templates, Modules, etc, 'The Archives' is a source of repositories of user-generated data where you can download or share (if you have permission). You can add or remove repository sources within the application.
#### Characters
Characters are made up of two parts: The **Template** and the **Character instance**.
## Modules `WIP`
##### 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.
## Data `WIP`
### TODO
- How do we redefine the data structure to better handle a dependency tree down the line.
- Dot (.) Notation should be the way to access items within a dataset (ex. `SessionZero.szcore-test-items.test-item` would grab the 'test-item' SZ Object from the 'SessionZero.szcore-test-items' dataset)
- Excluding SZ Object instances, all unique id fields must be prefixed with an author name (ex. `SessionZero.szcore-game-template`, where 'SessionZero' is the author, and 'szcore-game-template' is the rest of the unique id)
##### 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.
> <span style="color:red">All of the following examples are psuedocode and not final</span>
### Game Sessions
### Game Template
```ini
[metadata]
id = SessionZero.szcore-game
name = SessionZero Core Game Template
author = SessionZero Team
description = '''
SessionZero Core Game Template
'''
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.
# TODO: figure out how to list dependencies of datapacks, templates, and modules
[datapacks]
[templates]
[modules]
```
### Game Object
```json
The application supports several modes:
```
#### 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.
### Datapack
```ini
# Proposed metadata for a Datapack
#### 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.
[metadata]
id = SessionZero.szcore-datapack
name = Test Datapack
author = SessionZero Team
description = '''
SessionZero Test Datapack
'''
# TODO: reference to datasets and templates
```
#### 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.
### Dataset
### SessionZeroDB
```ini
# Proposed metadata for a Dataset
SessionZeroDB is an online repository of user-created SZF data. When enabled, the application can automatically find and download required datasets and templates.
[metadata]
id = SessionZero.szcore-test-items
name = Test Items Dataset
# The template ID to use for SZ Object instances
template-id = szcore-item
# Must match the template datatype
datatype = item
author = SessionZero Team
description = '''
SessionZero Test Dataset
'''
```
### SZF (SessionZero Format)
### Sz Object Template
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).
```ini
# Psuedocode for the structure of an SZ Object Template
## Philosophy
# TODO: Finish examples of using dependencies and formulas and lists
### Free
SessionZero is **FREE**. No account or subscription fees are required for the core application.
[metadata]
id = SessionZero.szcore-item
name = SzCore Item
# This is an arbitrary value and can be anything (ex. item, npc, weapon, etc.)
datatype = item
author = SessionZero Team
description = '''
SessionZero Core Item Template
'''
# Can also have any custom metadata
### Open Source
SessionZero is first and foremost **open-source software**. We believe in the right to see what's going on behind the scenes.
# This is a top-level field
[name]
# This denotes the field's type (text, number, boolean, formula, reference)
type = text
### Offline-First
By default, SessionZero works **completely offline**. Your data is stored locally on your machine. No account required. No phoning home.
# This is a field in a "Group"
[stats.damage]
type = number
# An optional default value
default = 10
### No BS
No AI chatbots, no ads, no bloat. We promise.
[example]
type = reference
# Denotes that this value is a list of values of the designated type
is-list = true
# A special thing for reference types to specify what 'datatype' is allowed
reference-type = item
# Makes the reference only allowed to be an instance of the specified template
reference-type-template = szcore-item
```
## Online Accounts & Server Connections
### SZ Object Instance
All SessionZero accounts are created and managed on the official SessionZero servers, which is always free.
The id field in an SZ Object instance does not need an additional prefix like templates and other abojects, as it will assume the author prefix from the dataset that contains the SZ Object (an SZ Object cannot stand alone, it must be a part of a dataset)
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:
```json
{
"metadata": {
"id": "test-item",
"name": "Test Item",
"template-id": "SessionZero.szcore-item",
"datatype": "item",
"author": "SessionZero Team",
"description": "A test item",
},
* **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
}
```