TombEngine 1.7.2 (Developer) scripting interface
Welcome to the TombEngine scripting API. This is a work in progress and some information might be wrong or outdated. Please also note that this is primarily a reference document, not a tutorial, so expect descriptions to be fairly sparse.
At the time of writing, there is a tutorial describing the basics of Lua, as well as a number of example scripts, on the TombEngine website.
Module Hierarchy (boring but important)
Other than the "special tables" (GameVars, LevelVars and LevelFuncs), every module described herein is held in a master table called TEN. For convenience, these modules and classes are automatically put in the global table. For example, you can call GetMoveableByName either of these two ways:
local door = TEN.Objects.GetMoveableByName("door_type4_14")
local door = GetMoveableByName("door_type4_14")
Always check logs/TENLog.txt
If you are scripting levels, TombEngine will often kick you back to the title screen, even if errorMode (see Flow.Settings) is set to ErrorMode.WARN or ErrorMode.SILENT.
This might get annoying, but it's on purpose. If your Lua script contains a syntax error (e.g. you're missing end at the end of a function), the Lua interpreter will not be able to continue running the script. If it tried to keep running, you'd probably see some pretty strange behaviour, and would possibly get a crash regardless.
If this happens, check logs/TENLog.txt and look for an error message with the word "unrecoverable".
Enjoy.
- squidshire and the TombEngine development team.
1 Modules
| Effects | Functions to generate effects. |
| Flow | Functions that (mostly) don't directly impact in-game mechanics. |
| Input | Functions for input management. |
| Inventory | Inventory manipulation |
| Logic | Saving data, triggering functions, and callbacks for level-specific scripts. |
| Objects | Objects including moveables, statics, cameras, and others. |
| Sound | Functions for sound management. |
| Strings | Display strings. |
| Util | Utility functions for various calculations. |
| View | Functions to manage camera and game view. |
2 Classes
| Collision.Probe | Represents a collision probe in the game world. |
| Flow.Level | Stores level metadata. |
| Flow.Settings | Global engine settings which don't fall into particular category or can't be assigned to a specific object. |
| Flow.Statistics | A set of gameplay statistics. |
| Objects.AIObject | AI object |
| Objects.Camera | Basic cameras that can point at Lara or at a CAMERA_TARGET. |
| Objects.LaraObject | Class for extra player-only functions. |
| Objects.Moveable | Represents a moveable object in the game world. |
| Objects.Room | Room object. |
| Objects.Sink | Represents a sink object. |
| Objects.SoundSource | Sound source |
| Objects.Static | Represents a static object in the game world. |
| Objects.Volume | Activator volume. |
| Strings.DisplayString | A string appearing on the screen. |
| View.DisplaySprite | Represents a display sprite. |
3 Primitive Classes
| Flow.Fog | Distance fog. |
| Flow.Horizon | Represents a horizon. |
| Flow.InventoryItem | Represents the properties of an object as it appears in the inventory. |
| Flow.LensFlare | Represents a global lens flare (not to be confused with the lens flare object). |
| Flow.SkyLayer | Describes a layer of moving clouds. |
| Flow.Starfield | Represents a starfield in the sky. |
| Color | Represents an RGBA or RGB color. |
| Rotation | Represents a 3D rotation. |
| Time | Represents a time value in game frames, with support for formatting to hours, minutes, seconds, and centiseconds (1/100th of a second). |
| Vec2 | Represents a float-based 2D vector. |
| Vec3 | Represents a float-based 3D vector. |
4 Enums
| Collision.MaterialType | Constants for material types. |
| Effects.BlendID | Constants for blend mode IDs. |
| Effects.EffectID | Constants for effect IDs. |
| Effects.FeatherMode | Constants for feather modes. |
| Effects.ParticleAnimationType | Constants for particle animation type constants. |
| Flow.ErrorMode | Constants for error modes. |
| Flow.FreezeMode | Constants for freeze modes. |
| Flow.GameStatus | Constants for game statuses. |
| Input.ActionID | Constants for action key IDs. |
| Objects.AmmoType | Constants for player weapon ammo types. |
| Objects.HandStatus | Constants for player hand statuses. |
| Objects.WeaponType | Constants for weapon types. |
| Objects.MoveableStatus | Constants for moveable statuses. |
| Objects.ObjID | Constants for object IDs. |
| Objects.RoomFlagID | Constants for room flag IDs. |
| Objects.RoomReverb | Constants for room reverb types. |
| Sound.SoundTrackType | Constants for the type of the audio tracks. |
| Strings.DisplayStringOption | Constants for Display String Options. |
| Util.LogLevel | Constants for LogLevel IDs. |
| View.AlignMode | Constants for sprite align modes. |
| View.CameraType | Constants for the type of the Camera. |
| View.PostProcessMode | Constants for the post-process effects to apply. |
| View.ScaleMode | Constants for display sprite scale modes. |
5 Lua utility modules
| CustomBar | This module provides functions for creating and managing custom progress bars. |
| Diary | This module provides functions to create and manage diaries. |
| EventSequence | Event sequence - a chain of functions to call at specified times, modeled after TRNG's organizers. |
| Timer | Basic timer - after a specified number of seconds, the specified thing happens. |
| Type | Type - This molule contains functions that allow to check the data type of a variable. |