Extract

Extracting a save file splits it into a nested directory structure. Each folder contains the information for one object (or Global). It contains different files per object, depending on what attributes it has (listed in the sections below). The files all have the same name, they are discriminated by the directory they are part of.

The data from Global will be on the top level of the output directory. From there the directory Contents contains the globally available objects. Object directories are named by using their nickname (the applied name that is also visible in the TTS tooltip), followed by a dot and their GUID. If the object doesn’t have nickname, their internal name is used instead. If the object is a container (a bag or deck), it’s content is again nested inside the Contents directory. The same applies for states

This process will create a directory structure like this:

<output-path>
├─ Data.json
├─ Contents.json
├─ Script.ttslua
├─ State.txt
├─ UI.xml
├─ Contents -- since this is Global, this contains all global objects
│ ├─ Bag.abc123
| | ├─ Contents.json
| | ├─ Data.json
| │ ├─ Script.ttslua
| | ├─ State.txt
| | ├─ States.json
| | ├─ UI.xml
| | ├─ Contents -- this object is a container, so this contains the contained objects
| | | ├─ CoolFigure.123456
| | ├─ States -- when the object is stated, the states are kept here
| | | ├─ 2-OtherBag.123456
| | | ├─ 3-MoreOtherBag.111111
│ ├─ HandTrigger.123abc

Options

The Api offers several options

Name Type Required Description

output

string

Yes

The path where the save file will be extracted to.

normalize

boolean/number

No

If set, floating point values will be rounded to the 4th decimal point. When a number is given instead of a boolean, the values will be rounded to that decimal point instead.

withState

boolean

No

If set, the script states of objects will also be extracted. Otherwise, they will be ignored, effectively clearing the state of all objects.

contentsPath

string

No

Name of the directory for a container object or the global table where each contained object will be written to. Defaults to no name, meaning objects are extracted directly into their container directory.

statesPath

string

No

Name of the directory for an object with multiple states where each state will be written to. Defaults to no name, meaning states are extracted directly into their object’s directory.

childrenPath

string

No

Name of the directory for an object with attachments where each attachment will be written to. Defaults to no name, meaning attachments are extracted directly into their object’s directory.

keyOrder

string[]

No

A list of names for fields in an object’s data. When set the keys in each Data.json file will be sorted by this order. Each field not listed will be sorted alphabetically after each listed field was sorted accordinly.

E.g. an object data like this:

{
  "GUID": "12356",
  "Name": "Custom_Token",
  "CustomImage": {
    "CustomToken": {
      "StandUp": false,
      "Stackable": false,
      "Thickness": 0.1,
      "MergeDistancePixels": 15.0001
    },
    "ImageSecondaryURL": "..",
    "ImageURL": "..."
  },
  "Nickname": "Test"
}

with a keyOrder option ["GUID", "Name", "Nickname", "ImageURL", "ImageSecondaryURL"], would create a Data.json file like this:

{
  "GUID": "12356",
  "Name": "Custom_Token",
  "Nickname": "Test",
  "CustomImage": {
    "ImageURL": "...",
    "ImageSecondaryURL": "..",
    "CustomToken": {
      "MergeDistancePixels": 15.0001,
      "Stackable": false,
      "StandUp": false,
      "Thickness": 0.1
    }
  }
}

Files

The following files are created while extracting (when applicable).

Script.ttslua

This file contains the Lua script attached to the object (or Global). If the script contains require() calls, it will be unbundled, so that only the root module will be written to the file. E.g. this is the same behavior seen in the TTS editor plugins, so that only the relevant code is written to the file.

NOTE

This tool does not (and does not intend to) support the use of the #include directive that is available in the Atom TTS plugin. Please use require() instead.

UI.xml

This file contains the XML UI attached to the object (or Global). Like the script it will be unbundled, so it contains the <Include src="" /> directives from the original code similar to the behavior from the Atom TTS plugin.

State.txt

This file contains the script state of the object (or Global).

Data.json

This file contains the data from the original save file for this object (or Global). Fields that where extracted (e.g. the Lua script or XML UI), will be empty and not included in the file. Adding contents to those fields will be ignored as their contents is solely driven by the available files for this object.

Contents.json

This file keeps the order of contained elements within a container or the globally available objects in case of Global. It contains a simple array with the relative path to the object within the Contents directory.

States.json

This file keeps the order of states of an object. It contains a simple array with the relative path to the object within the States directory.