The Tool Context & Telltale Editor
The starting point for functionality internally.
As described in the GitHub how it works page, this is split into two sub-projects. The Tool Context is the main class which is instantiated once by the user of the library. See the codebase file information page for where everything is and what exactly is in the codebase.
Game Snapshots
The first concept is a game snapshot. Telltale released many many games amongst many different platforms. To manage this, each game snapshot pretty much corresponds to exactly one game executable (.exe/.app/.xex etc) in which the file format (ie classes) are constant and don't change as the executable is static and never changes even with patches.
A game snapshot is simply comprised of the game ID, platform name and vendor. The vendor is used when there are multiple releases of the game which differ, or different revisions which sometimes rarely occurred. For each game ID, there are a unique set of platforms and vendors allowed (and combinations of these). These are all specified in each game script. For example, see one of the first Telltale game's script here, in the get descriptor function. Below that is all the code registering the high level class reflection system (Meta) information and members. Read on for more information.
Task System
The Telltale Editor is designed with simplicity and speed in mind. All work is divided into tasks. Tasks generally work on one file at a time and are typically one of 4 categories:
Write Serialisation,
Read Serialisation,
Normalisation,
Specialisation.
Although there are many other tasks (such as resource extraction) these 4 are the main ones. The API is designed to let you enqueue these tasks and then wait for them to complete. All the tasks are executed in parallel (async) but are all fundamentally thread safe. This is done by you periodically calling an update function on the main thread (hopefully along with thread sleeps). All heavy CPU work is performed asynchronously in a thread safe context. Once the heavy workload is finished, the output of that task is moved into the output object you specified, on the main thread. Any data changed on your side between the task being enqueued and it finishing will be overridden when the task finishes on the main thread (in a call to Update, see below).
The four categories of tasks above will be explained further below.
Using the Editor Context
The Tool Context can be found here. This is the interface to the lower level part of the library. Generally, you will be using the Telltale Editor class which is part of the Editor sub-project, which acts as a wrapper around this.
Only one tool context is ever present at a time, just like the higher level Editor context (Telltale Editor class). This tool context class manages the Lua virtual machine (VM) and the meta system and active game snapshot management. It loads the Lua scripts and registers all game information and game classes which allow for files to be read and written to.
As said earlier, it is always suggested to use API with the Telltale Editor class found here. Only one instance of this class should ever be present, and it should be created with functions CreateEditorContext and subsequently freed using FreeEditorContext .
Within this class the following functionality is provided:
Switch(snapshot)
Switches to a new game snapshot. This is already done when you create the editor context as well. All snapshot dependent objects (SDOs) [read on for information about these] must be destroyed before calling this. This will completely unload everything and reload for the given new snapshot, calling the Lua script to register all the classes for the new snapshot.
Update()
Periodic update. Most of the functionality of this class and TTE in general is done asynchronously. If you are waiting on loads of tasks to complete (such as reading files) then you should loop calling this (sleeping every so often to reduce CPU load of course).
ContextIsBusy()
Returns if the current Telltale Editor context is busy. This means that there are blocking asynchronous tasks that are executing. Most tasks are not blocking, meaning this will return false. If a task is blocking it will be specified as in the documentation. You will not be able to access the context while its busy.
Wait()
This simply waits, safely, for all blocking jobs to complete. Like all, only call on the main thread.
QueryTask(taskID)
Queries if the given task ID (returned to you in an Enqueue task function) has completed yet.
EnqueueNormaliseXXXTask
Enqueues an asynchronous task to normalise the given meta instance into the common instance. The common instance (eg Scene or Mesh) passed in here is safe to edit after this call but it will be overridden (by the new data) possibly if you call any other functionality part of this class. XXX is the common class name, for example Mesh, Scene, Dialog or Chore. For more information, see the common classes page.
EnqueueArchiveExtractTask
Enqueues a task to extract the given archive to an output folder on disk. Pass in the loaded archive and the file list to extract. Pass in an empty set of file names to extract all files.
EnqueueResourceLocationExtractTask
Enqueues a task to extract all files matching the given input string mask (file name filter) from the given resource location. This will extract all files into the output folder provided. This is useful for checking which files are part of the given resource logical location, such as <Project> or <ItalianSeason2> for examples.
CreateResourceRegistry
This creates a resource registry (example of an SDO) and returns it. Generally, you want to keep the number of these instances to a minimum, but you can have as many as you like. They represent a resource system instance which can be used to find, save and load files along with use the Scripting system's Resource API with.
Snapshot Dependent Objects (SDOs)
Some classes in the Telltale Editor are not allowed to be used across multiple game snapshots, i.e. they cannot be used across calls to TelltaleEditor::Switch . They must only stay alive between switches. This is because they are reliant on the current game snapshot. The most notable example of one of these is the ResourceRegistry class (see the resource system page).
Last updated