tts-expander
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",
...
]
}