NOTE: While most of the API is already finalized, a few minor things might still change.

For some things we actually need to differentiate between null and nil. Therefore, the global namespace contains a special readonly table named null.


The baselib is almost identical to the regular Lua base library. The following values/functions are identical to a regular Lua install:

  • _G / _VERSION
  • assert / error
  • getmetatable / setmetatable
  • pcall / xpcall
  • print
  • rawequal / rawget / rawlen / rawset
  • select
  • tonumber / tostring
  • type
  • next / pairs / ipairs

The following functions have been removed for the sandbox environment:

  • collectgarbage / dofile / load / loadfile

There is also a require function, but it works differently from the regular Lua require. It only lets you require files within your own Lua extension or files that other extensions have exported. For more info have a look at the extensions page.

Standard Libraries

The following lua libraries are also available:

  • bit32
  • table
  • string
    • additionally the following functions have been added:
      • string.trim(str): removes all whitespace at the start/end
      • string.isblank(str): returns true if the string only contains whitespace
      • string.interpolate(str, table): replaces all occurences of ${key} with table[key].
    • the modulo operator (%) has been implemented for strings, resulting in a useful string formatting/interpolation function.
      • str % x results in str:format(x) when x is not a table
      • str % x results in str:format(table.unpack(x)) when x is a table and contains at least one array element
      • str % x results in str:interpolate(x) when x is a table without array elements
  • os
    • the following functions have been removed:
      • execute, exit, getenv, remove, rename, setlocale, tmpname
  • math

Additional Libraries

JSON Library

The json library provides means to create and (de-)serialize json objects. Of course you could simply use Lua’s builtin table type to simulate json, but the order of named tabled entries is not fixed in Lua, also in pure Lua we can’t distuingish an empty array from an empty object.

  • json.object(): creates a new JsonObject
  • json.array(): creates an empty JsonArray
  • json.serialize(obj, prettyPrint = false): Serializes the given JsonObject or JsonArray into a string
  • json.deserialize(str): Deserializes the given json string into a JsonObject or JsonArray


JsonObject is a Lua userdata object, where you can simply get/set its values via a string key. Only the following types can be used as values: boolean, number, string, JsonObject, JsonArray

You can delete an entry by setting it to nil.

It also provides the length operator (#obj) and you can iterate over it using pairs(obj).


JsonArray is a Lua userdata object, where you can simple get/set values by index. Only the following types can be used as values: boolean, number, string, JsonObject, JsonArray

It also provides the length operator (#array) and you can iterate over it using ipairs(array).

The following helper functions are also defined:

  • JsonArray:add(value): simply adds the given value at the end of the array
  • JsonArray:first(): returns the first entry or nil
  • JsonArray:last(): returns the last entry or nil

Types Library

This is a simple helper library used for type checking of fields in types/components. Actual instances of these types have different representations in Lua.

  • types.Bool: Representation of the boolean type (Lua boolean)
  • types.Int: Representation of the 32-bit integer type (Lua number)
  • types.Float: Representation of the 32-bit float type (Lua number)
  • types.String: Representation of the string type (Lua string)
  • types.Color: Representation of the color type (Lua string)
  • types.FileHandle: Representation of a FileHandle, which is just a path to a file/folder (Lua string)
  • types.Image: Representation of an image, which is just a path to the file (Lua string)
  • types.Array: Representation of an array of values (native type Array)
  • types.EntityRef: Representation of a reference to an entity, represented by it’s guid (Lua string)


The global namespace provides the invocable middleclass table called class. Middleclass is simple, yet powerful OOP library for Lua.

Quick Look

local Fruit = class('Fruit') -- 'Fruit' is the class' name

function Fruit:initialize(sweetness)
  self.sweetness = sweetness

Fruit.static.sweetness_threshold = 5 -- class variable (also admits methods)

function Fruit:isSweet()
  return self.sweetness > Fruit.sweetness_threshold

local Lemon = class('Lemon', Fruit) -- subclassing

function Lemon:initialize()
  Fruit.initialize(self, 1) -- invoking the superclass' initializer

local lemon = Lemon:new()

print(lemon:isSweet()) -- false


Liluat is a lightweight Lua based template engine. It is very useful wenn creating a code generator or a textual data export. For more information on how to use this library, please have a look at its github page: liluat

Quick Look

-- values to render the template with
local values = {
	title = "A fine selection of vegetables.",
	vegetables = { "carrot", "cucumber", "broccoli", "tomato"}

-- compile the template into lua code
local template = liluat.compile [[
<!DOCTYPE html>
<html lang="en">
		<meta charset="UTF-8">
		<title>{{= title}}</title>
		{{ -- write regular lua code in the template}}
		{{for _,vegetable in ipairs(vegetables) do}}
			<li><b>{{= vegetable}}</b></li>

print(liluat.render(template, values))


<!DOCTYPE html>
<html lang="en">
		<meta charset="UTF-8">
		<title>A fine selection of vegetables.</title>

Native Types

Useful Enums

  • FileResolutionStrategy: Describes how file handles should be resolved
    • FileResolutionStrategy.ProjectRoot: relative to the project save lcoation
    • FileResolutionStrategy.ExportRoot: relative to export directory
  • EntityReferenceKey: Describes how entities are identified
    • EntityReferenceKey.Guid: the entities GUID
    • EntityReferenceKey.Name: the entities name
    • EntityReferenceKey.Id: the index of the entity inside the linear list of entities
  • EnumSerialization: Describes how enums shall be serialized
    • EnumSerialization.Index: Using the 0-based index
    • EnumSerialization.Name: Using their name
    • EnumSerialization.TypeDotName: Using their fully qualified name
    • EnumSerialization.Value: Using their value

Readonly List

Provides a simple readonly wrapper over an array or list.

  • ReadonlyList[index]: get value at index or nil
  • #ReadonlyList: length of list
  • iterable via ipairs


This is a small wrapper around a native file writer.

  • SafeWriter:writeByte(byte): expects an integer and writes the lowest byte to the file. Returns self for chaining.
  • SafeWriter:write(str): writes the given string to the file. Returns self for chaining.
  • SafeWriter:writeLine(str): writes the given string followed by a newline to the file. Returns self for chaining.
  • SafeWriter:flush(): flushes the buffer and returns self for chaining.
  • SafeWriter:close(): closes the file writer. Note: any open file writer is closed automatically when the export finishes.


Defines the overall composition of all entities, enums, types and components.

  • Composition.enums: ReadonlyList of Enums
  • Composition.types: ReadonlyList of Types
  • Composition.components: ReadonlyList of Components
  • Composition.rootEntity: The hidden root entity that is not actually available in the UI. All created entities are somewhere below this entity. You shoudl usually not export this root entity, but only it’s children.
  • Composition:findType(guid): Returns the type definition that is represented by the given guid-string.
  • Composition:collectUserEntities(): creates a linear list of all entities that can be edited by the user, that is: all entities except the root entity.


Describes a user defined enum.

  • name of the enum
  • Enum.guid: return the guid of the enum
  • Enum.type: underlying type of this enum: types.Int, types.Float or types.String
  • Enum.values: ReadonlyList of EnumEntry
  • Enum.isEnum: true


Describes a single valeu of an enumeration.

  • the name of the entry
  • EnumEntry.value: the string representation of it’s value
  • EnumEntry.index: the numeric index of the enum (0-based index!)
  • EnumEntry.typedValue: the correctly typed value (number or string)
  • EnumEntry.fullName: the full name of this entry, for example: MyEnum.EntryA


Describes a user defines custom type.

  • the name of the data type
  • CustomType.guid: the types guid
  • CustomType.fields: ReadonlyList of Fields
  • Custom:new(): instantiates a new instance of this type


Describes a single field of a type.

  • the name of the field
  • Field.type: the type of the fiels, see the Types Library for primitive types, but of coruse a field can also be of any other Enum or Custom Type.


Describes a user defined component. It provides the same API as a CustomType.


A user defined entity with all its components.

  • the name of the entity
  • Entity.guid: the guid of the entity
  • Entity.isRoot: whether the entity is a root entity
  • Entity.children: ReadonlyList of the entities direct children
  • Entity.components: ReadonlyList of the entities ComponentInstances
  • Entity.parent: the parent entity of this entity or nil if it is already the root entity.
  • Entity:dfsPre(visitor): performs a depth-first-search over the whole hierarchy, calling the visitor callable with each visited entity. For each entity the visitor is first called and then the children are visited.
  • Entity.dfsPost(visitor): same as dfsPre, but for each entity it first visits its children and then calls the visitor.


A component only describes its structure, and the ComponentInstance combines that structure with an actual value.

  • ComponentInstance.component: the actual Component
  • ComponentInstance.value: the actual ObjectValue


Basic key-value based dictionary, where the keys are Fields and the values boolean, number, string, ArrayValue, ObjectValue.

  • supports pairs iteration


Typed 1-indexed array.

  • ArrayValue.isArray: true
  • ArrayValue.typeGuid: the guid of the type that the values of this array must have.
  • ArrayValue:add(value): adds the value to the end of the array
  • ArrayValue:removeAt(index): removes the vlaue at the given index
  • ArrayValue:clear(): clears the whole array
  • #ArrayValue: length of the array
  • supports ipairs iteration

Lua Classes


The Exporter class provides some basic functionality to export entities and/or components.

You can create a subclass of Exporter and register it via the registerExporter function in the global namespace.

The Exporter class provides the following functions:

  • Exporter.composition: contains the composition that is about to be exported
  • Exporter.settings: contains the settings json object for this exporter
  • Exporter.userEntities: contains a flat list of all defined entities (except the readonly root entity)
  • Exporter:initialize(composition, settings): constructor that receives the composition to export and the user settings for this exporter as a json object
  • Exporter:getEnumSerializationStrategy(): returns EnumSerialization.Index. Overwrite this method if you want enums to be serialized differently (see Enums).
  • Exporter:getFileResolutionStrategy(): returns FileResolutionStrategy.ProjectRoot. Overwrite this method if want a different file resolution (see Enums).
  • Exporter:getEntityReferenceKey(): returns EntityReferenceKey.Guid. Overwrite this method if you want a different entity identification (see Enums).
  • Exporter:getNullKey(): returns -1 if EntityReferenceKey.Id is used, null otherwise.
  • Exporter:getEntityKey(entity): returns the entities guid, name or index depending on which EntityReferenceKey is used.
  • Exporter:resolveEntityReference(guid): expects a string guid and returns the key for it if the entity exists (getEntityKey), or the null key (getNullKey) when the entity does not exist.
  • Exporter:getEntityById(id): simply returns the entity with the given index or nil if it does not exist.
  • Exporter:getEntityByGuid(guid): simply returns the entity with the given guid or nil if it does not exist.
  • Exporter:guidToId(guid): returns the index for the entity with the given guid or -1 if there is no entity with that guid.
  • Exporter:typeValueToJson(type, value):
    • type: is either a type definition (see Types Library) or an instance of Enum, CustomType or Component
    • value: contains the actual value of the given type, which is either a primitive (boolean, number, string) or an ObjectValue or ArrayValue.
    • it returns the json representation of it, which is either a primitive or a json.object or json.array
    • this method can be overwritten when any special behavior is needed that’s not yet covered.

When you have created a subclass of this and registered it to the editor via registerExporter, then it will show up in the Exporter view and can be used by the user. When the user then hits the export button of your exporter, then an instance will be created automatically and a few more fields and methods will be added to this specific instance:

  • Exporter.pathRootDir: contains the path to the directory to where the user wants to export to
  • Exporter.path: contains the path to the file or directory to where the user wants to export to
  • Exporter.projectRootDir: contains the directory of the project file
  • Exporter:resolveFileHandle(file): resolves the given file according to the used FileResolutionStrategy
  • Exporter:resolveEnum(enumDef, enumEntryGuid): resolves the enum based on the used EnumSerialization. The enumEntryGuid contains the guid of an enum entry of the provided Enum.
  • Exporter:open(file): used to open a SafeWriter, but restricted to the exported file or directory.
    • If the exporter is set to only export a single file, then the file parameter must be that file or nil, in which case the name of the selected file is used automatically.
    • If the exporter is set to export to a directory, then the file parameter must not leave that directory.