SessionZero

A free and open‑source, system‑agnostic TTRPG companion app. SessionZero helps you create, manage, and share tabletop content using an extensible JSON datapack format. It supports fully offline use, and is designed to be self‑hostable with future federation capabilities.

At a glance

• Cross‑platform desktop client (Avalonia, .NET 9)
• Lightweight ASP.NET server for shared play and sync
• JSON datapacks for datasets, character templates, and session templates
• Offline‑first; self‑hostable; roadmap includes federation and mobile

For a deep dive into goals, architecture, and data formats, see docs/design-doc.md.

Repository layout

• SessionZero.sln – Solution file
• docs/
  • design-doc.md – Full design overview and datapack specification
  • rambling.md – Notes and ideas
• src/
  • SessionZero.Client/ – Avalonia desktop application
  • SessionZero.Server/ – ASP.NET Core server (minimal API)
  • SessionZero.Shared/ – Shared models and schema abstractions used by both client and server
• samples/ – Placeholder for sample datapacks (.szp) and source folders
• tools/ – Project tooling stubs
• license.txt – AGPL‑3.0 license text

Technology stack

• Language/Runtime: C# on .NET 9.0
• UI: Avalonia (cross‑platform desktop)
• Web/Server: ASP.NET Core minimal API, WebSockets planned for real‑time
• Data: JSON datapacks for content; PostgreSQL planned for shared online content

Core concepts (from the design)

• Datapack: Top‑level container (.szp) bundling datasets, templates, and media
• Dataset: Structured records (e.g., items, NPCs). See src/SessionZero.Shared/Models/Dataset.cs
• Template: Reusable structures for characters or sessions
  • CharacterTemplate: src/SessionZero.Shared/Models/CharacterTemplate.cs
  • SessionTemplate: src/SessionZero.Shared/Models/SessionTemplate.cs
• Schema: Versioned JSON schema ideas captured in docs and src/SessionZero.Shared/Schema/Schema.cs

Read the full specification and examples (including JSON snippets) in docs/design-doc.md, Section 5.

Datapack basics

A datapack directory typically looks like this:

pack-name/
├── szpack.json                 # Pack metadata and manifest
├── media/
│   └── images/                 # Image assets (referenced by objects)
└── objects/
    ├── datasets/               # User-defined structured data (e.g. items, NPCs)
    ├── character-templates/    # Templates defining character structures
    └── session-templates/      # Templates defining session/campaign structures

Examples of szpack.json, datasets, character templates, and session templates are provided in docs/design-doc.md (sections 5.2–5.7). The shared C# models in src/SessionZero.Shared mirror these structures.

Getting started

Prerequisites

• .NET SDK 9.0 or later
• A desktop OS supported by Avalonia (Windows, Linux). Mac may work but is not yet a target.

Build the solution

From the repository root:

dotnet build SessionZero.sln

Run the desktop client

dotnet run --project src/SessionZero.Client

This launches the Avalonia app.

Run the server (optional for local/offline; required for shared play)

dotnet run --project src/SessionZero.Server

The server uses ASP.NET Core default settings and appsettings files under src/SessionZero.Server. Future iterations will add persistence and WebSocket real‑time updates.

Using datapacks

• Place or import datapacks (.szp) through the client (UI flows under active development).
• For development and testing, keep source folders that match the structure above, then pack/export to .szp.
• Sample content: see samples/ (placeholder today). The design document shows complete JSON examples you can adapt.

Self-hosting and future federation

SessionZero is designed to be self-hostable from day one, with a clear roadmap toward optional federation of independently run servers.

Self-hosted server (today)

• Self-hosted by design: run the SessionZero server locally or on your own VPS; no central service is required to play with friends you invite. The desktop client works fully offline; the server is only needed for shared play and sync.
• Data ownership: datapacks and saves live on your disk. For online/shared play, your own server holds your data. Planned persistence for the server is PostgreSQL; early builds may use in-memory or file-backed storage.
• How to self-host (early stage):
  1. Run the server: dotnet run --project src/SessionZero.Server
  2. Expose it on your LAN or behind a reverse proxy (e.g., Nginx/Caddy) with TLS.
  3. Configure appsettings.json under src/SessionZero.Server for host/ports and, when available, database connection strings.
  4. Point clients to your server URL (UI setting to be added; defaults are http://localhost).
• Security and licensing notes:
  • Use HTTPS when exposing publicly; prefer a reverse proxy and strong auth when available.
  • The code is AGPL-3.0: if you modify and run a public instance, you must make the modified source available to its users.

Federation (future/Phase 2)

• Goal: independent servers discover and share public content (datapacks, datasets, templates) across a trust network.
• Identity: users have global IDs; datapacks are identified by UUID.
• Discovery and sharing: opt-in directories/search; servers fetch and cache public content from peers you trust.
• Permissions and privacy: private games stay private; only content you mark public is advertised.
• Interop and versioning: content references remain stable across servers via IDs and versions.

See docs/design-doc.md, Section 7 for more architectural detail.

Roadmap (high level)

• Phase 1: Core Platform (client UI, server scaffolding, datapack format)
• Phase 2: Federation (cross‑server discovery and sharing)
• Phase 3: Mobile and Plugins (broader platform support and extensibility)

Details for each phase are in docs/design-doc.md, Section 9.

Contributing

Contributions are welcome! Suggested ways to help:

• Try building/running the client and server; report issues and UX rough edges.
• Create example datapacks that exercise datasets and templates.
• Discuss schemas and validation approaches (see docs/design-doc.md, Section 5.8).

Before submitting a PR, please ensure the solution builds with .NET 9.0. Tests and CI will be added as the project matures.

License

Source code is licensed under the GNU Affero General Public License v3.0 (AGPL‑3.0). See license.txt.

User‑generated content is intended to be shareable under Creative Commons BY‑SA 4.0; see docs/design-doc.md, Section 8.2, for the rationale.