Adding 'data.md'

2025-11-29 23:23:04 -06:00
parent 7c98bc3a89
commit b1a43d038e
1 changed files with 131 additions and 0 deletions
--- a/SessionZero/data.md
+++ b/SessionZero/data.md
@@ -0,0 +1,131 @@
+# SessionZero Data
+
+## Datapack
+
+Datapacks contain multiple Datasets as well as their DatasetObject Template files and other resource files
+
+### Datapack Archive File Structure
+```text
+datapack_name/
+├─ resources/
+│  ├─ images/
+│  ├─ audio/
+├─ datasets/
+│  ├─ dataset_name/
+│  │  ├─ objects/
+│  │  │  ├─ object_name.szo
+│  │  ├─ dataset.meta
+├─ templates/
+│  ├─ template_name.sztl
+├─ datapack.meta
+├─ README.md
+├─ icon.png
+```
+
+### `datapack.meta` file
+```json
+{
+    "name": "SessionZero Core",
+    "id": "sz_core",
+    "uuid": "95c6d3c9-3213-4256-b3db-b004d0fb95b7",
+    "version": "1.0.0",
+    "compatible_systems": "sz_core, d20",
+    "description": "SessionZero Core Datapack"
+}
+```
+
+## Dataset Metadata (`dataset.meta`) File Definition
+
+- The `id` field MUST be unique from other datasets listed withing the containing datapack
+- `dataset_type` is an arbitrary string that is used to identify what the general "type" of data the dataset contains
+- `object_template` is the template definition used for creating dataset objects. It must be present in the parent datapack's `templates/` directory
+
+```json
+{
+    "name": "SessionZero Core Items",
+    "id": "core_items",
+    "icon": "icons/items_icon",
+    "description": "A set of simple items",
+    "dataset_type": "item",
+    "object_template": "core_item"
+}
+```
+
+## DatasetObject Template File
+
+- Metadata fields are denoted with a `!` and are required for this template:
+    - `data_type` is an arbitrary value used to denote what kind of dataset type the template is for.
+    - The `uuid` field can be left at 0, but when uploading to the SessionZeroDB a uuid will be assigned.
+    - The `id` must be unique within the datapack
+    - `compatible_systems` is arbitrary and only reflects if the template can be used in a datapack according to it's `compatible_systems` value
+- Some default fields are required by the default parser:
+    - `name: text` must be present
+
+```ini
+!id = "core_item"
+!uuid = 0
+!version = "1.0.0"
+!data_type = "item"
+!compatible_systems = "sz_core, d20"
+!description = """
+Core SessionZero item template
+"""
+
+
+# Top-level fields
+name: text
+description: textblock
+
+# Example of a group
+stats {
+    value: number
+    weight: number
+
+    # Example of a sub-group
+    modifiers {
+        
+        # Field with a default value
+        base: number = 1
+    }
+}
+
+```
+
+## DatasetObject object (.szo file)
+
+An instanced DatasetObject should only contain simple fields and values, no object references or formulas
+
+```json
+{
+    "id": "some_id",
+    "uuid": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
+    "name": "Human readable name",
+    "template_id": "some_template_id",
+    "parent_dataset_id": "some_dataset_id",
+    "description": "A description",
+    "icon": "path/to/icon",
+    "compatible_systems": ["sz_core", "d20"],
+    "fields": {
+        "groups": [
+            {
+                "id": "group_name",
+                "fields": [
+                    {
+                        "id": "field_name",
+                        "type": "number",
+                        "value": 1
+                    }
+                ],
+                "sub_groups": []
+            }
+        ],
+        "top_level_fields": [
+            {
+                "id": "name",
+                "type": "string",
+                "value": "something"
+            }
+        ]
+    }
+}
+```