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

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.

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