matanlurey / tts-expander

Expands and collapses the save-file format for Tabletop Simulator

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

tts-expander

Node.js CI

Node.js library for expanding and collapsing the save-file format for Tabletop Simulator.

The goals of this library are:

  • Avoid storing a giant monolothic JSON blob in version control (i.e. GitHub).
  • Ease collaboration and code reviews of changes.
  • Make it easier to hand-edit files/properties/scripts when desired.
  • Allow the development of more advanced editors and tooling for modding.

NOTE: As of 0.2.0, the require('...') function is used over #include.

API

import * as expander from 'tts-expander';

// Use the library!

.splitObject

const tree = expander.splitObject(/*ObjectState*/ object);

Converts an ObjectState into an intermediate object called a SplitObjectState - which is a tree-like structure that represents all of the metadata, children, and their metadata and children.

.splitSave

const tree = expander.splitSave(/*ObjectState*/ save);

Converts an SaveState into an intermediate object called a SplitSaveState - which is a tree-like structure that represents all of the metadata, children, and their metadata and children.

A SplitSaveState can then be provded to SplitIO.

SplitIO

A class that handles reading and writing metadata to disk.

.readSaveAndSplit

const io = new expander.SplitIO();
const tree = await io.readSaveAndSplit(pathToSaveFile);

Returns a SplitSaveState object.

.writeSplit

const io = new expander.SplitIO();
await io.writeSplit(pathToDirectory, splitSaveState);

Writes a SplitSaveState as a tree-based directory structure of files.

.readAndCollapse

const io = new expander.SplitIO();
const save = await io.readAndCollapse(pathToDirectory);

Reads a tree-based directory structure of files, collapsing into a SaveState.

Schema

tts-expander uses the @matanlurey/tts-save-format package in order to parse and validate the Tabletop Simulator save file format, and introduces two new meta schemas: ExpandedObjectState and ExpandedSaveState

ExpandedObjectState

Represents an ObjectState that has had all scripting, user-interface XML, children, and alternative states "expanded" (and subsequently removed from the metadata). To be able to piece this object back together into an ObjectState you would need to load additional files and inline them back into the original metadata.

{
  "Object": {
    "Name": "Block",
    "GUID": "abcdef",
    // ...
    // Scripts and XML is changed to an #include reference to another file.
    "LuaScript": "#include Block.lua",
    "XmlUI": "#include Block.xml",
    // ...
    // Rest of the metadata.
    // Notably `ContainedObjects` and `States` has been purged.
   },
  "ContainedObjectPaths": [
    // Files that contain the metadata for ContainedObjects.
    "Object-1.json",
    "Object-2.json",
    // ...
  ],
  "StatesPaths": {
    // Files that contain the metadata for States.
    "1": "State-1.json",
    "2": "State-2.json",
    // ...
  }
}

ExpandedSaveState

Similarly, ExpandedSaveState references a SaveState.

{
  "Save": {
    "Name": "Game",
    // ...
    // Scripts and XML is changed to an #include reference to another file.
    "LuaScript": "#include Game.lua",
    "XmlUI": "#include Game.xml",
    // ...
    // Rest of the metadata.
    // Notably `ContainedObjects` and `States` has been purged.
   },
  "ObjectStates": [
    // Files that contain the metadata for ContainedObjects.
    "Object-1.json",
    "Object-2.json",
    ...
  ]
}

About

Expands and collapses the save-file format for Tabletop Simulator


Languages

Language:TypeScript 99.8%Language:JavaScript 0.1%Language:Lua 0.0%