Become a SupporterRoadmapChangelogDocumentationDevBlogVideo SeriesSupporters Area

Documentation


IOLITE's documentation helps you get started quickly and serves as a comprehensive reference for the Lua scripting API, the editor, and all the available components.

Important Note

The documentation is a work in progress and will be updated as development progresses.

Table of Contents

  • Engine Documentation
  • Editor Documentation
  • Components Documentation
  • Lua API Documentation
  • Samples Available on GitHub

  Join us on Discord


Discord

Join our brand-new public Discord community and become one of the first 50 members!

By joining our community, you'll have the opportunity to give early feedback, connect with other developers, and be the first to know about new features and enhancements.

Engine Documentation


This section describes some of the core concepts and the ideology of the engine on a very high level. It also features detailed guides to work with the various subsystems of the engine.

Last updated: 13.05.2023

Table of Contents

  1. Introduction and General Concepts
    1. Ideology
    2. Entity Component System
    3. Worlds
    4. Rendering
  2. Installing IOLITE
    1. Setting up Python
  3. Data Sources and the App Metadata File
    1. Using Data Sources for Modding
    2. Working with the App Metadata File
  4. Post Processing
  5. Scripting
  6. Physics and Destruction
  7. Heightmap Terrain Generator
  8. Path Finding
  9. Sound System
  10. UI System
    1. Preparing Textures for the UI System

Introduction and General Concepts

Ideology

IOLITE's core ideology is to offer an easily understandable way to create fun and responsive voxel games.

TODO

Entity Component System

The ECS (Entity Component System) forms the engine's core.

An entity is a general-purpose object assigned a context using one or multiple components. The components primarily house the data to accomplish the specific task, and the system, which comes with every component type, provides the logic. A system works on all instantiated components of a particular type. So, for whatever you're trying to accomplish, you will most likely create an entity and decorate it with one or multiple of the available components to perform specific tasks.

By default, every entity created in the editor has a node component attached to it. Nodes assign a position, orientation, and size in the world to an entity and are also in charge of building hierarchies of multiple entities. One node can have multiple child nodes, and each child node can have multiple child nodes on its own.

As a more complex example, if you create an entity and decorate it with a node, character controller, script, and a hierarchy of voxel shape components, this could become the basis for your player character.

Internally the ECS is designed with data-oriented principles, making it possible to work with large scenes and thousands of objects without hiccups. All the data of entities and components are always ensured to be laid out consecutively in memory, utilizing the CPU caches efficiently when, e.g., iterating over specific properties of components. These design principles also ensure that almost any engine part is or can easily be optimized with multithreading in the future.

Worlds

Worlds are your creative containers. On its basis, a world stores its name and a single root entity. All entities attached to the root entity build the description for your scene. In addition to that, worlds can be saved to and loaded from disk. You can also use worlds to structure your project: Multiple worlds store the levels for your game, while another single world can house the scripts and logic for your menu screen.

Rendering

This section contains a short technical overview of the rendering approach utilized in IOLITE. While these details are optional to work with the engine, having at least some technical information in the back of your head, especially when optimizing your game, can be tremendously helpful.

Two different systems handle the rendering process in IOLITE.

The first system is responsible for displaying the voxels on the screen and for providing the necessary data for the deferred (direct) lighting pass. The other system handles shadow rendering and diffuse/specular global illumination. While the first system utilizes a mixture of ray tracing and rasterization, the second one solely relies on real-time ray tracing using compute shaders.

A world in IOLITE is potentially composed of thousands of so-called voxel shapes. Voxel shapes are one-to-one mappings to the voxel creations loaded from VOX files authored, e.g., in Magica Voxel. Voxel shapes can be positioned, scaled, and rotated however you like. After placing a voxel shape in the scene, the voxelization pass analyzes the voxel data. It then quickly generates a heavily compressed compound of axis-aligned bounding boxes as an overall bounding volume in the background. Voxel shapes are used for displaying everything voxel-related, so even chunks spawned in the destruction systems are subsets of the initial voxel shapes they were created from.

During the rendering stage, the renderer then collects all visible voxel shapes, so the ones neither occluded nor out of the bounds of the camera's view, and renders them to the G-buffer used for the deferred lighting stage. The vertex shader for each voxel shape expands the compressed data to a renderable set of vertices. Subsequently, the fragment shader executes a ray tracing pass, starting from all pixel positions on the bounding volume. If a ray hits a solid voxel, all necessary data is written to the G-buffer. If voxel shapes only occupy a small area on the screen, the rendering of the more complex box geometry is skipped, and the shape's world bounds are rendered instead.

All in all, especially with the occlusion culling pass and conservative depth tests in the background, this approach achieves a close to constant overhead per pixel - making it almost entirely independent of the scene's complexity. Extra care has to be taken to alleviate overdraw, though. Accordingly, it's crucial to ensure that the bounds of shapes are as tight as humanly possible - potentially requiring you to split a complex shape into a compound of multiple smaller shapes to keep the amount of "air" inside the volumes to a minimum.

The real-time ray tracing subsystem works quite differently. Instead of rasterization, it works with various acceleration structures and a low-resolution rendering approach to allow the tracing of millions of rays per frame from any point in the scene in real-time.

In the first step, the GI pass generates a bounding volume hierarchy (BVH) from all the voxel shapes in the world on the fly. This data structure is utilized in the different global illumination passes to accelerate the ray tracing. The BVH allows us to skip large portions of the scene when searching for the actual hits of one specific ray. When the first bounding volume intersecting the ray is found, a ray-tracing pass similar to the approach depicted in the previous system is used.

TODO: The different GI quality levels and their differences, light sources, diffuse sampling, specular sampling, denoising

Installing IOLITE

TODO: Downloading and installing IOLITE

Setting up Python

IOLITE uses Python for auxiliary scripts, such as generating the heightmaps for the terrain generator. To run these scripts, you'll need to have Python installed on your system. We recommend using Python 3.7 or later.

  1. Go to the Python downloads page.
  2. Click on the "Download Python" button for the latest version of Python.
  3. Run the installer.
  4. In the installer, select "Add Python to PATH" if it is not already selected.
  5. Complete the installation process by following the prompts.

The scripts can be found in utilities/python_scripts. Make sure to run install_requirements.bat before trying to execute the scripts. This will automatically install all the required Python packages using Python's package manager pip.

More details on the available scripts can be found in the according sections of this documentation.

Data Sources and the App Metadata File

Every project reads all its data from one or many so-called data sources. Data sources in the development environment are plain directories in the application's root directory (right next to the application). When deploying a build, you can opt-in to package the data of each of the data sources to an IOLITE package (IPKG) file.

Data is loaded from and stored in the following directories in a data source directory:

/my_data_source/worlds/ /my_data_source/managers/post_effects/ /my_data_source/managers/particle_effects/ /my_data_source/media/images/ /my_data_source/media/heightmaps/ /my_data_source/media/scripts/ /my_data_source/media/sounds/ /my_data_source/media/voxels/

If you're not using certain features, it's perfectly fine to skip the creation of the corresponding directories.

Using Data Sources for Modding

Data sources provide an incredibly flexible approach to modding applications created with IOLITE.

Let's say you want to replace a specific voxel asset in a game, like a tree in a different color or a particular script where you've added some little tweaks or new features. All you have to do is to create a new data source directory and place the modified assets in the correct path in the directory structure, matching the path used in the base data source. After that, you must tell the engine to load your data source first, shadowing the assets in the base data source. The following section about the app metadata file depicts how data sources are handled and loaded.

But data sources are not only handsome for modding purposes. They also offer a great way to tweak and test things without modifying the game's base assets.

Working with the App Metadata File

The app metadata data file is a JSON file with the following content:

{ "application_name": "IOLITE", "organization_name": "Missing Deadlines", "version_string": "0.1.0", "data_sources": [ "example" ], "active_data_source": "example", "initial_world": "example", "initial_game_state": "Editing", }

The app metadata offers the option to adjust basic things like your application's name and organization. In addition, it is also in charge of defining the data sources that should be used to source files from and which single data source is currently active for editing purposes.

Here's an overview of all the different parameters:

  • application_name
    The name of your application.
  • organization_name
    The name of your organization (if any).
  • version_string
    Version string following the Semantic Versioning scheme.
  • data_sources
    The data sources used for your project. Data sources are loaded in the provided order. The engine starts searching for files in the first data sources and, if the file is found, skips searching all the other data sources.
  • active_data_source
    The active data source the editor writes to.
  • initial_world
    The initial world to load after startup.
  • initial_game_state
    The initial game state to activate after startup. It can be either Editing for the editor or Main to start the application in game mode directly.

Post Processing

TODO

Scripting

---Called once when the script component becomes active. [email protected] entity Ref The ref of the entity the script component is attached to. function OnActivate(entity) end --- Called every frame. [email protected] entity Ref The ref of the entity the script component is attached to. [email protected] delta_t number The time (in seconds) passed since the last call to this function. function Tick(entity, delta_t) end --- Called once when the script component becomes inactive. [email protected] entity Ref The ref of the entity the script component is attached to. function OnDeactivate(entity) end

Physics and Destruction

TODO

Heightmap Terrain Generator

-- Generate table for heightmap with encoded pixels local heightmap_table = {Terrain.create_pixel(height, grass_height, palette_idx), ...} -- Generate heightmap from provided data/table local node = Terrain.generate_from_data(heightmap_table, size, palette_voxel_shape_name, max_height, scale) -- or directly generate the terrain from an image file (e.g., a PNG file) local node = Terrain.generate_from_image(image_file_name, palette_voxel_shape_name, max_height, scale)

TODO: What are template chunks?

Path Finding

TODO

Sound System

TODO

UI System

TODO

Preparing Textures for the UI System

UI textures are also plain DDS files sourced from the media/images directory. The are some requirements, though:

  • UI textures need to be stored with pre-multiplied alpha
  • UI textures must not contain any additional MIP levels (besides the first one, of course)

Here's an example of how to correctly convert a UI texture using DirectXTex:

texconv.exe -y -m 1 -pmalpha -f BC7_UNORM_SRGB my_ui_texture.png

Editor Documentation


This section focuses on the editor, featuring in-depth descriptions of the essential features, making it easy for you to get started quickly.

Last updated: 03.04.2023

Table of Contents

  1. Controlling the Camera
  2. Transforming Entities
  3. Creating and Loading Worlds
  4. Creating new Entities
  5. Importing VOX files
  6. Importing whole Scenes from VOX Files
    1. Known Issues

Controlling the Camera

TODO

Transforming Entities

TODO

Creating and Loading Worlds

TODO

Creating new Entities

To create a new entity in the editor, right-click on the entity in the world inspector you want to attach the new entity to. In the context menu, either select Attach New Entity or Attach New Entity (With Component) to create an entity decorated with the selected component from the start.

Importing VOX files

TODO

Importing whole Scenes from VOX Files

To import a scene from a VOX file, open up the File menu in the editor and select Import Scene from VOX. Finally, select the VOX file to import the scene from. You can find the imported scene hierarchy below a new entity called vox_scene. Please note that only scenes from VOX files can be loaded which are already present in the media/voxels directory.

Known Issues

  • Scaling is not supported when importing scenes from VOX files.
    Workaround: If you're using the flip feature in the world view, please reset the rotation and apply the changes in the model view.

Components Documentation


This chapter in-depth describes all the different Component types available in IOLITE.

Last updated: 03.04.2023

Table of Contents

  1. Voxel Shape
  2. Camera
  3. Character Controller
  4. Procedural Animation
  5. Script
  6. Post Effect Volume
  7. Trigger
  8. Interactable

Voxel Shape

TODO

Camera

TODO

Character Controller

TODO

Procedural Animation

TODO

Script

TODO

Post Effect Volume

TODO

Trigger

TODO

Interactable

TODO

Lua API 0.1.0 Documentation


Overview

This section offers a quick overview of all the functions and types made available via the Lua scripting interface. Use this section to quickly localize something and to jump to the detailed description in the next sections.

Lua Scripting Interface Header

To ease writing Lua code, you can also download the scripting interface as a LUA file. Autocompletion should work right out of the box with a lot of different IDEs, like, e.g., Visual Studio Code in combination with the widely spread Lua extension. Just download and place the iolite_api.lua file right next to your scripts.

The file itself is automatically generated and always reflects the latest state of the API visible on this page here.

  • iolite_api.lua

The file itself looks like this:

---IOLITE Scripting API (https://iolite-engine.com) [email protected] (c) 2023 Missing Deadlines (Benjamin Wrensch) ---Vector type with two components. [email protected] Vec2 Vec2 = { ---The x component of this vector. [email protected] number x = nil, ---The y component of this vector. [email protected] number y = nil } ---Initializes all components of the vector to the provided parameter. [email protected] x Vec2|number [email protected] Vec2 value function Vec2(x) end ---Initializes the x and y components to the provided values. [email protected] x number [email protected] y number [email protected] Vec2 value function Vec2(x, y) end ---Vector type with three components. [email protected] Vec3 Vec3 = { ---The x component of this vector. [email protected] number x = nil, ---The y component of this vector. [email protected] number y = nil, ---The z component of this vector. [email protected] number z = nil } ---Initializes all components of the vector to the provided parameter. [email protected] x Vec3|number [email protected] Vec3 value function Vec3(x) end ---Initializes the x, y, and z components to the provided values. [email protected] x number [email protected] y number [email protected] z number [email protected] Vec3 value function Vec3(x, y, z) end ---Vector type with four components. [email protected] Vec4 Vec4 = { ---The x component of this vector. [email protected] number x = nil, ---The y component of this vector. [email protected] number y = nil, ---The z component of this vector. [email protected] number z = nil, ---The w component of this vector. [email protected] number w = nil } ---Initializes all components of the vector to the provided parameter. [email protected] x Vec4|number [email protected] Vec4 value function Vec4(x) end ---Initializes the x, y, z, and w components to the provided values. [email protected] x number [email protected] y number [email protected] z number [email protected] w number [email protected] Vec4 value function Vec4(x, y, z, w) end ---A quaternion with four components. [email protected] Quat Quat = { ---The x component of this quaternion. [email protected] number w = nil, ---The y component of this quaternion. [email protected] number x = nil, ---The z component of this quaternion. [email protected] number y = nil, ---The w component of this quaternion. [email protected] number z = nil } ---Initializes all components of the quaternion to the provided parameter. [email protected] quat Quat [email protected] Quat value function Quat(quat) end ---Initializes the w, x, y, and z components to the provided values. [email protected] w number ---[email protected] x number [email protected] y number [email protected] z number [email protected] Quat value function Quat(w, x, y, z) end ---A reference to entities, components or resources. Refs are only returned by functions and can then be used to, e.g., interact with a created node. [email protected] Ref Ref = { } ---A name can be initialized from a string and supports fast comparison with other names (using integer instead of string comparisons internally). [email protected] Name Name = { } ---Initializes an invalid/empty name. [email protected] Name value function Name() end ---Initializes a new name from a string. [email protected] name string [email protected] Name value function Name(name) end ---Initializes this name from another name. [email protected] name Name [email protected] Name value function Name(name) end ---Handle used to reference particle emitters. [email protected] EmitterHandle EmitterHandle = { } Math = {} ---Returns x raised to the power y. [email protected] x number The base. [email protected] y number The exponent. [email protected] number value The result of x raised to the power y. function Math.pow(x, y) end ---Returns the square root of x. [email protected] x number The input value. [email protected] number value The square root of x. function Math.sqrt(x) end ---Returns e (Euler's number) raised to the power x. [email protected] x number The exponent. [email protected] number value The result of e raised to the power x. function Math.exp(x) end ---Calculates the absolute value of x. [email protected] x number The input value. [email protected] number value The absolute value of x. function Math.abs(x) end ---Clamps x to the provided minimum and maximum. [email protected] x number The value to clamp. [email protected] min number The minimum. [email protected] max number The maximum. [email protected] number value The result of x clamped to [min, max]. function Math.clamp(x, min, max) end ---Computes the minimum value of x and y. [email protected] x number First input value. [email protected] y number Second input value. [email protected] number value The minimum of x and y. function Math.min(x, y) end ---Computes the maximum value of x and y. [email protected] x number First input value. [email protected] y number Second input value. [email protected] number value The maximum of x and y. function Math.max(x, y) end Math = {} ---Converts the provided angle in degrees to radians. [email protected] x number Angle in degrees. [email protected] number value Angle in radians. function Math.radians(x) end ---Converts the provided angle in radians to degrees. [email protected] x number Angle in radians. [email protected] number value Angle in degrees. function Math.degrees(x) end ---Calculates the sine of the provided angle. [email protected] x number Angle in radians. [email protected] number value The sine of the angle. function Math.sin(x) end ---Calculates the arc sine of the provided value. [email protected] x number Value in [-1, 1]. [email protected] number value The arc sine in radians. function Math.asin(x) end ---Calculates the cosine of the provided angle. [email protected] x number Angle in radians. [email protected] number value The cosine of the angle. function Math.cos(x) end ---Calculates the arc cosine of the provided value. [email protected] x number Value in [-1, 1]. [email protected] number value The arc cosine in radians. function Math.acos(x) end ---Calculates the tangent of the provided angle. [email protected] x number Angle in radians. [email protected] number value The tangent of the angle. function Math.tan(x) end ---Calculates the arc tangent of the provided angle. [email protected] x number Input value. [email protected] number value The arc tangent in radians. function Math.atan(x) end ---Calculates the arc tangent of y/x in radians. [email protected] y number Proportion of the y-coordinate. [email protected] x number Proportion of the x-coordinate. [email protected] number value The arc tangent of y/x in radians. function Math.atan2(y, x) end Math = {} ---Linearly interpolates between the provided input values. [email protected] x number|Vec2|Vec3|Vec4 Start of the interpolation range. [email protected] y number|Vec2|Vec3|Vec4 End of the interpolation range. [email protected] a number Fraction used to interpolate between x and y. [email protected] any value The interpolated result. function Math.lerp(x, y, a) end ---Spherically interpolates between the provided input values. Useful for interpolating between quaternion-based orientations at constant speed. [email protected] x Quat First interpolant. [email protected] y Quat Second interpolant. [email protected] a number Fraction used to interpolate between x and y. [email protected] Quat value The interpolated result. function Math.slerp(x, y, a) end Math = {} ---Retrieves the component of the vector for the given index. [email protected] vec Vec2|Vec3|Vec4 The vector to retrieve the component from. [email protected] idx number The index of the component to retrieve. [email protected] number value The value of the vector's component for the given index. function Math.vec_get_component(vec, idx) end ---Multiplies the provided vectors. [email protected] x Vec2|Vec3|Vec4 The first vector. [email protected] y Vec2|Vec3|Vec4] The second vector. [email protected] any value The product of the operation. function Math.vec_mul(x, y) end ---Scales the provided vector by the given scalar value. [email protected] s number The scalar value the vector is scaled by. [email protected] vec Vec2|Vec3|Vec4 The vector to scale. [email protected] any value The scaled vector. function Math.vec_scale(s, vec) end ---Divides the first vector by the second vector. [email protected] x Vec2|Vec3|Vec4 The first vector. [email protected] y Vec2|Vec3|Vec4 The second vector. [email protected] any value The quotient of the operation. function Math.vec_div(x, y) end ---Adds the second vector to the first vector. [email protected] x Vec2|Vec3|Vec4 The first vector. [email protected] y Vec2|Vec3|Vec4 The second vector. [email protected] any value The summand of the operation. function Math.vec_add(x, y) end ---Subtracts the second vector from the first vector. [email protected] x Vec2|Vec3|Vec4 The first vector. [email protected] y Vec2|Vec3|Vec4 The second vector. [email protected] any value The difference of the operation. function Math.vec_sub(x, y) end ---Returns the length of the provided vector. [email protected] vec Vec2|Vec3|Vec4 The vector used for calculating the length. [email protected] any value The length of the provided vector. function Math.vec_length(vec) end ---Returns the squared length of the provided vector. More efficient when only comparing lengths. [email protected] vec Vec2|Vec3|Vec4 The vector used for calculating the length. [email protected] any value The squared length of the provided vector. function Math.vec_length2(vec) end ---Returns the distance between the two provided points in space. [email protected] x Vec2|Vec3|Vec4 The first position in space. [email protected] y Vec2|Vec3|Vec4 The second position in space. [email protected] any value The distance between the two provided points. function Math.vec_distance(x, y) end ---Returns the squared distance between the two provided points in space. More efficient when only comparing distances. [email protected] x Vec2|Vec3|Vec4 The first position in space. [email protected] y Vec2|Vec3|Vec4 The second position in space. [email protected] any value The squared distance between the two provided points. function Math.vec_distance2(x, y) end ---Normalizes the provided vector. [email protected] x Vec2|Vec3|Vec4 The vector to normalize. [email protected] any value The normalized vector. function Math.vec_normalize(x) end ---Calculates the dot product of the provided vectors. [email protected] x Vec2|Vec3|Vec4 The first vector. [email protected] y Vec2|Vec3|Vec4 The second vector. [email protected] number value The dot product of both vectors. function Math.vec_dot(x, y) end ---Calculates the cross product of the provided vectors. [email protected] x Vec3 The first vector. [email protected] y Vec3 The second vector. [email protected] Vec3 value The cross product of both vectors. function Math.vec_cross(x, y) end Math = {} ---Multiplies the provided quaternions. [email protected] x Quat The first quaternion. [email protected] y Quat The second quaternion. [email protected] Quat value The product of both quaternions. function Math.quat_mul(x, y) end ---Rotates the provided three-component vector using the given quaternion. [email protected] quat Quat The quaternion used for the rotation. [email protected] vec Vec3 The vector to rotate. [email protected] Vec3 value The rotated three-component vector. function Math.quat_rotate(quat, vec) end ---Computes the inverse of the provided quaternion. [email protected] quat Quat The quaternion to invert. [email protected] Quat value The inverse of the provided quaternion. function Math.quat_inverse(quat) end ---Normalizes the provided quaternion. [email protected] quat Quat The quaternion to normalize. [email protected] Quat value The normalized quaternion. function Math.quat_normalize(quat) end ---Generates a look at quaternion using the provided direction and up vector. [email protected] dir Vec3 The direction to look in. [email protected] up Vec3 The up vector. [email protected] Quat value The look at quaternion for the provided direction and up vector. function Math.quat_look_at(dir, up) end ---Generates a quaternion from the provided axis rotation. [email protected] angle number The angle of the rotation in radians. [email protected] axis Vec3 The axis to rotate around. [email protected] Quat value The quaternion for the provided axis rotation. function Math.quat_from_angle_axis(angle, axis) end ---Derives the Euler angles from the provided quaternion. [email protected] quat Quat The quaternion to derive the Euler angles from. [email protected] Vec3 value The Euler angles [pitch, yaw, roll] derived from the quaternion. function Math.quat_to_euler_angles(quat) end ---Derives a quaternion from the provided Euler angles. [email protected] euler Vec3 The Euler angles [pitch, yaw, roll] to derive the quaternion from. [email protected] Quat value The quaternion derived from the Euler angles. function Math.quat_from_euler_angles(euler) end ---Computes a quaternion describing a rotation from vector x to vector y. [email protected] x Vec3 The first vector. [email protected] y Vec3 The second vector. [email protected] Quat value The quaternion describing a rotation from x to y. function Math.quat_rotation(x, y) end Random = {} ---Generates a random unsigned integer. [email protected] number value Random unsigned integer value. function Random.rand_uint() end ---Generates a random float in [0.0, 1.0]. [email protected] number value Random floating point value. function Random.rand_float() end ---Generates a random float in [min, max]. [email protected] min number The smallest random float to generate. [email protected] max number The largest random float to generate. [email protected] number value Random floating point value in [min, max]. function Random.rand_float_min_max(min, max) end Input = {} ---Gets the state of the given key. [email protected] key number The key to retrieve the state from. [email protected] player_id number The player id to retrieve the state from. [email protected] number value The current state of the given key. function Input.get_key_state(key, player_id) end ---Gets the state of the given axis. [email protected] axis number The axis to retrieve the state from. [email protected] player_id number The player id to retrieve the state from. [email protected] number value The current state of the given axis mapped to [-1, 1]. function Input.get_axis_state(axis, player_id) end ---Gets the position of the mouse. [email protected] Vec2 value The position of the mouse in pixels. function Input.get_mouse_pos() end ---Gets the position of the mouse mapped to viewport coordinates. [email protected] Vec2 value The position of the mouse relative to the viewport (mapped to [0, 1]). function Input.get_mouse_pos_viewport() end ---Gets the delta position of the mouse (calculated as current_mouse_pos - previous_mouse_pos). [email protected] Vec2 value The position delta in pixels. function Input.get_mouse_pos_relative() end ---Requests the hardware mouse cursor to be shown. Has to be called every frame to keep the mouse cursor visible. function Input.request_mouse_cursor() end Log = {} ---Logs the given string as information. [email protected] message string The message to log. function Log.log_info(message) end ---Logs the given string as a warning. [email protected] message string The message to log. function Log.log_warning(message) end ---Logs the given string as an error. [email protected] message string The message to log. function Log.log_error(message) end Settings = {} ---Creates or sets the setting with the given name to the provided value. [email protected] name string The name of the setting. [email protected] value number|boolean The value to set. function Settings.register_or_update_setting(name, value) end ---Gets the setting with the given name (as a bool). [email protected] name string The name of the setting to retrieve from. [email protected] boolean value The value of the setting. function Settings.find_setting_bool(name) end ---Gets the setting with the given name (as a float). [email protected] name string The name of the setting to retrieve from. [email protected] boolean value The value of the setting. function Settings.find_setting_float(name) end ---Gets the setting with the given name (as an unsigned integer). [email protected] name string The name of the setting to retrieve from. [email protected] number value The value of the setting. function Settings.find_setting_uint(name) end Ref = {} ---Returns true if the provided ref is valid. [email protected] ref Ref The ref to check. [email protected] boolean value True if the provided ref is valid. function Ref.is_valid(ref) end ---Gets the id of the provided ref. [email protected] ref Ref The ref to retrieve from. [email protected] number value The id of the provided ref. function Ref.get_id(ref) end ---Gets the type id of the provided ref. [email protected] ref Ref The ref to retrieve from. [email protected] number value The type id of the provided ref. function Ref.get_type_id(ref) end Name = {} ---Returns true if the given name is valid (not empty). [email protected] name string The name to check. [email protected] Ref value True if the given names are valid (and not empty). function Name.is_valid(name) end ---Returns whether the names are equal - or not. [email protected] a Name The first name to compare. [email protected] b Ref The second name to compare. [email protected] boolean value True if both names are equal. function Name.equal_to(a, b) end Physics = {} ---Performs a sphere sweep test from the given position into the provided direction. Great for doing intersection tests for fast moving objects, like, e.g., projectiles. [email protected] p Vec3 The position to start the sweep at. [email protected] r number The radius of the sphere to sweep with. [email protected] dir Vec3 The direction to sweep in. [email protected] dist number The distance to sweep. [email protected] boolean hit Whether the sweep test hit something - or not. [email protected] Vec3 pos The position of the hit. [email protected] Vec3 normal The normal of the hit. [email protected] Ref ref The ref referencing the component responsible for the hit. function Physics.sweep_sphere(p, r, dir, dist) end ---Performs a raycast from the given position into the provided direction. [email protected] origin Vec3 The starting position (origin) of the ray. [email protected] dir Vec3 The direction of the ray. [email protected] dist number The maximum distance the ray can travel. [email protected] boolean hit Whether the raycast hit something - or not. [email protected] Vec3 pos The position of the hit. [email protected] Vec3 normal The normal of the hit. [email protected] Ref ref The ref referencing the component responsible for the hit. function Physics.raycast(origin, dir, dist) end World = {} ---Returns the root node of the current world. [email protected] Ref value The root node of the current world. function World.get_root_node() end ---Loads the world with the given name replacing the current world. [email protected] name string The name of the world to load. function World.load_world(name) end ---Spawns the prefab with the given name. [email protected] name string The name of the prefab to spawn. [email protected] Ref value The root node of the loaded prefab. function World.spawn_prefab(name) end ---Helper function to calculate a ray starting at the current camera's position towards the projected position of the mouse cursor. [email protected] boolean origin The origin of the ray (current position of the camera). [email protected] Vec3 pos The direction of the ray (towards the current position of the mouse). function World.calc_mouse_ray() end ---Applies radius damage at the given position for explosion type effects. [email protected] pos Vec3 The world space position to apply the explosion at. [email protected] radius number The radius of the explosion. [email protected] shade_crater boolean Whether the crater of the explosion should be shaded. function World.radius_damage(pos, radius, shade_crater) end ParticleSystem = {} ---Spawns the particle emitter with a certain particle effect at the given position for the provided time. [email protected] effect_name string The name of the particle effect to use. [email protected] position Vec3 The position to spawn the emitter at (in world space). [email protected] lifetime_in_seconds number How long the emitter should live (in seconds). [email protected] adjust_spawnrate boolean Whether the spawnrate should be adjusted to the lifetime. [email protected] EmitterHandle value The handle of the emitter. function ParticleSystem.spawn_particle_emitter(effect_name, position, lifetime_in_seconds, adjust_spawnrate) end ---Updates the spawn rate of the provided particle emtiter. [email protected] emitter_handle EmitterHandle The handle of the emitter to update. [email protected] spawn_rate float The new spawn rate to set. function ParticleSystem.set_spawn_rate(emitter_handle, spawn_rate) end DebugGeometry = {} ---Draws a line with the given color. [email protected] pos0 Vec3 The starting position of the line. [email protected] pos1 Vec3 The end position of the line. [email protected] color Vec4 The color of the line. [email protected] always_in_front boolean Keep in front of all other objects in the scene. function DebugGeometry.draw_line(pos0, pos1, color, always_in_front) end ---Draws a sphere with the given radius and color. [email protected] center Vec3 The center of the sphere. [email protected] radius number The radius of the sphere. [email protected] color Vec4 The color of the sphere. [email protected] always_in_front boolean Keep in front of all other objects in the scene. function DebugGeometry.draw_sphere(center, radius, color, always_in_front) end Entity = {} ---Gets the type id for entities. [email protected] number value The type id for entities. function Entity.get_type_id() end ---Returns whether the referenced entity is still alive - or not. [email protected] entity Ref The ref of the entity. [email protected] boolean value True if the entity referenced is alive. function Entity.is_alive(entity) end ---Retrieves the name of the given entity. [email protected] entity Ref The ref of the entity. [email protected] string value The name of the entity. function Entity.get_name(entity) end ---Returns the first entity found in the world with the given name. [email protected] name string The name of the entity to retrieve. [email protected] Ref value The entity with the given name. Returns an invalid ref if not found. function Entity.find_first_entity_with_name(name) end ---Returns an array with all entities matching the given name. [email protected] name string The name of the entities to retrieve. [email protected] table value List of entities with the given name. function Entity.find_entities_with_name(name) end Node = {} ---Creates a new node component and entity and attaches it to the root node of the current world. [email protected] name Ref The name of the node. function Node.create(name) end ---Creates a new node component and entity and attatches it to the provided node. [email protected] parent_node Ref The node to attach the new node to. [email protected] name Ref The name of the node. function Node.create(parent_node, name) end ---Destroys the given node and its whole hierarchy, including all components and entities attached to it and its children. [email protected] node Ref The node to destroy. function Node.destroy(node) end ---Gets the local position of the given node component. [email protected] node Ref The node component to retrieve from. [email protected] Vec3 value The local position of the given node component. function Node.get_position(node) end ---Gets the world position of the given node component. [email protected] node Ref The node component to retrieve from. [email protected] Vec3 value The world position of the given node component. function Node.get_world_position(node) end ---Gets the orientation of the given node component. [email protected] node Ref The node component to retrieve from. [email protected] Quat value The orientation of the given node component. function Node.get_orientation(node) end ---Gets the world orientation of the given node component. [email protected] node Ref The node component to retrieve from. [email protected] Quat value The world orientation of the given node component. function Node.get_world_orientation(node) end ---Sets the local position of the given node component. [email protected] node Ref The node component to modify. [email protected] position Vec3 The local position to set. function Node.set_position(node, position) end ---Sets the world position of the given node component by reversing the world transform of the parent node. Can be used to move the node to a fixed world position, regardless of its hierarchy. [email protected] node Ref The node component to modify. [email protected] position Vec3 The world position to set. function Node.set_world_position(node, position) end ---Sets the local orientation of the given node component. [email protected] node Ref The node component to modify. [email protected] position Quat The local orientation to set. function Node.set_orientation(node, position) end ---Sets the world orientation of the given node component by reversing the world transform of the parent node. Can be used to set the node to a fixed world orientation, regardless of its hierarchy. [email protected] node Ref The node component to modify. [email protected] orientation Quat The world orientation to set. function Node.set_world_orientation(node, orientation) end ---Sets the local size of the given node component. [email protected] node Ref The node component to modify. [email protected] size Vec3 The local size to set. function Node.set_size(node, size) end ---Updates the world transforms of the given node and all its child nodes. Has to be called to make any changes to the node visible. [email protected] node Ref The root node component to update. function Node.update_transforms(node) end Tag = {} ---Gets the type id for the given component. [email protected] number value The type id for node components. function Tag.get_type_id() end ---Returns whether the referenced component is alive - or not. [email protected] comp Ref The ref of the node component. [email protected] boolean value True if the node component referenced is alive. function Tag.is_alive(comp) end ---Returns the component's entity. [email protected] comp Ref The component to retrieve from. [email protected] Ref value The entity this node component is attached to. function Tag.get_entity(comp) end ---Gets the component of the provided entity. [email protected] comp Ref The Ref of the entity. [email protected] Ref value The ref of the component of the provided entity. Returns an invalid ref if none is found. function Tag.get_component_for_entity(comp) end ---Returns an array of all available entities with matching tags. [email protected] tag string The tag to match. [email protected] table value List of entities with matching tag components. function Tag.find_entities_with_tag(tag) end CharacterController = {} ---Gets the type id for the given component. [email protected] number value The type id for node components. function CharacterController.get_type_id() end ---Returns whether the referenced component is alive - or not. [email protected] comp Ref The ref of the node component. [email protected] boolean value True if the node component referenced is alive. function CharacterController.is_alive(comp) end ---Returns the component's entity. [email protected] comp Ref The component to retrieve from. [email protected] Ref value The entity this node component is attached to. function CharacterController.get_entity(comp) end ---Gets the component of the provided entity. [email protected] comp Ref The Ref of the entity. [email protected] Ref value The ref of the component of the provided entity. Returns an invalid ref if none is found. function CharacterController.get_component_for_entity(comp) end ---Moves the character controller by the provided vector. [email protected] cct Vec3 The character controller to move. [email protected] move Vec3 The move vector. function CharacterController.move(cct, move) end

General

General math related functions.

Functions

pow(x, y)Returns x raised to the power y.
sqrt(x)Returns the square root of x.
exp(x)Returns e (Euler's number) raised to the power x.
abs(x)Calculates the absolute value of x.
clamp(x, min, max)Clamps x to the provided minimum and maximum.
min(x, y)Computes the minimum value of x and y.
max(x, y)Computes the maximum value of x and y.

Trigonometry

Trigonometry related functions and types.

Functions

radians(x)Converts the provided angle in degrees to radians.
degrees(x)Converts the provided angle in radians to degrees.
sin(x)Calculates the sine of the provided angle.
asin(x)Calculates the arc sine of the provided value.
cos(x)Calculates the cosine of the provided angle.
acos(x)Calculates the arc cosine of the provided value.
tan(x)Calculates the tangent of the provided angle.
atan(x)Calculates the arc tangent of the provided angle.
atan2(y, x)Calculates the arc tangent of y/x in radians.

Interpolation

Functions enabling interpolation between different data types.

Functions

lerp(x, y, a)Linearly interpolates between the provided input values.
slerp(x, y, a)Spherically interpolates between the provided input values. Useful for interpolating between quaternion-based orientations at constant speed.

Vector Math

Vector math related functions.

Functions

vec_get_component(vec, idx)Retrieves the component of the vector for the given index.
vec_mul(x, y)Multiplies the provided vectors.
vec_scale(s, vec)Scales the provided vector by the given scalar value.
vec_div(x, y)Divides the first vector by the second vector.
vec_add(x, y)Adds the second vector to the first vector.
vec_sub(x, y)Subtracts the second vector from the first vector.
vec_length(vec)Returns the length of the provided vector.
vec_length2(vec)Returns the squared length of the provided vector. More efficient when only comparing lengths.
vec_distance(x, y)Returns the distance between the two provided points in space.
vec_distance2(x, y)Returns the squared distance between the two provided points in space. More efficient when only comparing distances.
vec_normalize(x)Normalizes the provided vector.
vec_dot(x, y)Calculates the dot product of the provided vectors.
vec_cross(x, y)Calculates the cross product of the provided vectors.

Types

Vec2Vector type with two components.
Vec3Vector type with three components.
Vec4Vector type with four components.

Quaternion Math

Quaternion math related functions and types.

Functions

quat_mul(x, y)Multiplies the provided quaternions.
quat_rotate(quat, vec)Rotates the provided three-component vector using the given quaternion.
quat_inverse(quat)Computes the inverse of the provided quaternion.
quat_normalize(quat)Normalizes the provided quaternion.
quat_look_at(dir, up)Generates a look at quaternion using the provided direction and up vector.
quat_from_angle_axis(angle, axis)Generates a quaternion from the provided axis rotation.
quat_to_euler_angles(quat)Derives the Euler angles from the provided quaternion.
quat_from_euler_angles(euler)Derives a quaternion from the provided Euler angles.
quat_rotation(x, y)Computes a quaternion describing a rotation from vector x to vector y.

Types

QuatA quaternion with four components.

Random

Functions to generate random numbers.

Functions

rand_uint()Generates a random unsigned integer.
rand_float()Generates a random float in [0.0, 1.0].
rand_float_min_max(min, max)Generates a random float in [min, max].

Input

Functions to interact with the input system.

Functions

get_key_state(key, player_id)Gets the state of the given key.
get_axis_state(axis, player_id)Gets the state of the given axis.
get_mouse_pos()Gets the position of the mouse.
get_mouse_pos_viewport()Gets the position of the mouse mapped to viewport coordinates.
get_mouse_pos_relative()Gets the delta position of the mouse (calculated as current_mouse_pos - previous_mouse_pos).
request_mouse_cursor()Requests the hardware mouse cursor to be shown. Has to be called every frame to keep the mouse cursor visible.

Logging

Functions necessary to interact with the logging subsystem.

Functions

log_info(message)Logs the given string as information.
log_warning(message)Logs the given string as a warning.
log_error(message)Logs the given string as an error.

Settings

Functions provided to modify and retrieve settings.

Functions

register_or_update_setting(name, value)Creates or sets the setting with the given name to the provided value.
find_setting_bool(name)Gets the setting with the given name (as a bool).
find_setting_float(name)Gets the setting with the given name (as a float).
find_setting_uint(name)Gets the setting with the given name (as an unsigned integer).

Refs

Functions provided to work with refs. Refs are used to reference components, resources and entities.

Functions

is_valid(ref)Returns true if the provided ref is valid.
get_id(ref)Gets the id of the provided ref.
get_type_id(ref)Gets the type id of the provided ref.

Types

RefA reference to entities, components or resources. Refs are only returned by functions and can then be used to, e.g., interact with a created node.

Names

Functions and types provided to interact with names.

Functions

is_valid(name)Returns true if the given name is valid (not empty).
equal_to(a, b)Returns whether the names are equal - or not.

Types

NameA name can be initialized from a string and supports fast comparison with other names (using integer instead of string comparisons internally).

Physics

Functions provided to interact with the physics system.

Functions

sweep_sphere(p, r, dir, dist)Performs a sphere sweep test from the given position into the provided direction. Great for doing intersection tests for fast moving objects, like, e.g., projectiles.
raycast(origin, dir, dist)Performs a raycast from the given position into the provided direction.

World

Functions provided to interact with the current world on a global level.

Functions

get_root_node()Returns the root node of the current world.
load_world(name)Loads the world with the given name replacing the current world.
spawn_prefab(name)Spawns the prefab with the given name.
calc_mouse_ray()Helper function to calculate a ray starting at the current camera's position towards the projected position of the mouse cursor.
radius_damage(pos, radius, shade_crater)Applies radius damage at the given position for explosion type effects.

Particle System

Functions to interact with the low-level particle system.

Functions

spawn_particle_emitter(effect_name, position, lifetime_in_seconds, adjust_spawnrate)Spawns the particle emitter with a certain particle effect at the given position for the provided time.
set_spawn_rate(emitter_handle, spawn_rate)Updates the spawn rate of the provided particle emtiter.

Types

EmitterHandleHandle used to reference particle emitters.

Debug Geometry

Functions to draw debug geometry. Have to be called every frame.

Functions

draw_line(pos0, pos1, color, always_in_front)Draws a line with the given color.
draw_sphere(center, radius, color, always_in_front)Draws a sphere with the given radius and color.

Entities

Functions provided to interact with entities.

Functions

get_type_id()Gets the type id for entities.
is_alive(entity)Returns whether the referenced entity is still alive - or not.
get_name(entity)Retrieves the name of the given entity.
find_first_entity_with_name(name)Returns the first entity found in the world with the given name.
find_entities_with_name(name)Returns an array with all entities matching the given name.

Node Components

Functions provided to interact with node components.

Functions

create(name)Creates a new node component and entity and attaches it to the root node of the current world.
create(parent_node, name)Creates a new node component and entity and attatches it to the provided node.
destroy(node)Destroys the given node and its whole hierarchy, including all components and entities attached to it and its children.
get_position(node)Gets the local position of the given node component.
get_world_position(node)Gets the world position of the given node component.
get_orientation(node)Gets the orientation of the given node component.
get_world_orientation(node)Gets the world orientation of the given node component.
set_position(node, position)Sets the local position of the given node component.
set_world_position(node, position)Sets the world position of the given node component by reversing the world transform of the parent node. Can be used to move the node to a fixed world position, regardless of its hierarchy.
set_orientation(node, position)Sets the local orientation of the given node component.
set_world_orientation(node, orientation)Sets the world orientation of the given node component by reversing the world transform of the parent node. Can be used to set the node to a fixed world orientation, regardless of its hierarchy.
set_size(node, size)Sets the local size of the given node component.
update_transforms(node)Updates the world transforms of the given node and all its child nodes. Has to be called to make any changes to the node visible.

Tag Components

Functions provided to interact with tag components.

Functions

get_type_id()Gets the type id for the given component.
is_alive(comp)Returns whether the referenced component is alive - or not.
get_entity(comp)Returns the component's entity.
get_component_for_entity(comp)Gets the component of the provided entity.
find_entities_with_tag(tag)Returns an array of all available entities with matching tags.

Character Controller Components

Functions provided to interact with character controller components.

Functions

get_type_id()Gets the type id for the given component.
is_alive(comp)Returns whether the referenced component is alive - or not.
get_entity(comp)Returns the component's entity.
get_component_for_entity(comp)Gets the component of the provided entity.
move(cct, move)Moves the character controller by the provided vector.

Functions

This section lists the detailed description of all functions made available via the Lua scripting interface. To quickly find and jump to a function, please use the overview section above.

General

pow

Returns x raised to the power y.
local value = Math.pow(x, y)

Arguments

x [number]
The base.
y [number]
The exponent.

Return Value

value [number]
The result of x raised to the power y.

sqrt

Returns the square root of x.
local value = Math.sqrt(x)

Arguments

x [number]
The input value.

Return Value

value [number]
The square root of x.

exp

Returns e (Euler's number) raised to the power x.
local value = Math.exp(x)

Arguments

x [number]
The exponent.

Return Value

value [number]
The result of e raised to the power x.

abs

Calculates the absolute value of x.
local value = Math.abs(x)

Arguments

x [number]
The input value.

Return Value

value [number]
The absolute value of x.

clamp

Clamps x to the provided minimum and maximum.
local value = Math.clamp(x, min, max)

Arguments

x [number]
The value to clamp.
min [number]
The minimum.
max [number]
The maximum.

Return Value

value [number]
The result of x clamped to [min, max].

min

Computes the minimum value of x and y.
local value = Math.min(x, y)

Arguments

x [number]
First input value.
y [number]
Second input value.

Return Value

value [number]
The minimum of x and y.

max

Computes the maximum value of x and y.
local value = Math.max(x, y)

Arguments

x [number]
First input value.
y [number]
Second input value.

Return Value

value [number]
The maximum of x and y.

Trigonometry

radians

Converts the provided angle in degrees to radians.
local value = Math.radians(x)

Arguments

x [number]
Angle in degrees.

Return Value

value [number]
Angle in radians.

degrees

Converts the provided angle in radians to degrees.
local value = Math.degrees(x)

Arguments

x [number]
Angle in radians.

Return Value

value [number]
Angle in degrees.

sin

Calculates the sine of the provided angle.
local value = Math.sin(x)

Arguments

x [number]
Angle in radians.

Return Value

value [number]
The sine of the angle.

asin

Calculates the arc sine of the provided value.
local value = Math.asin(x)

Arguments

x [number]
Value in [-1, 1].

Return Value

value [number]
The arc sine in radians.

cos

Calculates the cosine of the provided angle.
local value = Math.cos(x)

Arguments

x [number]
Angle in radians.

Return Value

value [number]
The cosine of the angle.

acos

Calculates the arc cosine of the provided value.
local value = Math.acos(x)

Arguments

x [number]
Value in [-1, 1].

Return Value

value [number]
The arc cosine in radians.

tan

Calculates the tangent of the provided angle.
local value = Math.tan(x)

Arguments

x [number]
Angle in radians.

Return Value

value [number]
The tangent of the angle.

atan

Calculates the arc tangent of the provided angle.
local value = Math.atan(x)

Arguments

x [number]
Input value.

Return Value

value [number]
The arc tangent in radians.

atan2

Calculates the arc tangent of y/x in radians.
local value = Math.atan2(y, x)

Arguments

y [number]
Proportion of the y-coordinate.
x [number]
Proportion of the x-coordinate.

Return Value

value [number]
The arc tangent of y/x in radians.

Interpolation

lerp

Linearly interpolates between the provided input values.
local value = Math.lerp(x, y, a)

Arguments

Start of the interpolation range.
End of the interpolation range.
a [number]
Fraction used to interpolate between x and y.

Return Value

value [number, Vec2, Vec3, Vec4]
The interpolated result.

slerp

Spherically interpolates between the provided input values. Useful for interpolating between quaternion-based orientations at constant speed.
local value = Math.slerp(x, y, a)

Arguments

x [Quat]
First interpolant.
y [Quat]
Second interpolant.
a [number]
Fraction used to interpolate between x and y.

Return Value

value [Quat]
The interpolated result.

Vector Math

vec_get_component

Retrieves the component of the vector for the given index.
local value = Math.vec_get_component(vec, idx)

Arguments

vec [Vec2, Vec3, Vec4]
The vector to retrieve the component from.
idx [number]
The index of the component to retrieve.

Return Value

value [number]
The value of the vector's component for the given index.

vec_mul

Multiplies the provided vectors.
local value = Math.vec_mul(x, y)

Arguments

x [Vec2, Vec3, Vec4]
The first vector.
The second vector.

Return Value

value [Vec2, Vec3, Vec4]
The product of the operation.

vec_scale

Scales the provided vector by the given scalar value.
local value = Math.vec_scale(s, vec)

Arguments

s [number]
The scalar value the vector is scaled by.
vec [Vec2, Vec3, Vec4]
The vector to scale.

Return Value

value [Vec2, Vec3, Vec4]
The scaled vector.

vec_div

Divides the first vector by the second vector.
local value = Math.vec_div(x, y)

Arguments

x [Vec2, Vec3, Vec4]
The first vector.
y [Vec2, Vec3, Vec4]
The second vector.

Return Value

value [Vec2, Vec3, Vec4]
The quotient of the operation.

vec_add

Adds the second vector to the first vector.
local value = Math.vec_add(x, y)

Arguments

x [Vec2, Vec3, Vec4]
The first vector.
y [Vec2, Vec3, Vec4]
The second vector.

Return Value

value [Vec2, Vec3, Vec4]
The summand of the operation.

vec_sub

Subtracts the second vector from the first vector.
local value = Math.vec_sub(x, y)

Arguments

x [Vec2, Vec3, Vec4]
The first vector.
y [Vec2, Vec3, Vec4]
The second vector.

Return Value

value [Vec2, Vec3, Vec4]
The difference of the operation.

vec_length

Returns the length of the provided vector.
local value = Math.vec_length(vec)

Arguments

vec [Vec2, Vec3, Vec4]
The vector used for calculating the length.

Return Value

value [Vec2, Vec3, Vec4]
The length of the provided vector.

vec_length2

Returns the squared length of the provided vector. More efficient when only comparing lengths.
local value = Math.vec_length2(vec)

Arguments

vec [Vec2, Vec3, Vec4]
The vector used for calculating the length.

Return Value

value [Vec2, Vec3, Vec4]
The squared length of the provided vector.

vec_distance

Returns the distance between the two provided points in space.
local value = Math.vec_distance(x, y)

Arguments

x [Vec2, Vec3, Vec4]
The first position in space.
y [Vec2, Vec3, Vec4]
The second position in space.

Return Value

value [Vec2, Vec3, Vec4]
The distance between the two provided points.

vec_distance2

Returns the squared distance between the two provided points in space. More efficient when only comparing distances.
local value = Math.vec_distance2(x, y)

Arguments

x [Vec2, Vec3, Vec4]
The first position in space.
y [Vec2, Vec3, Vec4]
The second position in space.

Return Value

value [Vec2, Vec3, Vec4]
The squared distance between the two provided points.

vec_normalize

Normalizes the provided vector.
local value = Math.vec_normalize(x)

Arguments

x [Vec2, Vec3, Vec4]
The vector to normalize.

Return Value

value [Vec2, Vec3, Vec4]
The normalized vector.

vec_dot

Calculates the dot product of the provided vectors.
local value = Math.vec_dot(x, y)

Arguments

x [Vec2, Vec3, Vec4]
The first vector.
y [Vec2, Vec3, Vec4]
The second vector.

Return Value

value [number]
The dot product of both vectors.

vec_cross

Calculates the cross product of the provided vectors.
local value = Math.vec_cross(x, y)

Arguments

x [Vec3]
The first vector.
y [Vec3]
The second vector.

Return Value

value [Vec3]
The cross product of both vectors.

Quaternion Math

quat_mul

Multiplies the provided quaternions.
local value = Math.quat_mul(x, y)

Arguments

x [Quat]
The first quaternion.
y [Quat]
The second quaternion.

Return Value

value [Quat]
The product of both quaternions.

quat_rotate

Rotates the provided three-component vector using the given quaternion.
local value = Math.quat_rotate(quat, vec)

Arguments

quat [Quat]
The quaternion used for the rotation.
vec [Vec3]
The vector to rotate.

Return Value

value [Vec3]
The rotated three-component vector.

quat_inverse

Computes the inverse of the provided quaternion.
local value = Math.quat_inverse(quat)

Arguments

quat [Quat]
The quaternion to invert.

Return Value

value [Quat]
The inverse of the provided quaternion.

quat_normalize

Normalizes the provided quaternion.
local value = Math.quat_normalize(quat)

Arguments

quat [Quat]
The quaternion to normalize.

Return Value

value [Quat]
The normalized quaternion.

quat_look_at

Generates a look at quaternion using the provided direction and up vector.
local value = Math.quat_look_at(dir, up)

Arguments

dir [Vec3]
The direction to look in.
up [Vec3]
The up vector.

Return Value

value [Quat]
The look at quaternion for the provided direction and up vector.

quat_from_angle_axis

Generates a quaternion from the provided axis rotation.
local value = Math.quat_from_angle_axis(angle, axis)

Arguments

angle [number]
The angle of the rotation in radians.
axis [Vec3]
The axis to rotate around.

Return Value

value [Quat]
The quaternion for the provided axis rotation.

quat_to_euler_angles

Derives the Euler angles from the provided quaternion.
local value = Math.quat_to_euler_angles(quat)

Arguments

quat [Quat]
The quaternion to derive the Euler angles from.

Return Value

value [Vec3]
The Euler angles [pitch, yaw, roll] derived from the quaternion.

quat_from_euler_angles

Derives a quaternion from the provided Euler angles.
local value = Math.quat_from_euler_angles(euler)

Arguments

euler [Vec3]
The Euler angles [pitch, yaw, roll] to derive the quaternion from.

Return Value

value [Quat]
The quaternion derived from the Euler angles.

quat_rotation

Computes a quaternion describing a rotation from vector x to vector y.
local value = Math.quat_rotation(x, y)

Arguments

x [Vec3]
The first vector.
y [Vec3]
The second vector.

Return Value

value [Quat]
The quaternion describing a rotation from x to y.

Random

rand_uint

Generates a random unsigned integer.
local value = Random.rand_uint()

Arguments

none

Return Value

value [number]
Random unsigned integer value.

rand_float

Generates a random float in [0.0, 1.0].
local value = Random.rand_float()

Arguments

none

Return Value

value [number]
Random floating point value.

rand_float_min_max

Generates a random float in [min, max].
local value = Random.rand_float_min_max(min, max)

Arguments

min [number]
The smallest random float to generate.
max [number]
The largest random float to generate.

Return Value

value [number]
Random floating point value in [min, max].

Input

get_key_state

Gets the state of the given key.
local value = Input.get_key_state(key, player_id)

Arguments

key [number]
The key to retrieve the state from.
player_id [number]
The player id to retrieve the state from.

Return Value

value [number]
The current state of the given key.

get_axis_state

Gets the state of the given axis.
local value = Input.get_axis_state(axis, player_id)

Arguments

axis [number]
The axis to retrieve the state from.
player_id [number]
The player id to retrieve the state from.

Return Value

value [number]
The current state of the given axis mapped to [-1, 1].

get_mouse_pos

Gets the position of the mouse.
local value = Input.get_mouse_pos()

Arguments

none

Return Value

value [Vec2]
The position of the mouse in pixels.

get_mouse_pos_viewport

Gets the position of the mouse mapped to viewport coordinates.
local value = Input.get_mouse_pos_viewport()

Arguments

none

Return Value

value [Vec2]
The position of the mouse relative to the viewport (mapped to [0, 1]).

get_mouse_pos_relative

Gets the delta position of the mouse (calculated as current_mouse_pos - previous_mouse_pos).
local value = Input.get_mouse_pos_relative()

Arguments

none

Return Value

value [Vec2]
The position delta in pixels.

request_mouse_cursor

Requests the hardware mouse cursor to be shown. Has to be called every frame to keep the mouse cursor visible.
Input.request_mouse_cursor()

Arguments

none

Return Value

none

Logging

log_info

Logs the given string as information.
Log.log_info(message)

Arguments

message [string]
The message to log.

Return Value

none

log_warning

Logs the given string as a warning.
Log.log_warning(message)

Arguments

message [string]
The message to log.

Return Value

none

log_error

Logs the given string as an error.
Log.log_error(message)

Arguments

message [string]
The message to log.

Return Value

none

Settings

register_or_update_setting

Creates or sets the setting with the given name to the provided value.
Settings.register_or_update_setting(name, value)

Arguments

name [string]
The name of the setting.
value [number, boolean]
The value to set.

Return Value

none

find_setting_bool

Gets the setting with the given name (as a bool).
local value = Settings.find_setting_bool(name)

Arguments

name [string]
The name of the setting to retrieve from.

Return Value

value [boolean]
The value of the setting.

find_setting_float

Gets the setting with the given name (as a float).
local value = Settings.find_setting_float(name)

Arguments

name [string]
The name of the setting to retrieve from.

Return Value

value [boolean]
The value of the setting.

find_setting_uint

Gets the setting with the given name (as an unsigned integer).
local value = Settings.find_setting_uint(name)

Arguments

name [string]
The name of the setting to retrieve from.

Return Value

value [number]
The value of the setting.

Refs

is_valid

Returns true if the provided ref is valid.
local value = Ref.is_valid(ref)

Arguments

ref [Ref]
The ref to check.

Return Value

value [boolean]
True if the provided ref is valid.

get_id

Gets the id of the provided ref.
local value = Ref.get_id(ref)

Arguments

ref [Ref]
The ref to retrieve from.

Return Value

value [number]
The id of the provided ref.

get_type_id

Gets the type id of the provided ref.
local value = Ref.get_type_id(ref)

Arguments

ref [Ref]
The ref to retrieve from.

Return Value

value [number]
The type id of the provided ref.

Names

is_valid

Returns true if the given name is valid (not empty).
local value = Name.is_valid(name)

Arguments

name [string]
The name to check.

Return Value

value [Ref]
True if the given names are valid (and not empty).

equal_to

Returns whether the names are equal - or not.
local value = Name.equal_to(a, b)

Arguments

a [Name]
The first name to compare.
b [Ref]
The second name to compare.

Return Value

value [boolean]
True if both names are equal.

Physics

sweep_sphere

Performs a sphere sweep test from the given position into the provided direction. Great for doing intersection tests for fast moving objects, like, e.g., projectiles.
local hit, pos, normal, ref = Physics.sweep_sphere(p, r, dir, dist)

Arguments

p [Vec3]
The position to start the sweep at.
r [number]
The radius of the sphere to sweep with.
dir [Vec3]
The direction to sweep in.
dist [number]
The distance to sweep.

Return Value

hit [boolean]
Whether the sweep test hit something - or not.
pos [Vec3]
The position of the hit.
normal [Vec3]
The normal of the hit.
ref [Ref]
The ref referencing the component responsible for the hit.

raycast

Performs a raycast from the given position into the provided direction.
local hit, pos, normal, ref = Physics.raycast(origin, dir, dist)

Arguments

origin [Vec3]
The starting position (origin) of the ray.
dir [Vec3]
The direction of the ray.
dist [number]
The maximum distance the ray can travel.

Return Value

hit [boolean]
Whether the raycast hit something - or not.
pos [Vec3]
The position of the hit.
normal [Vec3]
The normal of the hit.
ref [Ref]
The ref referencing the component responsible for the hit.

World

get_root_node

Returns the root node of the current world.
local value = World.get_root_node()

Arguments

none

Return Value

value [Ref]
The root node of the current world.

load_world

Loads the world with the given name replacing the current world.
World.load_world(name)

Arguments

name [string]
The name of the world to load.

Return Value

none

spawn_prefab

Spawns the prefab with the given name.
local value = World.spawn_prefab(name)

Arguments

name [string]
The name of the prefab to spawn.

Return Value

value [Ref]
The root node of the loaded prefab.

calc_mouse_ray

Helper function to calculate a ray starting at the current camera's position towards the projected position of the mouse cursor.
local origin, pos = World.calc_mouse_ray()

Arguments

none

Return Value

origin [boolean]
The origin of the ray (current position of the camera).
pos [Vec3]
The direction of the ray (towards the current position of the mouse).

radius_damage

Applies radius damage at the given position for explosion type effects.
World.radius_damage(pos, radius, shade_crater)

Arguments

pos [Vec3]
The world space position to apply the explosion at.
radius [number]
The radius of the explosion.
shade_crater [boolean]
Whether the crater of the explosion should be shaded.

Return Value

none

Particle System

spawn_particle_emitter

Spawns the particle emitter with a certain particle effect at the given position for the provided time.
local value = ParticleSystem.spawn_particle_emitter(effect_name, position, lifetime_in_seconds, adjust_spawnrate)

Arguments

effect_name [string]
The name of the particle effect to use.
position [Vec3]
The position to spawn the emitter at (in world space).
lifetime_in_seconds [number]
How long the emitter should live (in seconds).
adjust_spawnrate [boolean]
Whether the spawnrate should be adjusted to the lifetime.

Return Value

The handle of the emitter.

set_spawn_rate

Updates the spawn rate of the provided particle emtiter.
ParticleSystem.set_spawn_rate(emitter_handle, spawn_rate)

Arguments

emitter_handle [EmitterHandle]
The handle of the emitter to update.
spawn_rate [float]
The new spawn rate to set.

Return Value

none

Debug Geometry

draw_line

Draws a line with the given color.
DebugGeometry.draw_line(pos0, pos1, color, always_in_front)

Arguments

pos0 [Vec3]
The starting position of the line.
pos1 [Vec3]
The end position of the line.
color [Vec4]
The color of the line.
always_in_front [boolean]
Keep in front of all other objects in the scene.

Return Value

none

draw_sphere

Draws a sphere with the given radius and color.
DebugGeometry.draw_sphere(center, radius, color, always_in_front)

Arguments

center [Vec3]
The center of the sphere.
radius [number]
The radius of the sphere.
color [Vec4]
The color of the sphere.
always_in_front [boolean]
Keep in front of all other objects in the scene.

Return Value

none

Entities

get_type_id

Gets the type id for entities.
local value = Entity.get_type_id()

Arguments

none

Return Value

value [number]
The type id for entities.

is_alive

Returns whether the referenced entity is still alive - or not.
local value = Entity.is_alive(entity)

Arguments

entity [Ref]
The ref of the entity.

Return Value

value [boolean]
True if the entity referenced is alive.

get_name

Retrieves the name of the given entity.
local value = Entity.get_name(entity)

Arguments

entity [Ref]
The ref of the entity.

Return Value

value [string]
The name of the entity.

find_first_entity_with_name

Returns the first entity found in the world with the given name.
local value = Entity.find_first_entity_with_name(name)

Arguments

name [string]
The name of the entity to retrieve.

Return Value

value [Ref]
The entity with the given name. Returns an invalid ref if not found.

find_entities_with_name

Returns an array with all entities matching the given name.
local value = Entity.find_entities_with_name(name)

Arguments

name [string]
The name of the entities to retrieve.

Return Value

value [table]
List of entities with the given name.

Node Components

create

Creates a new node component and entity and attaches it to the root node of the current world.
Node.create(name)

Arguments

name [Ref]
The name of the node.

Return Value

none

create

Creates a new node component and entity and attatches it to the provided node.
Node.create(parent_node, name)

Arguments

parent_node [Ref]
The node to attach the new node to.
name [Ref]
The name of the node.

Return Value

none

destroy

Destroys the given node and its whole hierarchy, including all components and entities attached to it and its children.
Node.destroy(node)

Arguments

node [Ref]
The node to destroy.

Return Value

none

get_position

Gets the local position of the given node component.
local value = Node.get_position(node)

Arguments

node [Ref]
The node component to retrieve from.

Return Value

value [Vec3]
The local position of the given node component.

get_world_position

Gets the world position of the given node component.
local value = Node.get_world_position(node)

Arguments

node [Ref]
The node component to retrieve from.

Return Value

value [Vec3]
The world position of the given node component.

get_orientation

Gets the orientation of the given node component.
local value = Node.get_orientation(node)

Arguments

node [Ref]
The node component to retrieve from.

Return Value

value [Quat]
The orientation of the given node component.

get_world_orientation

Gets the world orientation of the given node component.
local value = Node.get_world_orientation(node)

Arguments

node [Ref]
The node component to retrieve from.

Return Value

value [Quat]
The world orientation of the given node component.

set_position

Sets the local position of the given node component.
Node.set_position(node, position)

Arguments

node [Ref]
The node component to modify.
position [Vec3]
The local position to set.

Return Value

none

set_world_position

Sets the world position of the given node component by reversing the world transform of the parent node. Can be used to move the node to a fixed world position, regardless of its hierarchy.
Node.set_world_position(node, position)

Arguments

node [Ref]
The node component to modify.
position [Vec3]
The world position to set.

Return Value

none

set_orientation

Sets the local orientation of the given node component.
Node.set_orientation(node, position)

Arguments

node [Ref]
The node component to modify.
position [Quat]
The local orientation to set.

Return Value

none

set_world_orientation

Sets the world orientation of the given node component by reversing the world transform of the parent node. Can be used to set the node to a fixed world orientation, regardless of its hierarchy.
Node.set_world_orientation(node, orientation)

Arguments

node [Ref]
The node component to modify.
orientation [Quat]
The world orientation to set.

Return Value

none

set_size

Sets the local size of the given node component.
Node.set_size(node, size)

Arguments

node [Ref]
The node component to modify.
size [Vec3]
The local size to set.

Return Value

none

update_transforms

Updates the world transforms of the given node and all its child nodes. Has to be called to make any changes to the node visible.
Node.update_transforms(node)

Arguments

node [Ref]
The root node component to update.

Return Value

none

Tag Components

get_type_id

Gets the type id for the given component.
local value = Tag.get_type_id()

Arguments

none

Return Value

value [number]
The type id for node components.

is_alive

Returns whether the referenced component is alive - or not.
local value = Tag.is_alive(comp)

Arguments

comp [Ref]
The ref of the node component.

Return Value

value [boolean]
True if the node component referenced is alive.

get_entity

Returns the component's entity.
local value = Tag.get_entity(comp)

Arguments

comp [Ref]
The component to retrieve from.

Return Value

value [Ref]
The entity this node component is attached to.

get_component_for_entity

Gets the component of the provided entity.
local value = Tag.get_component_for_entity(comp)

Arguments

comp [Ref]
The Ref of the entity.

Return Value

value [Ref]
The ref of the component of the provided entity. Returns an invalid ref if none is found.

find_entities_with_tag

Returns an array of all available entities with matching tags.
local value = Tag.find_entities_with_tag(tag)

Arguments

tag [string]
The tag to match.

Return Value

value [table]
List of entities with matching tag components.

Character Controller Components

get_type_id

Gets the type id for the given component.
local value = CharacterController.get_type_id()

Arguments

none

Return Value

value [number]
The type id for node components.

is_alive

Returns whether the referenced component is alive - or not.
local value = CharacterController.is_alive(comp)

Arguments

comp [Ref]
The ref of the node component.

Return Value

value [boolean]
True if the node component referenced is alive.

get_entity

Returns the component's entity.
local value = CharacterController.get_entity(comp)

Arguments

comp [Ref]
The component to retrieve from.

Return Value

value [Ref]
The entity this node component is attached to.

get_component_for_entity

Gets the component of the provided entity.
local value = CharacterController.get_component_for_entity(comp)

Arguments

comp [Ref]
The Ref of the entity.

Return Value

value [Ref]
The ref of the component of the provided entity. Returns an invalid ref if none is found.

move

Moves the character controller by the provided vector.
CharacterController.move(cct, move)

Arguments

cct [Vec3]
The character controller to move.
move [Vec3]
The move vector.

Return Value

none

Types

This section lists the detailed description of all types made available via the Lua scripting interface. Class-like structures are almost exlusively PODs (plain old data) and do not, besides the constructor, expose member functions. To quickly find and jump to a type, please use the overview section above.

Vector Math

Vec2

Vector type with two components.
--Example of Vec2's member variable layout as a Lua table local value = { x = nil, y = nil }

Constructors

Vec2(x [Vec2, number])
Initializes all components of the vector to the provided parameter.
Vec2(x [number], y [number])
Initializes the x and y components to the provided values.

Members

x [number]
The x component of this vector.
y [number]
The y component of this vector.

Vec3

Vector type with three components.
--Example of Vec3's member variable layout as a Lua table local value = { x = nil, y = nil, z = nil }

Constructors

Vec3(x [Vec3, number])
Initializes all components of the vector to the provided parameter.
Vec3(x [number], y [number], z [number])
Initializes the x, y, and z components to the provided values.

Members

x [number]
The x component of this vector.
y [number]
The y component of this vector.
z [number]
The z component of this vector.

Vec4

Vector type with four components.
--Example of Vec4's member variable layout as a Lua table local value = { x = nil, y = nil, z = nil, w = nil }

Constructors

Vec4(x [Vec4, number])
Initializes all components of the vector to the provided parameter.
Vec4(x [number], y [number], z [number], w [number])
Initializes the x, y, z, and w components to the provided values.

Members

x [number]
The x component of this vector.
y [number]
The y component of this vector.
z [number]
The z component of this vector.
w [number]
The w component of this vector.

Quaternion Math

Quat

A quaternion with four components.
--Example of Quat's member variable layout as a Lua table local value = { w = nil, x = nil, y = nil, z = nil }

Constructors

Quat(quat [Quat])
Initializes all components of the quaternion to the provided parameter.
Quat(w [number], x [number], y [number], z [number])
Initializes the w, x, y, and z components to the provided values.

Members

w [number]
The x component of this quaternion.
x [number]
The y component of this quaternion.
y [number]
The z component of this quaternion.
z [number]
The w component of this quaternion.

Refs

Ref

A reference to entities, components or resources. Refs are only returned by functions and can then be used to, e.g., interact with a created node.

Names

Name

A name can be initialized from a string and supports fast comparison with other names (using integer instead of string comparisons internally).

Constructors

Name()
Initializes an invalid/empty name.
Name(name [string])
Initializes a new name from a string.
Name(name [Name])
Initializes this name from another name.

Particle System

EmitterHandle

Handle used to reference particle emitters.

Get IOLITE

Become a Supporter
Supporters Area

Get in Touch

Public Relations

Press Kit

News and Blog

Development Blog
© 2023 Missing Deadlines. All rights reserved.