sessionzero/szds.md

SessionZero Data System

Layout

Data is separated into 3 main chunks: systems, games, and datasets. Each of these work together but hold varying information.

The flow goes as such:

1. Create a System i. Define a character template ii. Define data templates
2. Create a Dataset i. Reference an existing system for available templates ii. Create data instances based on the available templates
3. Create a Game i. 'Install' an existing system ii. 'Install' various datasets that use the same system iii. Install plugins (future feature) iv. Create a character from the system template

File Specifications

Namespaces and IDs

There are 4 "namespaces" in the sz data pipeline: author, system, dataset, and 'template group' (working name, but essentially is the data type, which are grouped by folders in a dataset), in that order.

Namespaces are accessed with a trailing :, ex. the 'szcore' system, made by 'sz', would be sz:szcore.

All .sz, .szt, and .szo files are given IDs based on the file name when loaded into the local database, and must be unique to their scope.

For instance, a data template in the szcore system with the file name item.szt will be identified as szcore:item.

And a data instance in a dataset called data with the name item/coin.szo (with the item template, designated by the folder name) will be identified in the database as sz:szcore:data:item:coin.

Top level .sz files (system.sz, dataset.sz, and game.sz) are identified by the parent folder, for instance a system named sz.szcore/ will be identified as sz:szcore.

Fields

A field is found within a data object, defined by a template.

---

System

Holds:

• Character Template
• Data templates

Example Directory Structure:

author.system_name/
- system.sz
- icon.png
- character_template.szt 
- templates/
	- weapon.szt

Example system.sz file

id = "szcore"
display_name = "SZ Core System"
version = "1.0"
author = "sz"
description = """
	A simple core system to base others off of
"""

Example character_template.szt file

template_type = "character"
author = "sz"

[fields.name]
type = "text"
required = true
default_value = "Character 1"

[fields.player_name]
type = "text"
required = false

[fields.level]
type = "number"
required = true
default_value = 1

[fields.race]
type = "option"
required = true
option_type = "data"
data_source = ["races"] 

[fields.class]
type = "option"
option_type = "text"
data_source = ["ranger", "fighter", "wizard"]
required = true

[fields.status.is_dead]
type = "boolean"
required = true
default_value = false

[fields.stats.str]
type = "number"
required = true
default_value = 0

[fields.stats.modifiers.str]
type = "formula"
formula = '(stats.str - 10) / 2'

[fields.inventory]
type = "list" #
list_type = "data" # If a list type is `data` then the list_data_source becomes a list of data sources in which the list can pull from, otherwise you can use `number` or `text` for literal values
data_source = ["items", "weapons"] 

[fields.spells]
type = "list"
list_type = "text"
data_source = ["fireball", "mage_hand"]

[fields.equipped_weapon]
type = "option"
option_type = "data"
data_source = ["weapons"]

[fields.stats.damage]
type = "formula"
formula = 'equipped_weapon.calculated_damage'

Example data template file weapon.szt:

# The data type eg. "item" is pulled from the file name, and can be anything
template_type = "data"
author = "sz"

[fields.id]
type = "text"
required = true

[fields.display_name]
type = "text"
required = true

[fields.value]
type = "number"
required = true
default_value = 1.0

[fields.base_damage]
type = "number"
required = true
default_value = 1.0

[fields.skill]
type = "text"
required = true
default_value = "str"

[fields.calculated_damage]
type = "formula"
formula = 'base_damage + $PLAYER.stats.modifiers.{skill}' 
# TODO: Need to figure out the syntax for this; 
# $PLAYER should be a special variable that gets the current character of the owning player within a session,
# and the local `skill` variable needs to be evaluated as a string value (so it will look for `$PLAYER.stats.modifiers.str` as a number).
# Not sure about the {} as the syntax though, maybe I should rework the formula type entirely

---

Datasets

Holds:

• Reference to a System and its templates
• Data Instance

Example Directory structure

author.dataset_name/
- dataset.sz
- icons/
    - dataset.png
    - weapon/
        - sword.png
- data/
    - weapon/
        - sword.szo

Example dataset.sz file

id = "szcore_data"
system_id = "szcore"
author = "sz"

Example data instance file sword.szo (this would use the szcore.weapon template from the system defined in the dataset)

author = "sz"

[fields.id]
value = "sword"

[fields.display_name]
value = "Sword"

[fields.value]
value = "100"

[fields.base_damage]
value = 10

[fields.skill]
value = "str"

# This field is calculated based on the template and its value will change automatically when recalculated
[fields.calculated_damage]
value = "10"

---

Games

The Game type glues everything together.

Holds:

• System
• Plugins
• Datasets
• Player Data
  • Character Instances
• Gamestate/Data

Example directory structure:

game_name/
- game.sz
- plugins/
    - (plugins will be defined in the future)
- datasets/
- player_data/
    - player_name/
        - player.sz
        - characters/
            - character1.szo   // An actual Character instance using the System's template
- game_data/
    - (various game related data...)

Example game.sz file