SessionZeroWasm/szf-documentation.md

Session Zero Format (.szf) Documentation

Overview

The Session Zero Format (.szf) is a human-readable, structured data format designed specifically for the Session Zero tabletop RPG management application. It provides a standardized way to represent game data, templates, and character sheets for offline storage, interchange, and sharing.

Format Principles

• Human-Readable: Content is stored in plain text with a clear, consistent structure
• Self-Documenting: Field types and metadata are explicitly defined
• Extensible: Format supports future expansion without breaking compatibility
• Portable: Files can be easily shared and imported across devices
• Compact: Efficient representation without unnecessary verbosity

File Structure

All .szf files follow a common structure:

1. Header: Identifies the file type and schema version
2. Metadata: Contains descriptive information about the content
3. Content Sections: Contains the actual data organized in logical sections

Header Format

Files begin with type declaration and schema version:

!type: [file_type]
!schema: [schema_version]

Where [file_type] can be:

• dataset - Collection of related game elements
• character_template - Character sheet definition
• character - Actual character data
• session - Game session data

And [schema_version] follows semantic versioning (e.g., 1.0.0).

Section Format

Data is organized into named sections with optional nesting:

[Section: Name]
FieldName (field_type) = value

[Section.SubsectionName]
FieldName (field_type) = value

For entries in datasets, the format is:

[Entry: EntryName]
FieldName (field_type) = value

[Entry.EntryName.SubsectionName]
FieldName (field_type) = value

Field Types

The .szf format supports the following field types:

Type	Description	Example
text	Single-line string	Name (text) = Longsword
text-field	Multi-line text	Description (text-field) = A long sword...
number	Integer or floating-point	Weight (number) = 3
bool	Boolean true/false	IsMartial (bool) = true
group	Container for related fields	Currency (group) = true
calculated	Formula-based computed value	StrengthMod (calculated) = (Strength - 10) / 2
system	Special application-handled field	DatasetType (system) = items
dataset-reference	Reference to specific dataset	Race (dataset-reference) = PlayableRaces
dataset-type	Reference to any dataset of type	PrimaryWeapon (dataset-type) = items
dataset-reference-multiple	Multiple references to specific dataset	Feats (dataset-reference-multiple) = CoreFeats
dataset-type-multiple	Multiple references to dataset type	Level1Spells (dataset-type-multiple) = spells

Dataset Format

Datasets contain collections of related game elements like items, spells, or character classes.

Example

!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

Character Template Format

Templates define the structure of character sheets, including fields, calculations, and dataset references.

Example

!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: 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

Special Features

Dataset Dependencies

Character templates can specify required datasets using the Name|GUID|Version triple format:

[Required Datasets]
ClassesDataset (text) = Core Classes|c3d4e5f6-g7h8-9012-cdef-123456789012|1.5.0

This ensures that character sheets created from the template have access to the correct datasets.

Calculated Fields

Formulas can reference other fields to create dynamic values:

StrengthMod (calculated) = (Strength - 10) / 2
SpellSaveDC (calculated) = 8 + ProficiencyBonus + IntelligenceMod

Supported operations include basic arithmetic, comparisons, and functions like SUM, MIN, MAX.

Nested Sections

Sections can be nested to create a logical hierarchy:

[Section: Equipment]
DatasetType (system) = items

[Section.Equipment.Weapons]
PrimaryWeapon (dataset-type) = items

System Properties

Special fields that control application behavior:

DatasetType (system) = items
SelectionMode (system) = multiple

Best Practices

1. Use Descriptive Names: Choose clear, meaningful section and field names
2. Include Metadata: Always provide version, description, and author information
3. Organize Logically: Group related fields into appropriate sections
4. Set Defaults: Provide sensible default values where appropriate
5. Document Dependencies: List all required datasets with their correct identifiers
6. Validate Before Sharing: Ensure all references are valid and values are appropriate
7. Follow Naming Conventions: Use consistent capitalization and naming patterns

Import/Export Guidelines

Exporting

When exporting .szf files:

1. Include all required metadata (especially GUID and version)
2. List all dependencies explicitly
3. Keep file sizes reasonable (prefer multiple focused files over single massive ones)
4. Set appropriate default values

Importing

When importing .szf files:

1. Validate the file structure before processing
2. Check for missing dependencies
3. Handle version conflicts appropriately
4. Validate all field values against their declared types

Character Sheet Data

When a character is created from a template, the resulting .szf file contains:

1. Reference to the source template (GUID and version)
2. All field values populated by the user
3. References to selected dataset entries
4. Character-specific notes and customizations

Versioning and Compatibility

• GUID: Unique identifier that remains constant across versions
• Version: Semantic version number (MAJOR.MINOR.PATCH)
• Compatibility: Minor versions should maintain backward compatibility
• Breaking Changes: Major version increases indicate potentially incompatible changes

Common Use Cases

1. Sharing Game Systems: Distribute templates and datasets for specific RPG systems
2. Character Backups: Export characters for safekeeping or transfer between devices
3. Community Content: Share custom content with other Session Zero users
4. Game Preparation: Pre-build NPCs, items, and other game elements