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.

BaseLib

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

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

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)

Middleclass

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
end

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

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

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

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

local lemon = Lemon:new()

print(lemon:isSweet()) -- false

liluat

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">
	<head>
		<meta charset="UTF-8">
		<title>{{= title}}</title>
	</head>
	<body>
		<h1>Vegetables</h1>
		<ul>
		{{ -- write regular lua code in the template}}
		{{for _,vegetable in ipairs(vegetables) do}}
			<li><b>{{= vegetable}}</b></li>
		{{end}}
		</ul>
	</body>
</html>
]]

print(liluat.render(template, values))

Output

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="UTF-8">
		<title>A fine selection of vegetables.</title>
	</head>
	<body>
		<h1>Vegetables</h1>
		<ul>
			<li><b>carrot</b></li>
			<li><b>cucumber</b></li>
			<li><b>broccoli</b></li>
			<li><b>tomato</b></li>
		</ul>
	</body>
</html>

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

SafeWriter

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.

Composition

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.

Enum

Describes a user defined enum.

Enum.name: 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

EnumEntry

Describes a single valeu of an enumeration.

EnumEntry.name: 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

CustomType

Describes a user defines custom type.

CustomType.name: 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

Field

Describes a single field of a type.

Field.name: 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.

Component

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

Entity

A user defined entity with all its components.

Entity.name: 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.

ComponentInstance

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

ObjectValue

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

supports pairs iteration

ArrayValue

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

Exporter

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.

Lua API

BaseLib

Standard Libraries

Additional Libraries

JSON Library

JsonObject

JsonArray

Types Library

Middleclass

Quick Look

liluat

Quick Look

Native Types

Useful Enums

Readonly List

SafeWriter

Composition

Enum

EnumEntry

CustomType

Field

Component

Entity

ComponentInstance

ObjectValue

ArrayValue

Lua Classes

Exporter