Common Classes

Find out about the Telltale Editor deals with multiple versions of Telltale classes across a span of game snapshots.

Outline

At the core of the Telltale Editor is the concept of how we have a standardised 'common' set of classes in which all Telltale files are eventually converted into.

Below is the list of all Telltale classes are put into a common class format:

• Mesh (.d3dmesh / D3DMesh) [Mesh::MeshInstance]

• Texture (.d3dtx / D3DTexture / T3Texture) [RenderTexture]

• Chore (.chore / Chore)

• Input Mapper (.imap / InputMapper)

• Animation (.anm / Animation)

• Scene (.scene / Scene)

• Skeleton (.skl / Skeleton)

• Dialog (.dlg / .dlog / DialogResource / Dialog)

• Transition Map (.tmap / TransitionMap)

• PropertySet (.prop / PropertySet) [handled differently, read on]

• Font (.font / Font)

• Other miscellaneous files (.amap / .aam / .particle / .enl / etc..)

All of these files are at runtime (when the game runs) represented as their own class, and class instance for each file loaded.

All of these have their own common class implemented in C++ in the Telltale Editor. The problem arises because Telltale's game engine adapted a lot over its lifetime. The serialised classes (i.e. files) change in format and what's in them vastly. One option would be to write each version of the class and just have loads of conditional code.

In the Telltale Editor, the way it works is the Lua scripts deal with the detail of each class and each common class listed above from the Telltale Editor provides a set of API to push data into the common format. Information which is not in the files because the file is too old is set as defaults or what it would it be in new games. Information which is in the files and the common class is just transferred.

This process of converting this specialised class for a game snapshot into the common set of classes (in which the header files are found here for), is known as normalisation. Once done, you now have a specific Telltale file from a certain game snapshot in a common format interchangeable with all other games (to an extent).

You can then specialise this common class back into a game snapshot and then write that back to a file, saving your modified changes. This is the workflow for pretty all reading and writing of Telltale files which use the Telltale Meta reflection system.

Reading and Writing files

Before your can normalise or specialise a file, you have to read in the file into a meta instance. This is explained in the Meta system part of the core documentation. At this point, its in a specialised specific game format.

Once you have specialised back into this instance from a brand new common instance or previously normalised instance, you can write this meta instance back to a file.

The Exception: Property Sets

There is one slight exception to this system. The PropertySet class (.prop files).

By nature, these files are list of a key value mappings in which the values are meta instances themselves. This makes it very hard to make a common class for it as its just a set of the specialised classes anyway!

Due to this, property sets are never normalised or specialised. They are directly kept as meta instances. They are also not found in the Editor sub-project but rather the lower level Tool-Library project.

There is API for them in which the Editor sub-project deals with coercion of these meta instances to common C++ intrinsic types and Lua types. This allows for classes which format never changes, such as Strings, int, other intrinsics and Telltale specific classes which never change like Bounding Box, Sphere, Rect or AnimOrChore.