Cubos Engine - Release

Release 0.7

2025-06-19T00:00:00+01:00

New 0.7 Features

This blog post covers the most important changes, but you can check out the full changelog in our repository.

On the Engine

Overhauled ImGui Inspector with Hook Support (@RiscadoA)

Before 0.7, to inspect a Cubos value in the ImGui inspector, you used the DataInspector resource. This resource provided methods to show and edit types through ImGui, but had no state whatsoever, which was a bit counterintuitive. Additionally, it was not possible to externally override the behavior of the inspector, which made it impossible to customize the way certain types were displayed or edited. This meant that, for instance, if the game developer wanted to display a custom UI on the inspector for a component of theirs, it would not be possible.

This previous implementation was replaced by a new ImGuiInspector system argument. This can be used in any ImGui system. For example:

cubos.system("inspect all velocities")
     .tagged(imguiTag)
     .call([](Query<Entity, Velocity&> velocities, ImGuiInspector inspector) {
        for (auto [ent, velocity] : velocities) {
            inspector.edit(velocity, "Velocity of " + std::to_string(ent));
        }
     });

This new inspector allows overriding its behavior for specific types by using the ImGuiInspector::hook method. This paved the way for us to enhance the inspector with new features such as displaying quaternions as Euler angles, breaking down matrices into translation, rotation and scale, and more. Additionally, support was added for mask and enum types using their respective reflection traits.

Distance Physics Constraint (@joaomanita)

In version 0.7, we began adding physics constraints that users can set and customize. Previously, only the penetration constraint was available, which was used exclusively for collision solving. For now, we've added the distance constraint, which ensures either a fixed distance between two physics bodies, or a distance range (similar to a rope). To add this constraint:

commands.relate(ent1, ent2,
                    DistanceConstraint{.isRigid = false,
                                       .minDistance = 0.0F,
                                       .maxDistance = 5.0F,
                                       .localAnchor1 = {0.0F, 0.0F, 0.0F},
                                       .localAnchor2 = {0.0F, 0.0F, 0.0F}});

commands.relate(ent1, ent2,
                    DistanceConstraint{.isRigid = true,
                                       .fixedDistance = 5.0F,
                                       .localAnchor1 = {0.0F, 0.0F, 0.0F},
                                       .localAnchor2 = {0.0F, 0.0F, 0.0F}});

Where isRigid indicates whether it's a fixed distance or a range constraint, and the local anchor values specify the points on each body where the constraint is applied.

Voxel Mesh Frustum Culling (@mkuritsu)

In this release we used the intersection utilities from the previous release to perform frustum culling on rendered voxel meshes. Previously, every voxel mesh loaded into the engine would have its data sent to the GPU for rendering, regardless of whether they were visible. This resulted in wasted resources, and that's exactly what this feature addresses. With frustum culling, only meshes within the camera's visible area are sent to the GPU for drawing, while others are ignored, potentially improving performance in scenes with a large number of objects.

Frustum culling is performed automatically with any type of camera—whether it's an OrthographicCamera or a PerspectiveCamera. This means no manual intervention is required to benefit from it. Additionally, a debug option has been added to the Camera component, allowing you to freeze (stop) updates to the camera's frustum, keeping it in the last calculated state.

AABB and Collider Rework (@fallenatlas)

In this release, we began reworking the Colliders to make them more streamlined and easier to understand. Previously, we had the Collider component, which contained the AABB of the Collision Shape as well as a transform to apply an offset to the AABB. This component has now been renamed to ColliderAABB to clarify its purpose, and the transform has been removed, as it only affected the AABB and not the collision shape itself.

A Collider now represents the owner entity of a collision shape. This distinction is important, as we plan to support collision shapes composed of multiple shapes from child entities of the owner entity. We need an easy way to distinguish them in the hierarchy. The offset of collision shapes will be determined by the entity's transform when the collision shape is part of a child entity. Otherwise, it is assumed to be centered. This functionality has not been implemented yet, but will begin rolling out in future releases.

Additionally, we now automatically add the ColliderAABB when a collision shape is added.

Voxel Shape Inertia (@fallenatlas)

Up until now, we had voxel shapes that collided with each other and with boxes. However, the inertia matrix for these shapes was calculated based on the size of the voxel grid, which led to inaccuracies, particularly for shapes with many empty spaces. Now, we use a custom algorithm that treats each voxel as a point and sums the inertia for each point, relative to the center of mass, to compute the total inertia matrix. Currently, we only support uniform density, meaning each point has a mass equal to the total mass divided by the number of occupied voxels in the grid. You can check the implementation of the functions defined here for more details.

One important note is that, while we calculate the inertia tensor for this shape, we do not guarantee it will be symmetric, even though it should be by definition. The matrix is guaranteed to be symmetric only when the shape itself is symmetric. However, in all cases, it’s possible to obtain a symmetric matrix by finding the principal axis of inertia. This is a minor optimization that makes the inertia more readable, though it's not a priority.

New Scene Format (@RiscadoA)

With the introduction of relations in the ECS, particularly the ChildOf relation, hierarchies became essential in Cubos scenes. This posed a problem, as the previous scene format didn’t have an intuitive way to represent hierarchies—scenes were simply flat lists of entities with no parent-child relationships. To address this, we designed a new scene format where each scene is a JSON file describing an entity, its components and relations, as well as its children, recursively. It looks like this:

{
    "inherit": "ba19170e-65a0-47cd-9bd2-b4ea9447fe22",
    "game::Player": {},
    "#camera": {
        "cubos::engine::PerspectiveCamera": {
            "fovY": 90,
        }
    },
    "#gun": {
        "inherit": "6cb09eea-4156-4a75-b0ae-488aac843e05"
    }
}

This scene represents an entity that inherits from another scene with the ID ba19170e-65a0-47cd-9bd2-b4ea9447fe22, meaning we're modifying an existing scene.``` To this base entity, a game::Player component and two child entities, camera and gun, are added. The camera entity also receives a cubos::engine::PerspectiveCamera component, with a field fovY set to 90, and the gun entity inherits from another scene, with the ID 6cb09eea-4156-4a75-b0ae-488aac843e05.

This format is much more flexible than the previous one, as it allows us to easily expand upon existing scenes by inheriting from them, while also representing hierarchies in a natural way. The inheritance system has been especially useful in our recent demos, such as for setting different player skins by inheriting from a base player scene and overriding the models used.

Custom ImGui Styling (@RiscadoA)

In this release we've finally customized the ImGui theme colors and font to match the Cubos brand guidelines. This change makes the engine's tools UI look more professional and consistent with the overall look of our website and brand.

Optional Render Picker (@tomas7770)

In the previous release's blog post, we discussed some of the major performance bottlenecks in the graphics renderer. One of them was SSAO, which was made optional to allow disabling it on lower-end devices. The other was the render picker.

Although work to make the render picker optional had already started, it wasn’t completed due to deadline constraints and some lingering bugs.

With this release, it's now possible to remove the RenderPicker component from a render target without breaking the graphics system. While this disables certain features, such as selecting entities with the mouse cursor, in most cases, those features aren't crucial, and the performance cost of render picking is too high to ignore.

On one particular machine, disabling render picking in our Airships demo running at 1080p on integrated graphics resulted in a jump from 30 FPS to nearly 60 FPS! This shows how this change makes it much more feasible to run Cubos games on lower-end hardware.

Center Render Voxel Pivot (@kuukitenshi)

Previously, the pivot point for voxel rendering was at the bottom-left corner of each voxel grid. Now, it’s at the center!

This change makes aligning voxel meshes with other entities much easier, as there's no longer a need to manually adjust offsets.

On the Core

Math Vector Reflection Trait (@RiscadoA)

One issue that had been bothering us for a while was the lack of proper support for math types in the reflection system. This led to the serialization and inspector systems being unaware of them, treating them as simple structs. To address this, we've added a new reflection trait, VectorTrait, which identifies types that represent math vectors, such as all the glm vector types.

Entity Destruction Observers (@kuukitenshi)

Previously, detecting when an entity was being destroyed required manually checking its destruction state. Now, we have an observable for entity destruction that triggers automatically when an entity is destroyed.

This makes handling such events easier, as we can now simply register a callback that’s invoked upon destruction. It’s especially useful for cleaning up resources or performing actions across systems without needing to repeatedly check if an entity is being destroyed.

Query Match Counting (@GalaxyCrush)

Previously, to count matches in queries, we had to use a for loop to count them after the query was executed.

Now we added a new count method to the Query class, which directly returns the number of matches in the query, eliminating the need for a separate loop outside the class.

Wrapper Reflection Trait (@SrGesus, @RiscadoA)

A recurring pattern in our codebase are single field wrapper structs, such as Position, Rotation and Scale. We use these types to give meaning to the data they contain (in this case, math vectors and quaternions), and to distinguish them in the Entity Component System. To reflect these types, we previously relied the FieldsTrait, as it describes struct like types.

When reflection consumers such as the JSON serializer interacted with these types, they would usually treat FieldsTrait types with a single field as wrappers. In the case of JSON, this led to shorter more readable output, e.g., instead of:

"cubos::engine::Position": {
    "vec": {
        "x": 1.0,
        "y": 2.0,
        "z": 3.0
    }
}

It would just output:

"cubos::engine::Position": {
    "x": 1.0,
    "y": 2.0,
    "z": 3.0
}

However, this behavior became problematic, as not all struct types with a single field should be treated as wrappers. For instance, the cubos::engine::PerspectiveCamera component holds a single field fovY. Thus, when serialized to JSON, it would output:

"cubos::engine::PerspectiveCamera": 90.0

This, of course, is not readable at all. Even worse, if someone were to add a new field to the PerspectiveCamera component, it would break the serialization format. image the component now has a new field called farClip. How would the JSON deserializer know how to deserialize the above JSON?

To prevent issues like these while still allowing the wrapper behavior for single field structs, we introduced a new reflection trait called WrapperTrait. FieldsTrait types with single fields are now no longer automatically treated as wrappers, and instead, only types with the WrapperTrait will be serialized in the shorter format.

On the Tools

Auto-scroll Toggle on the Console (@R-Camacho)

Previously, we had to scroll manually to view the latest debug messages in the console.

Now, a new checkbox allows us toggle auto-scroll. When enabled, the console will automatically scroll to display the most recent messages as they appear.

Next Steps

On the next release we'll be introducing a Lua scripting plugin, backed by C API bindings to Cubos. Our goal is to be able to host a game jam focused on our engine by October 2025, and we believe that having a scripting language will be essential for that.

As usual, one of the focus areas of the team is improving the tooling. The tools team has received a great influx of new contributors, and we're excited to see what they will bring to the table.

You can check out the full list of things we want to get done in the milestone for the next release.

Release 0.6

2025-03-12T00:00:00+00:00

New 0.6 Features

This blog post covers the most important changes, but you can check out the full changelog in our repository.

On the Engine

Physics with Warm-Starting (@fallenatlas)

Continuing the work from the previous release, we finished warm-starting for our physics simulation. Warm-starting uses the information stored in the contact manifold between two bodies, especially the total impulses applied to each contact point in the previous frame, and applies it before solving begins. It works based on the assumption that the impulses applied in the previous frame are a good estimate for the impulses that will also be applied in the current frame. Therefore, by applying them to the body before solving the collision constraint, the body should already be closer to its ideal position. Over time, these impulses will stabilize (since our solver is a "dirty" solver), resulting in less jitter. This is particularly effective for stacks of bodies, where the bodies push against each other, creating instability. However, if they're already closer to their ideal position, this instability will be reduced. With warm-starting, we can stack more bodies, and when the stack isn't fully stable, it stays together for longer.

Here you can see how, in our complex physics sample, the stack holds for much longer than before, although it still falls in the end.

However, if we increase our physics update rate to 60 times per second (rather than our current 30), and the substeps performed in each update to 8 (instead of our current 4), we can see that a stack of 8 blocks holds mostly stable.

Unfortunately, our collisions are not optimized to the point where we can have 60 updates per second with many bodies, but the door is open for this upgrade in the future!

Toggleable SSAO and Resolution Scale (@tomas7770)

Some time ago, we profiled Cubos's graphics engine to determine the main performance bottlenecks. SSAO stood out as the graphics plugin that took the most frame time. However, due to the way the rendering pipeline was implemented, disabling it to get better performance wasn't possible without breaking rendering altogether. Starting with this release, the SSAO component can be removed from a render target to disable this feature.

In addition, we found that other game engines often default to rendering SSAO textures at half the width/height of the screen resolution, which greatly improves performance without major loss in quality. To implement this, we added a resolution scale option to the SSAO component, which defaults to 0.5, but can be set to any value up to 2.0.

Conditional Shader Compilation (@tomas7770)

Another major bottleneck in the graphics renderer is the render picker, which allows finding out which entity is visible at a given pixel. As explained in the Modular Renderer section of the 0.2 blog post, we attempted to mitigate performance loss with Pixel Buffers and double-buffering. But despite this, it remains a demanding feature.

Just like what happened with SSAO, disabling the render picker wasn't possible. Unlike the former, though, this one required the ability to change shaders' source code at runtime. To solve this, we added new methods to the Shader class to prepend #define macros and recompile the shader.

auto vs = vsAsset->shaderStage(); // unmodified shader
vs = vsAsset->builder().with("RENDER_PICKER").build(); // shader with #define RENDER_PICKER
vs = vsAsset->builder().with("MAX_CSM_SPLITS", "5").build(); // shader with #define MAX_CSM_SPLITS 5

Unfortunately, the actual ability to toggle render picking didn't make it to this release, but it should make it to the next one!

On the Core

Added Frustum geometry and intersection utilities (@mkuritsu)

A new geometry object was added, the frustum, and additionally, two new intersection functions to check if a box or a capsule intersects a frustum. This new geometry utility will be useful for frustum culling in a future release, potentially improving graphics performance when rendering large scenes with Cubos.

New Demo Sneak Peek

We have been working on a new game made with Cubos, and we're excited to share a sneak peek with you! It's a competitive multiplayer game where you and your team pilot an airship and fight against other teams. We plan to implement networked multiplayer, allowing you to play with friends online — this will be a first for Cubos! Stay tuned for more details after the 0.7 release blog post!

Next Steps

In the next release, which should be out by the end of April, we're planning to work on the following features:

A menu bar and a sensible default layout for Tesseratos.
A proper scene editor for Tesseratos.
Automated inertia computation for arbitrary voxel shapes.
Frustum culling when rendering.
Various other performance improvements in the renderer.
Better integration of mouse input with the high-level input system.
And many other new features and bug fixes!

In the meantime, we'll also be participating in the Azul Jam, a game jam happening over the weekend of March 28nd. We're excited to see what we can come up with in just 48 hours! A blog post about our experience will be published sometime after the jam.

You can check out the full list of things we want to get done in the milestone for the next release.

Release 0.5

2025-01-27T00:00:00+00:00

New 0.5 Features

This blog post covers the most important changes in the 0.5 release - we've added a lot of new features, such point light shadows, audio support, MSDF text rendering and more! We've released 0.5 some time ago, but with the exam season and the holidays, we only got around to writing this blog post now. As usual, you can check out the full changelog in our repository.

On the Editor

Hold mode for Debug Camera (@jdbaracho)

For debugging purposes, we have a debug camera which allows the user to move around the scene and inspect it. Previous this camera could only be controlled by locking the camera to the mouse with a toggle. This was inconvenient when also using the mouse to interact with the editor UI, so we added a new mode where the camera can be rotated by holding a key or mouse button (e.g. the middle mouse button).

On the Engine

Point Light Shadows (@tomas7770)

Over the past couple of releases, shadows have been gradually introduced to the engine's graphics renderer, starting with spotlight shadows, and then directional ones. Naturally, the next step was to implement shadows for point lights, finally completing support for the most common types of lights.

Point shadows are enabled by adding a PointShadowCaster component to the light entity. They behave similarly to spot shadows, lacking all the configurable values of the more complex directional shadows. You can read the previous blog posts for more detailed information (0.3, 0.4).

In terms of implementation, point shadows are also very similar to spot shadows, using a shared atlas texture that stores shadow maps for every point light in a quadtree structure. However, because point lights cast light in all directions, there are 6 atlas textures, one for each direction of a cube.

The final result of our shadows engine can be seen in the Shadows sample. Below is a screenshot of the sample with all light types casting shadows. Some tweaks have been done to better highlight the shadows.

Audio Support through the Audio Plugin (@Dageus, @diogomsmiranda)

This release is a significant milestone for the Cubos engine, as it finally introduces Audio functionality!

The new audioPlugin leverages the previously implemented Audio Context to manage audio playback. It introduces two new components:

AudioSource: Attach this component to entities to play audio files in supported formats such as FLAC, MP3 and WAV.
AudioListener: Attach this component to an entity to capture audio from the scene.

With the plugin, you can now register listeners, and control audio sources with play, pause, and stop functionality. You can also customize audio playback by modifying the AudioSource properties for each entity, adjusting settings such as volume, pitch, and looping behavior to tailor the sound to your needs. Due to restrictions in our audio backend, you can only have up to three active listeners at a time. For practical examples of how to use these new audio components (AudioPlay, AudioPause, AudioStop), check out our Audio Sample.

Method to save settings to files (@SrGesus)

The Settings resource was missing some way to interact with its corresponding file, as it was limited to a startup system that would load the file from a command line argument with no way for posterior changes to persist which was inconvenient.

Now there are two new simple methods - save(path, indentation) and load(path) - to save and load the Settings to and from cubos::core::data::FileSystem paths. E.g:

settings.merge(settings.load("/file.json"));
settings.save("/file_backup.json");

Collision detection between VoxelCollisionShapes (@joaomanita)

The engine was only able to able to detect collisons between boxes, now we can add a VoxelCollisionShape to decompose a voxel shape into multiple box collision shapes.

Anti-aliasing using the FXAA technique (@kuukitenshi)

We introduced the FXAA (Fast Approximate Anti-Aliasing) technique to reduce jagged edges in the rendered images. As you can see in the images below, FXAA smooths out the visuals without the performance cost of traditional anti-aliasing methods.

FXAA Off

FXAA On

UI text element using MSDF for text rendering (@mkuritsu)

A significant addition to the Cubos engine was the support for text rendering in the UI, which will greatly improve the capabilities for communicating with the player in future games developed with the engine.

This new features comes in the uiTextPlugin, which includes the UIText component, containing all the data needed to draw text on the screen. The plugin also adds two new asset types:

Font: holds the raw font data to be used to create font atlases (.ttf and .otf files supported).
FontAtlas: maps characters to their glyph on a given font, with different configurable properties.

In order to draw the text on the screen this plugins uses Multi Signed Distante Fields (MSDFs) with the help from msdfgen and msdf-atlas-gen, and FreeType to load different font formats. Below is a screenshot taken from the UI sample available in the engine showcasing the text rendering in action.

Note: Currently only the ASCII charset is supported, UTF-8 support will be added in a future release.

Enable assets to be identified in the code by their file path (@GalaxyCrush)

Assets could only be identified by their UUID, which can be hard to keep track of for human developers. Now, they are able to be identified by their path, thus making them easier to handle when developing projects with Cubos. E.g., you can now do:

Asset<Scene> SceneAsset = AnyAsset("/path/to/asset");

instead of:

Asset<Scene> SceneAsset = AnyAsset("uuid");

Option to use Shadow Normal Offset Bias algorithm (@GalaxyCrush)

We noticed that the shadows had some shadow acne and/or peter panning artifacts in some samples. So, to improve it, we implemented the option of using the Shadow Normal Offset Bias algorithm, which improved the quality of the shadows and reduced these artifacts. To use the algorithm, the user simply has to assign a value to the normalOffsetScale field in the light casters ShadowCaster.

Resource to easily configure constants in the physics solver (@GCeSilva)

The physics solver previously included hardcoded constants, which were not easily accessible or modifiable. A new resource has been added which allows the user to configure these constants, making it easier to tune and debug, even at runtime.

Contact caching for collision between box shapes (@fallenatlas)

We added contact caching as a first step towards implementing warm-starting. Contact caching consists of keeping information about collisions that were happening in the previous physics update so that in the next update we can trace them back. This information includes identifiers for each collision manifold and the corrections applied to each contact point. Due to limitations in the current implementation of collisions between entities, this is currently only supported for box shapes.

On the Core

A Proper CMake Configuration (@RiscadoA)

While functional, our CMake build configuration was incomplete in terms of features and poorly organized. As the engine evolved, we recognized the need to install it as a system-wide library for use in other projects. Before, we always simply added the engine repository as a git submodule in our projects, which required maintaining a local copy of the entire codebase for each project - an inneficient approach. To address this, we decided to clean up the CMake configuration, and add installation and find_package support. As a result, you can now install the whole Cubos project, and to use it in another project, you only need to include the following lines in your CMakeLists.txt:

find_package(cubos REQUIRED)
target_link_libraries(your_game PRIVATE cubos::engine)

One big advantage of this is that we can now also install Quadrados and Tesseratos, the tools we use for making games with Cubos, system-wide, as you would with any other application. As of now, Cubos has only been packaged for NixOS, but we haven't contributed it to the Nixpkgs repository yet. We plan to do so in the future, and also to package it for other distributions.

Web Support with Emscripten (@RiscadoA, @luishfonseca)

We've had a pull request open since 0.2 for porting Cubos to the web with Emscripten, but it was constantly postponed due to some blocking issues being present, and us being focused on other features. Now, we finally made the final push to get it working, and now Cubos can be compiled to WebAssembly and ran in the browser!

This is an important feature, as for game jams, for example, it's handy to be able to share your game with others without them having to download anything, and also to be able to play it on any device. It's a good way to showcase the engine to people who might be interested in using it, but are reluctant to download it. We plan on embedding each sample on their respective documentation page, but that will be left for a future release.

One of the major challenges was guaranteeing compatibility with WebGL2. Fortunately, the rendering code is built on top of a rendering API abstraction layer. We had to make some changes to this layer to guarantee we cover strictly the intersection between the features of OpenGL 3.3 and WebGL2, but we managed to do it without much hassle. As of now, this means we're making some performance sacrifices, as we're not using advanced features even when they're available. We plan to address this in the future.

Next Steps

In the next release, which should be out by February 6th, we're planning to work on the following features:

Toggleable gravity on the physics plugin.
Warm starting in physics solver.
Graphics performance improvements.
Transparent voxel rendering.
Particle system.
Editor UX improvements, making it very useful.
New scene editor.

We also developed a demo showcasing the new features of this release, which you will be able to check out pretty soon here.

You can check out the full list of stuff we want to get done in the milestone for the next release.

Release 0.4

2024-11-05T00:00:00+00:00

New 0.4 Features

This blog post covers the most important changes, but you can check out the full changelog in our repository.

On the Editor

Project Management and Debugging (@RiscadoA)

In this release, we were finally able to make our editor, Tesseratos, a standalone application! Previously, the editor was a part of the engine itself, which meant if you made changes to the game's code, you had to recompile the editor as well, and restart it. Now the editor has its own executable, and through it, you can open projects, edit their assets, and even debug them - all without having to restart the editor when recompiling the game. At this time, the UX is still a bit rough, as we've focused on making it work first.

One major hurdle we had to overcome was how to make the editor aware of the project's data types, such as its components and resources. Before, they were part of the same application, and thus, the editor could simply access them directly. Now, with the editor being a separate application, we needed a way to share this information across different processes. You can read more about it in the "Type Client and Type Server" section at the end of this post, but in short, with the new reflection functionalities, it is now possible to share type data across different processes, through, for example, a socket.

In practice, this means that games made with Cubos can now be launched with a debug flag which makes them act as a server at a given port. Then, the editor is able to connect to this server and extract all of the required debug information. We also make use of this new connection to allow the editor to send debugging commands to the game, such as pausing, resuming, and stepping the game's execution.

So, essentially, we've added two new tools to the editor:

A debugger tool, which allows you to connect to a running game and debug it (pause, resume, step, etc.).
A project manager tool, which allows you to open projects, edit their assets, and launch them.

You can see them in action in the video below:

Voxel Model Importing Tool (@Scarface1809)

In this release, we've added a highly useful plugin to Tesseratos: a Voxel Model Importing Tool. With this new tool, you can now import .qb files directly within the editor, bypassing the need for the external conversion tool Quadrados.

Previously, importing voxel models required converting .qb files into .pal and .grd files using Quadrados, a CLI tool, before they could be used in the engine. Now, with the Voxel Model Importer Plugin, the process has been simplified, acting as an interface to handle the conversion process within the editor.

The tool allows you to:

Assign names to the .pal and .grd files.
Choose the file paths where the .grd files and the .pal file should be saved.
Specify how many .grd files supported by the .qb file you want to import.

With this tool, importing voxel models into your projects is now faster and easier, allowing for a smoother workflow and less reliance on Quadrados.

On the Engine

Physics with Rotation (@fallenatlas)

We have rotation!

Since the start of the physics plugin, we always treated rigid bodies as simple particles. This is because it made the calculations more intuitive, and it reduced the potential amount of mistakes we could make when first starting out. It also made debugging - of penetration solving for example - easier. With the particle behaviour stabilized, we decided it was time to expand the plugin to consider rotation, and for that we had to:

Add Collision Manifold and Collision Points computation.
Add Components for Rotation.
Expand the Integrator and Solver to compute rotations.

Collision Manifold and Collision Points

Previously, since everything was a particle, we simply computed if there was a collision using SAT, which also returned the normal along which the penetration was the smallest, along with that penetration value. For rotations we need a ContactManifold relation, that holds all information about the collision. A Contact Manifold is effectively a 2D polygon that details the surface of contact between the 2 bodies. In computer physics the bodies inter-penetrate each other, which does not happen in the real world. The manifold is the aproximation of the real contact surface the bodies would have. This polygon is described by its vertices, in the form of Contact Points, all of which contain their position and penetration in ContactPointData.

To compute the manifold we use the Sutherland Hodgman algorithm. Our current implementation was mostly inspired by this tutorial, which you can check out, to see how it works.

struct ContactPointData
{
    cubos::core::ecs::Entity entity; ///< Entity to which the normal is relative to.
    glm::vec3 globalOn1;             ///< Position on the entity of the contact in global coordinates.
    glm::vec3 globalOn2;             ///< Position on the other entity of the contact in global coordinates.
    glm::vec3 localOn1;              ///< Position on the entity of the contact in local coordinates.
    glm::vec3 localOn2;              ///< Position on the other entity of the contact in local coordinates.
    float penetration;               ///< Penetration of the contact point. Always positive.
};

struct ContactManifold
{
    cubos::core::ecs::Entity entity;      ///< Entity to which the normal is relative to.
    glm::vec3 normal;                     ///< A contact normal shared by all contacts in this manifold,
                                          ///< expressed in the local space of the first entity.
    std::vector<ContactPointData> points; ///< Contact points of this manifold.
};

With this change, our narrow phase firstly checks for collision with SAT, since it's cheaper, and only then computes the manifold.

The collisions sample was also enhanced so we could visualize this information.

New Components

The next thing to add were Components to support rotations, such as Inertia, Torque, and AngularVelocity, just to name a few. To facilitate the creation of entities with box collision shapes, we also added automatic computation of the inertia tensor for the BoxCollisionShape, which is performed upon adding the Inertia component and every time Mass or the dimentions of the shape are changed.

Expand the Integrator and Solver

The last step was to add rotation in the Integrator and PenetrationConstraint Solving.

The integrator simply takes the AngularImpulse and Torque components and handles them similarly to the linear movement components. We want to note that the Force component also holds a torque vector, in our current design. This is because the method we supply to apply a force on a point of the body belongs to Force, and that method may also apply some torque, if the force isn't aligned with the center of mass. This hidden torque vector is also used in the Integration phase.

struct Force
{
    void addForceOnPoint(glm::vec3 force, glm::vec3 localPoint, glm::vec3 centerOfMass)
    {
        mForce += force;
        mTorque = glm::cross(localPoint - centerOfMass, force);
    }

private:
    glm::vec3 mForce = {0.0F, 0.0F, 0.0F};
    glm::vec3 mTorque = {0.0F, 0.0F, 0.0F};
};

The PenetrationConstraint is now solved for each contact point, using their local anchor for relative velocity, separation, and angular velocity calculation at each step. This involved changing the constraint itself to also have a number of PenetrationConstraintPointData, which are the same as the manifold points but with extra information to keep track of the constraint solving. The constraint is now created when the ContactManifold relation is present between 2 entities, instead of CollidingWith.

struct PenetrationConstraintPointData
{
    float initialSeparation; ///< The separation of the contact point. Negative separation indicates
                             ///< penetration.
    float normalSpeed; ///< The relative velocity of the bodies along the normal at the contact point the begging of
                       ///< the collision.

    glm::vec3 localAnchor1; ///< The local contact point relative to the center of mass of the first body.
    glm::vec3 localAnchor2; ///< The local contact point relative to the center of mass of the second body.

    /// Store fixed world-space anchors.
    /// This improves rolling behavior for shapes like balls and capsules. Used for restitution and friction.
    glm::vec3 fixedAnchor1; ///< The world-space contact point relative to the center of mass of the first body.
    glm::vec3 fixedAnchor2; ///< The world-space contact point relative to the center of mass of the second body.

    // separation
    float normalMass;    ///< Mass to use for normal impulse calculation.
    float normalImpulse; ///< Accumulated impulse for separation.

    // friction
    float frictionMass1;    ///< Mass to use for friction impulse calculation along the first tangent..
    float frictionMass2;    ///< Mass to use for friction impulse calculation along the second tangent..
    float frictionImpulse1; ///< Accumulated impulse for friction along the first tangent.
    float frictionImpulse2; ///< Accumulated impulse for friction along the second tangent.
};

struct PenetrationConstraint
{
    cubos::core::ecs::Entity entity; ///< Entity to which the normal is relative to.
    glm::vec3 normal;                ///< Normal of contact on the surface of the entity.
    float friction;                  ///< Friction of the constraint.
    float restitution;               ///< Restitution coefficient of the constraint.

    std::vector<PenetrationConstraintPointData> points; ///< Contact points in the contact manifold.
};

And that's it for this very short summary of the physics changes. Our implementation is still far from perfect. As you might have seen in the sample clip, some movements still don't look very natural, and the boxes should have stayed on top of each other, which is something we'll be working on over the next releases.

To wrap up, as we promised in the previous release blog post, we've added the PhysicsMaterial component, which allows users to fine tune the friction and bounciness behaviour of each body. Check it out in our documentation!

Cascading Shadow Maps (@tomas7770)

In the previous release, we introduced shadows. As shown in the release blog post, this had a significant impact on the quality of Cubos' graphics. However, due to the complexity and time it took to implement this feature, we were only able to support spot lights, the type of light for which it's easiest to cast shadows. This obviously restricted the scenarios where shadows were visible. For this release we aimed to extend shadows support to directional lights, leaving only point light shadows to be implemented.

Here are some comparison screenshots showing the difference directional shadows can make. Try dragging the slider in the middle to compare the before and after!

Before

After

Before

After

Before

After

As you can see, this adds a whole new level of depth to the engine's graphics.

Similarly to spot shadows, directional shadows can be enabled by adding a component to the respective light, in this case a DirectionalShadowCaster. The Shadows sample has been updated to show this.

Because directional shadows are more complex than spot shadows, there are more options that can be configured, namely the maximum and minimum distances for which shadows are casted (directional lights have an unlimited range, but shadows have a limited range), the distances at which the shadow quality level drops ("splits"), and the resolution of the shadow map. You may want to tweak the distance values for better results: a lower value will result in better shadow quality at the expense of range, and vice-versa.

Due to a technical limitation in our renderer, only one directional light can cast shadows at a given time; other directional shadow casters will simply be ignored.

The way directional shadows are implemented is similar to spot shadows. One of the main differences is that, because of directional lights' unlimited range, a technique known as Cascaded Shadow Mapping is employed, rendering the world from a point which varies with the camera's position, and at multiple distances to balance quality with draw range. This means that instead of just a single shadow map texture for the light, there is a texture for each camera, multiplied by the number of distances at which the world is rendered. It's worth noting that each directional shadow caster has its own textures, instead of using a shared shadow atlas like spot casters. Below are screenshots of the directional shadow map used to draw shadows in Scraps vs Zombies, as shown earlier.

Input Axis Deadzones (@kuukitenshi)

Previously, dealing with input sources that exhibited drift, like older gamepad joysticks, required developers to manually filter out noise from input data.

In this release, input deadzones can now be configured directly within the bindings asset, allowing players to adjust it in the settings for their controllers to filter out unwanted noise.

This enhancement significantly simplifies input handling and ensures a smoother and more reliable gameplay experience, especially for games that heavily rely on precise controller input.

Ortographic Cameras (@mkuritsu)

Previously we only had support for perspective cameras in Cubos, and additionally, perspective matrix computations were duplicated all over the code. To address this, we've added a new generic Camera component that holds the projection matrix of the current camera in use. Now, the PerspectiveCamera component is only used to fill in the Camera component with the correct projection matrix, and code needing the projection matrix can simply query the Camera component.

With this, we decoupled the camera type from the rest of code, allowing us to add a new OrtographicCamera component which uses an ortographic projection instead of a perspective one.

On the Core

Spans for Profiling and Tracing (@roby2014)

In our ongoing efforts to improve metrics and address performance issues, we are excited to announce the implementation of a new feature for telemetry: Tracing. This addition will significantly enhance our ability to monitor and understand the execution flow of applications built with Cubos.

Tracing allows developers to track the execution of their code by creating spans that represent specific periods of execution. This capability makes it easier to log messages and visualize the flow of an application, providing valuable insights into performance and behaviour.

In Cubos, tracing is facilitated through a set of macros defined in core/tel/tracing.hpp: - CUBOS_SPAN_TRACE - CUBOS_SPAN_DEBUG - CUBOS_SPAN_INFO

From now on, all telemetry components share the same logging level. You can set it by using cubos::core::tel::level method. This means that, as an example, trace spans will only be registered if the logger level is set to trace. We also moved the other components to the tel namespace (metrics and logging).

Here's a simple code snippet on how it works and its output:

int main()
{
    cubos::core::tel::level(Level::Debug);
    CUBOS_SPAN_TRACE("this_wont_exist!"); // wont exist because trace < debug

    CUBOS_INFO("hello from root span!");

    CUBOS_SPAN_INFO("main_span");
    // With this macro, a new RAII guard is created. When dropped, exits the span.
    // This indicates that we are in the span for the current lexical scope.
    // Logs and metrics from here will be associated with 'main' span.
    CUBOS_INFO("hello!");

    CUBOS_SPAN_DEBUG("other_scope");
    CUBOS_INFO("hello again!");

    SpanManager::begin("manual_span", cubos::core::tel::Level::Debug);
    CUBOS_INFO("entered a manual span");
    SpanManager::end();

    CUBOS_INFO("after exit manual span");
}

[16:03:31.966] [main.cpp:20 main] [thread11740] info: hello from root span!
[16:03:31.967] [main.cpp:26 main] [thread11740:main_span] info: hello!
[16:03:31.967] [main.cpp:29 main] [thread11740:main_span:other_scope] info: hello again!
[16:03:31.968] [main.cpp:34 main] [thread11740:main_span:other_scope:manual_span] info: entered a manual span
[16:03:31.969] [main.cpp:37 main] [thread11740:main_span:other_scope] info: after exit manual span

Looking ahead, we aim to develop a Tesseratos plugin that will allow developers to debug and view all possible spans and their execution times (e.g: https://github.com/bwrsandman/imgui-flame-graph).

This UI will enable developers to interact with the tracing data, providing a comprehensive view of the entire game flow.

Swapping OpenAL for Miniaudio (@diogomsmiranda, @Dageus)

This release marks the beginning of an exciting new chapter for Cubos: the Audio Plugin. But before we could start working on the plugin itself, we had to make some changes to the audio backend. Previously, we were using OpenAL for audio, which no longer aligned with our vision for Cubos, so we decided to switch to miniaudio.h, a lightweight, single-file audio library easy to integrate and use while also sharing the same license as Cubos. We implemented a new AudioContext abstraction on the core library, which hides the underlying audio library from the rest of the engine.

In the next release of Cubos, we're planning to have a fully functional audio plugin, which will allow you to play sounds and music in your games!

Type Client and Type Server (@RiscadoA)

To separate Tesseratos from the engine into a separate process, we needed a way to share type data across different processes. This is because the editor needs to know about the project's data types, such as its components and resources, to be able to do work with them, such as showing them in the editor's UI, or editing scene assets.

To solve this problem, we've added the TypeServer and TypeClient classes to the core's reflection module. The editor contains a TypeClient, the game contains a TypeServer and both communicate through an abstract stream, which currently is implemented using a TCP socket.

Our reflection system is based on the concept of "traits". A trait is a piece of metadata that describes a type, such as its name, its fields, and its methods. Both the TypeClient and the TypeServer allow registering serialization and deserialization functions for each trait, so that they can be sent across the stream.

The protocol itself is relatively simple:

The client - the editor - sends a list with the names of the traits it supports.
The client sends a list with the types it already knows about (for example, primitive types like int and float).
The server - the game - sends a list with the types that the client doesn't know about yet. This includes: - The type name. - A list of the serialized traits that describe the type. - The serialized default value for the type, if it has one.

Most of the complexity of this system is on the client side, as it needs to figure out the memory layout of the types it receives from the server. We do this by basing the memory layout on one of the received traits. For example, if the server sends a trait that describes an object type with fields, then the client will create a new type which stores these fields in memory. If the trait describes an array type, then the client will create a new type that stores an array in memory, and so on.

One major limitation of the current implementation is that it lacks support for traits like NullableTrait. This trait contains a function which determines if a value is null or not, and another to make a value null. How can we pass a function through a stream? We can't. One thing we could do would be to communicate again with the server whenever the client needs to know whether a value is null or not. For now, we've decided to simply ignore these traits, but we'll eventually need to tackle this issue, as it would allow for better UX in the editor.

Stacktraces on Crashes (@RiscadoA)

Previously, when the engine crashed, it would simply print an error message to the console, and that was it. We would not get a lot of information about the crash's context, other than the previous log messages. To debug a crash, we usually spun up a debugger and tried to reproduce it. This way we could get a stack trace, but it was a bit cumbersome, and when the crash happened in a release build or in a different environment, we were out of luck.

In order to make our lives easier, we've integrated cpptrace into the core library. Now, whenever the engine aborts, it prints a pretty stack trace to stderr, which includes the function names, the file names, and the line numbers of the functions that were called.

New Team Organization

We're currently undergoing a major reorganization of the team itself, as it has grown significantly over the past few months. We have now over 20 developers working on the project, and we're planning to expand even further.

Previusly, we all met weekly to showcase what each member had been working, and to discuss the project's direction. Of course, with such a large team, these meetings were becoming increasingly long and unproductive.

So, we decided to split the big team into smaller teams, each with its own focus. As of now, we have the following teams:

Community: responsible for managing the more meta aspects of the project, such as the blog, the Discord server, and the social media.
Graphics: responsible for any graphics-related features, such as voxels, UI and gizmos rendering.
Physics: responsible for the physics and collisions plugins.
Tools: responsible for Tesseratos, Quadrados and all other kinds of tooling.
Wildcard: catch-all team for any other kind of feature that doesn't fit in the other teams.

Now each team meets weekly to discuss their progress and plans, and we have a big meeting less frequently to discuss the project as a whole.

Next Steps

In the next release, which should be out by the end of November, we're planning to work on the following features:

Scene editing through the new standalone editor, Tesseratos.
An Audio plugin, using the new Audio Context abstraction we've added in this release.
Point light shadows.
Anti-aliasing.
MSDF text rendering on our UI plugin.
Reduce shadow artifacts such as shadow acne and peter panning.
Toggleable gravity on the physics plugin.
Voxel collision shapes, where the collision shape is the same as the voxel model.
Contact point caching to avoid recomputing the collision manifolds every frame.
Saving settings after changing them in the UI.
An Active component to enable and disable all kinds of behaviors in entities.
Refactoring the whole CMake configuration to support installation and packaging.

Additionally, we're planning to work on a new game project using our engine - now with online multiplayer support!

You can check out the full list of stuff we want to get done in the milestone for the next release.

Release 0.3

2024-09-09T16:00:00+01:00

This blog post came a bit late due to the summer break, but we're back with a new release! Features-wise, this release was a tad smaller than the previous one as we spent a lot of time working on non-code related stuff, such as rebranding and marketing the project.

New 0.3 Features

This blog post covers the most important changes, but you can check out the full changelog in our repository.

On the Editor

Groundwork for a Standalone Editor (@RiscadoA)

The original main goal for this version was to get a first prototype of our standalone editor working. Sadly, we didn't manage to get it done in time, as it was a bigger task than we anticipated.

The initial approach, to which we dedicated most of the time, was to have two instances of Cubos running at the same time, on the same process - one for the editor and one for the game. The game instance would be running within the editor instance, and would be launched by loading the game's code from a shared library (such as a DLL). With this separation, it would be possible for the editor to interact with the game, pause it, restart it and so on, even across game code changes, without having to restart the editor.

So, with this in mind, we restructured some parts of the code base to get it flexible enough to support this kind of setup. Namely, it is now possible to step Cubos instances, reset them, restart them, and other similar operations. We also added cross platform support for loading Cubos instances from shared libraries, so that we could load the game from the editor.

This all seems, at first, perfect, but after a team discussion, we realized that this approach of having two Cubos instances in the same process is not ideal at all. Any game crash would bring down the editor, any memory leak in the game would affect the editor, and infinite loops in the game would freeze the editor. Since solving the halting problem isn't in our roadmap, we decided that we should discard this approach, and instead try to keep the editor and the game in two separate processes.

So, for the next release, we'll be focusing on following this new approach. It will be a big task, and it will be a lot more difficult, as it will require a lot of inter-process communication, but it will be worth it in the end. It will allows us to have a stable editor, whose performance is not affected (that much at least) by the game, and vice-versa.

On the Engine

A New Physics Solver (@fallenatlas)

Upon discovering some potential issues with regards to NVidia's patent of XPBD, some problems with how XPBD handled friction, and stability, we decided that this would be the ideal moment to switch to another solver. Recently, Erin Catto shared his comparison of multiple solvers, and the results of TGS Soft seemed quite promising, so we decided to give it a try... And at this point, our simulation is already more stable than before!

In simple terms, it differs from XPBD in the sense that it uses impulses instead of changing the position of the bodies directly, however, like XPBD it also uses substeps. On top of this it also uses soft constraints, which is what Soft stands for in it's name.

Since these changes were mostly in internal systems, from a user stand point, everything works the same way.

Additionally, we added Friction and Bounciness. For now, these are a predefined value for every body, but will be customizable in the next release with a PhysicsMaterial.

Raycasting (@diogomsmiranda)

Raycasting is a commonly used tool in game development which Cubos was lacking until now - it is a technique used to determine the intersection of a ray with an object in a scene. This allows for a wide range of applications, such as shooting mechanics, object selection, and more.

This new utility was implemented as a system argument, which means it can be used in any system, by simply adding it as an argument:

cubos.system("raycast").call([](Raycast raycast)
{
    // raycast from the origin to -50,0,0
    auto hit = Raycast.fire({{0.0F,0.0F,0.0F},{-50.0F,0.0F,0.0F}});
    if (hit.contains())
    {
        CUBOS_INFO("Hit entity {} at point {}", hit->entity, hit->point);
    }
});

To implement this, we had to handle the two types of colliders that we currently have in Cubos: boxes and capsules.

Intersection with a Box

The intersection test with a box is based on the Cyrus-Beck algorithm, which is a line clipping algorithm that is used to find the intersection of a line segment with a convex polygon.

We can easily define a box by the minimum and maximum values of x,y,z and the ray by its origin and the direction.

A ray is defined then by the line formula:

Being t a scalar value that represents the distance from the ray's origin to the point.

Our objective is to find t, and check if the point is in the "right" side of the ray (the side that the ray is pointing to).

For that we can rearrange the previous formula to:

If the point is in the right side of the ray, then the intersection point is the point that is closest to the ray's origin.

Now, the only thing that we still need to account is, that most of the times, we have 2 intersection points, one going in, and one going out.

For this we can change the way we use this formulas by instead of using the point, we use the minimum and maximum values of the box.

If both our t's make sense, then we have an intersection.

Here is an excerpt taken from the Raycast class:

static float intersects(cubos::engine::Raycast::Ray ray, cubos::core::geom::Box box)
{
    (...)

    glm::vec3 max = corners[1];
    glm::vec3 min = corners[0];

    float tMinX = (min.x - ray.origin.x) / ray.direction.x;
    float tMaxX = (max.x - ray.origin.x) / ray.direction.x;
    float tMinY = (min.y - ray.origin.y) / ray.direction.y;
    float tMaxY = (max.y - ray.origin.y) / ray.direction.y;
    float tMinZ = (min.z - ray.origin.z) / ray.direction.z;
    float tMaxZ = (max.z - ray.origin.z) / ray.direction.z;

    // find the maximum of the min
    float tMin = std::max(std::max(std::min(tMinX, tMaxX), std::min(tMinY, tMaxY)), std::min(tMinZ, tMaxZ));

    // find the minimum of the max
    float tMax = std::min(std::min(std::max(tMinX, tMaxX), std::max(tMinY, tMaxY)), std::max(tMinZ, tMaxZ));

    if (tMax < 0 || tMin > tMax)
    {
        return -1.0F;
    }

    return tMin < 0.0F ? tMax : tMin;
};

Intersection with a Capsule

The intersection with a capsule is more straight forward than the collision with a box, as we can separate a capsule into 3 parts, a cylinder and the two spheres at the ends.

We then can check for a point of intersection by checking if the ray intersects the cylinder, and if it doesn't, we check if it intersects the spheres.

We can determine both intersections by simply subbing the the ray's equation for x and z in the cylinder and sphere equations, and then solving it for t.

Code excerpt from raycast.cpp for the cylinder intersection:

static float intersects(cubos::engine::Raycast::Ray ray, float radius, float top, float bottom)
{
    // We are gonna use the quadratic equation made by subbing the ray equation into the cylinder equation
    // The cylinder equation is:
    // x^2 + z^2 = r^2
    // The ray equation is:
    // x = x0 + t * dx
    // z = z0 + t * dz

    float a = ray.direction.x * ray.direction.x + ray.direction.z * ray.direction.z;
    float b = 2.0F * (ray.direction.x * ray.origin.x + ray.direction.z * ray.origin.z);
    float c = ray.origin.x * ray.origin.x> + ray.origin.z * ray.origin.z - radius * radius;

    float discriminant = b * b - 4.0F * a * c;
    if (discriminant < 0)
    {
        return -1.0F; // no intersection with the cylinder
    }

    float t1 = (-b + std::sqrt(discriminant)) / (2.0F * a);
    float t2 = (-b - std::sqrt(discriminant)) / (2.0F * a);

    float max = std::max(t1, t2);
    float min = std::min(t1, t2);

    float t = min > 0.0F ? min : max;

    if (t < 0.0F)
    {
        return -1.0F; // no valid intersection
    }

    float y = ray.origin.y + t * ray.direction.y;

    if (y < bottom || y > top)
    {
        return -1.0F; // intersection is outside the finite cylinder
    }

    return t;
};

Spot Light Shadows (@tomas7770)

Our graphics renderer has received a new major feature in this release: shadows!

It should go without saying that this feature has a big impact on the visuals of games developed with Cubos. We've tried it on Scraps vs Zombies and the result is stunning! It's an important step towards the kind of appealing graphics that we hope to achieve.

For the time being, shadows support is limited to spot lights. To enable them, all you need to do is add a SpotShadowCaster component to the spot lights for which you want shadows to be cast, as shown in the Shadows sample. Both hard and soft shadows are supported, with a configurable blurRadius.

Behind the scenes, this works by rendering the world from each light's perspective to determine which parts are occluded, and making these parts unlit. A large texture known as the "shadow atlas" holds this information for every light in a quadtree structure, reducing expensive texture switching. Finally, soft shadows are implemented as a post-processing step that effectively blurs out the shadows. Below is a screenshot of the shadow atlas with 5 spot lights. Lines have been drawn separating the areas of the atlas reserved for each light.

Initial UI Plugin (@DiogoMendonc-a)

Cubos now has a UI system!

Add a UICanvas to your Render Target, and set a UIElement as its child. The UIElement will determine where the entity is drawn, and other UI components you add to the entity, such as a UIImage, will determine what it is that is drawn. For this initial version of the plugin, there are only two types of elements: UIColorRect, which simply fills the element with a solid colour, and UIImage, which draws an image asset.

To make using the UIElement easier, there are also a number of components meant to dynamically change its size: UIHorizontalStretch and UIVerticalStretch will make the element expand to its parent's size.

One more problem that was tackled was the question of how to handle different aspect ratios. As it stands, Cubos now has five different settings for how to handle that, that can be read in detail on the sample page.

Finally, there is a UINativeAspectRatio that, when paired with an UIImage, will ensure that the UIElement will retain the proportions of the original source file.

On the Core

Metrics (@roby2014)

We are excited to introduce the new metrics and profiling utilities! This started becoming a priority since we detected lots of performance issues in the last Game Jam we participated.

These tools are designed to help track performance and gather valuable insights about code execution and data.

How it looks:

static void compute()
{
    CUBOS_PROFILE();
    // ...
} // after the scope ends, a new metric `compute` will be added, with the duration of this scope

static void myFunction()
{
    /// simulate profiling loop
    for (int i = 0; i < 1337; ++i)
    {
        // simulate frame by calling a function that does work..
        compute();

        // register some metrics, this could be FPS, entities count, ....
        CUBOS_METRIC("count", i);
    }
}

Currently, metrics can be accessed manually through the singleton class. However, we plan to integrate these metrics into our editor for a more streamlined experience.

Learn more about it on our metrics documentation.

Networking Utilities (@roby2014)

In the 0.3 release, Cubos finally has networking! This is a big step forward for our engine, bringing powerful networking utilities such as Address, UdpSocket, TcpListener, and TcpStream.

Creating an UDP client and sending a message is as simple as:

UdpSocket client;
client.bind(8080, Address::LocalHost);

const char* msg = "Hello, I'm a Cubos UDP client!";
client.send(msg, std::strlen(msg), Address::from("server.com"), 8081);

Learn more about it on our networking documentation.

Next Steps

Although this was a smaller release, we managed to get some important features done! In the next release, which should be out by the end of this month, we're planning to add:

A standalone editor application. Our tools are currently integrated into the games themselves which is not ideal.
Audio support, as there's no sound at all in the engine right now.
Actual voxel collisions, as we currently only check the bounding boxes.
Basic rigidbody physics, with rotation and friction.
Shadows for other light types.
Tracing and spans, for better tracking of program execution.

You can check out the full list of stuff we want to get done in the milestone for the next release.

We're currently a team of 13 people, and we're looking to expand! If you're interested in joining us, or just want to learn more about the project, join our Discord server!

Release 0.2

2024-05-21T10:00:00+01:00

New 0.2 Features

Our focus on this release was to continue working on improving and implementing base functionality, such as rendering and physics, and also to improve on the tools available to the developer. We've compiled here some of the most important changes (if you're curious, you can check out the full changelog in our repository).

On the Editor

Transform Gizmo Upgrades (@DiogoMendonc-a)

The biggest change was the addition of a rotation gizmo, so now you can rotate entities using your mouse!

We also added a toggle that allows changing between using global or local space with the Transform Gizmo, and a new type of gizmo, a Rotated Box, which, unlike the old boz gizmos, does not need to be axis-aligned.

Finally, the transform gizmo is now always rendered at the same size, regardless of the selected entity's distance to the camera. This should hopefully make it easier to use the tool when moving entities either very far away, or very close.

World Inspector Overhaul (@diogomsmiranda)

The World inspector has been on our radar for quite some time now, as a tool that could be improved. This release we particularly aimed on making it better by focusing on:

Making it easier to find the entities you are looking for.
Displaying more information about the entities in the scene.

To tackle the first point we've added a search bar that allows you to filter the entities in the scene, either by their name, or by their components. e.g:

Searching for "player" will show all entities that have "player" in their name.
Searching for "Transform" will show all entities that have a Transform component.
Searching for "player, Transform" will show all entities that have a Transform component and contain "player" in their name.

To tackle the second point on our list we added an hierarchy view that shows the entities in the scene in a tree-like structure representing the ChildOf relation between entities.

Sub-scene importing in scene editor (@teres4)

Previously our scene editor was lacking support for importing sub-scenes. This meant that developers had to manually open the scene file and paste the sub-scene UUID in its import section. To save time, we've added a popup that shows all the importable sub-scenes, and allows the developer to select the one they want to import.

On the Engine

Physics Improvements (@fallenatlas)

This update we introduced the Solver, which works to satisfy the physics constraints applied to entities (e.g. Spring, Fixed distance between entities, etc.).

This means that the developers can now give entities any number of constraints, either engine defined or their own, and the solver will handle their expected interaction. As of now, we have one constraint, internal to the engine, the PenetrationConstraint, which separates bodies that are inside each other, and comes in to replace our previous collision solving system.

With the ability to have repeating systems, it was possible to introduce the physics substeps loop, which will perform the physics update in multiple smaller steps. This is important to increase the convergence rate of the solver and preservation of energy, by reducing the errors caused by approximations of the simulation.

These changes should lead to more realistic behavior, as well as better consistency between systems with different performance levels.

Modular Renderer (@RiscadoA, @tomas7770)

Before this update, our graphics renderer was very monolithic, with a lot of the code being held in a single file. This posed some problems, namely that if we wanted to implement new rendering methods in the future (e.g. raytracing), we would end up with tons of duplicate code. It also didn't fit well with our ECS design, since things such as the renderer and its active cameras were just global resources.

To overcome this, we've restructured the renderer, splitting it into several components with their respective plugins. The most important ones are perhaps RenderTarget, representing something that can be drawn to, and PerspectiveCamera, which draws to render targets using perspective projection. Entities with these components are related using a DrawsTo relation. There are also components that individually enable various parts of the renderer, such as deferred shading, or effects like bloom and SSAO. This separation opens up possibilities for more customizability from the user side, and makes the renderer code easier to deal with by engine developers.

We also used the opportunity to optimize the renderer, namely, by allocating a large GPU buffer for all the voxel meshes, which we then split into smaller buckets. This way, we can draw all the voxel objects with fewer draw calls, and with way less context switches. One other feature we improved greatly was entity picking - finding out which entity is visible at a given pixel. Previously, enabling it cut the framerate by more than half, which was unacceptable. By using Pixel Buffers and double-buffering, we managed to make its performance impact negligible.

Additionally, we added a tone-mapping pass to the renderer, which makes better use of the HDR color space. It allows us to tune the exposure of the scene, and also to apply effects like bloom and SSAO in a more realistic way. One side-effect of us changing the color-space is that now the colors in the game are a bit more washed out. We'll have to go back and tweak the colors in the game to make them look good again.

On the Core

Clearer Plugin Dependencies (@RiscadoA)

One of the main features of Cubos is its plugin system. We structure all of the engine and editor features as plugins, each with its own set of components, systems, and resources. The developer ultimately chooses which plugins to include in their game, and may also create their own plugins.

Plugins may depend on each other. One example is the physics plugin, which depends on the collisions plugin. Previously, when a plugin was included, all of its dependencies were automatically included. It was also possible to include a plugin twice - the second time, the plugin would simply be ignored.

While this seems useful, this led to some problems. Since a plugin could be included more than once, there isn't a single place where its safe to make decisions about how a given plugin should behave. This was particularly problematic with the new modular renderer plugins.

Imagine a scenario where we have two plugins A and B, which implement different rendering methods. A and B are incompatible. Adding both should be an error, as it's impossible to have both rendering methods active at the same time. Additionally, A and B both add on a plugin C, and make decisions about how C should behave. If both A and B are included, which one should have the final say? How do we specify the dependency between them without coupling their code?

Our solution to this was to distinguish between depending and including a plugin. When a plugin X depends on a plugin Y, adding X without Y being present leads to an error. When a plugin X includes a plugin Y, including X will also include Y. But, if a plugin is included twice, an error occurs. This way, we get a clean plugin hierarchy, which is easier to reason about:

void myPlugin(Cubos& cubos)
{
    cubos.depends(renderVoxelsPlugin); // Don't care about internals, just need the plugin

    cubos.plugin(mySubPlugin); // Include a sub-plugin, which becomes part of my plugin

    // ...
}

One issue with this solution is that you would now have to manually include all plugins you need when making a game. Of course, this is not ideal, and thus, we've added a new defaults plugin to the engine that includes all the plugins that are necessary for a basic game to run. If the developer wants to configure the engine in a different way, they can simply write their own alternative defaults plugin.

Observers (@RiscadoA)

Very often while working with Cubos, we find the need to react to the addition and removal of components in entities. One use case, for example, is setting up the AABB of an entity when we add a collider to it. Previously, we had to manually implement this logic, for example, by adding a flag to the collider which was initially false, and having a system initializing all colliders with the flag set to false.

To solve this problem in a more elegant way, we added a new special kind of system: observers. Observers are essentially systems which instead of running on a specific schedule, run immediately after a certain change occurs in the ECS (akin to callbacks).

We also found another unexpected use for this feature. Complex plugins with lots of components, such as the physics plugin, where previously cumbersome to work with, as all the required components had to be manually added to each entity we wanted physics to apply to. With observers, we instead now add a single component PhysicsBundle. An observer picks up this addition, and immediately replaces this component with all of the required components for the physics plugin to work.

If you're interested in learning more about this feature and ECS in general on our engine, check out our ECS feature guide.

Introducing Inheritance in Reflection (@roby2014)

Cubos has a powerful reflection system to examine and interact with a structures and types at runtime It works by attaching metadata to types, which we call traits. These traits can be queried at runtime to get information about the type. For example, we provide a FieldsTrait, which you can add to a type to expose its fields to the reflection system.

One thing we were missing was information about inheritance relationships between types. We've added a new trait, InheritsTrait, which allows you to specify that a type inherits from another type.

This will be particularly useful for serialization, as right now we have to manually add the fields of the base class to the derived class. Now, serializers can check if this trait is present and fallback to the base class if necessary.

Repeating Systems and Fixed-Step Updates (@joaomanita)

Certain plugins, like the physics plugin, required some of their systems to run multiple times per frame so that they could make more accurate aproximations. In addition, some of them need to be executed in ordered groups. For example:

The integration system needs to run before the velocity update system.
The velocity update system needs to run before the force clear system.
The force clear system needs to run before the impulse clear system.

To allow repeating groups such as these, we added a new feature to the ECS tags: the repeat while modifier. This makes the systems tagged by it repeat until a certain condition becomes false.

cubos.tag(groupTag).repeatWhile(myCondition);
cubos.system("integrate physics").tagged(groupTag)./* ... */;
cubos.system("update velocity").tagged(groupTag)./* ... */;
cubos.system("clear forces").tagged(groupTag)./* ... */;

Its also possible to make repeating subgroups by tagging the subgroup with the parent tag.

cubos.tag(subgroupTag).tagged(groupTag).repeatWhile(myOtherCondition);

This way the subgroup's systems will repeat a total of n x m times, where n is the number of times the parent tag repeats and m is the number of times the subgroup tag repeats.

With this implemented, it was easy to implement the fixed-step plugin on the engine side. It simply adds a tag that makes systems repeat as needed according to the DeltaTime passed, avoiding variance due to different frame rates and more/less powerful PCs.

Moving Away from the Old Serialization (@Dacops)

Serialization is a crucial part of the game engine that allows for the saving of any Cubos game components as well as then loading them in. Previously, serialization was done through a series of functions, both for reading and writing, that could be overloaded for each type. On the previous (and first) release, we introduced a reflection system, that allowed for the inspection of types at runtime. This was an essential step to make the inspectors on the editor side work.

But with this new system, we now had two sources of truth for the types, the reflection system and the serialization system. To solve this, we decided to change the serialization system to use the reflection system, and thus, not force the developer to write serialization code for each type.

On this release, we've finally finished this transition, by replacing serialization by direct stream manipulation in places where performance was more of a concern, such as voxel object saving/loading; and by replacing the serialization methods by reflection in other places, such as the input bindings.

Next Steps

We're very happy with the progress we've made on this release. The engine is becoming more and more powerful, and we were able to create a full game with it in a week!

For the next release, which should be out in July, we'll be focusing on expanding the engine's capabilities, as it is currently missing some key features, such as:

A standalone editor application. Our tools are currently integrated into the games themselves which is not ideal.
Audio support, as there's no sound at all in the engine right now.
An initial UI plugin, which can render images, text and handle buttons.
Actual voxel collisions, as we currently only check the bounding boxes.
Basic rigidbody physics, with rotation and friction.
Shadows, transparency and other rendering features.
Raycasting.
Networking utilities, to allow for online multiplayer games.
Web-support, so that games can be played in the browser.
C API, so that we can use the engine from other languages (scripts!).
Better editor tools.

You can check out the full list of stuff we want to get done in the milestone for the next release.

We're currently a team of 10 people, and we're looking to expand! If you're interested in joining us, or just want to learn more about the project, join our Discord server!

Cubos Engine - Release

Release 0.7

New 0.7 Features

On the Engine

Overhauled ImGui Inspector with Hook Support (@RiscadoA)

Distance Physics Constraint (@joaomanita)

Voxel Mesh Frustum Culling (@mkuritsu)

AABB and Collider Rework (@fallenatlas)

Voxel Shape Inertia (@fallenatlas)

New Scene Format (@RiscadoA)

Custom ImGui Styling (@RiscadoA)

Optional Render Picker (@tomas7770)

Center Render Voxel Pivot (@kuukitenshi)

On the Core

Math Vector Reflection Trait (@RiscadoA)

Entity Destruction Observers (@kuukitenshi)

Query Match Counting (@GalaxyCrush)

Wrapper Reflection Trait (@SrGesus, @RiscadoA)

On the Tools

Tesseratos Menu Bar (@jdbaracho)

Auto-scroll Toggle on the Console (@R-Camacho)

Next Steps

Release 0.6

New 0.6 Features

On the Engine

Physics with Warm-Starting (@fallenatlas)

Toggleable SSAO and Resolution Scale (@tomas7770)

Conditional Shader Compilation (@tomas7770)

On the Core

Added Frustum geometry and intersection utilities (@mkuritsu)

New Demo Sneak Peek

Next Steps

Release 0.5

New 0.5 Features

On the Editor

Hold mode for Debug Camera (@jdbaracho)

On the Engine

Point Light Shadows (@tomas7770)

Audio Support through the Audio Plugin (@Dageus, @diogomsmiranda)

Method to save settings to files (@SrGesus)

Collision detection between VoxelCollisionShapes (@joaomanita)

Anti-aliasing using the FXAA technique (@kuukitenshi)

UI text element using MSDF for text rendering (@mkuritsu)

Enable assets to be identified in the code by their file path (@GalaxyCrush)

Option to use Shadow Normal Offset Bias algorithm (@GalaxyCrush)

Resource to easily configure constants in the physics solver (@GCeSilva)

Contact caching for collision between box shapes (@fallenatlas)

On the Core

A Proper CMake Configuration (@RiscadoA)

Web Support with Emscripten (@RiscadoA, @luishfonseca)

Next Steps

Release 0.4

New 0.4 Features

On the Editor

Project Management and Debugging (@RiscadoA)

Voxel Model Importing Tool (@Scarface1809)

On the Engine

Physics with Rotation (@fallenatlas)

Collision Manifold and Collision Points

New Components

Expand the Integrator and Solver

Cascading Shadow Maps (@tomas7770)

Input Axis Deadzones (@kuukitenshi)

Ortographic Cameras (@mkuritsu)

On the Core

Spans for Profiling and Tracing (@roby2014)

Swapping OpenAL for Miniaudio (@diogomsmiranda, @Dageus)

Type Client and Type Server (@RiscadoA)

Stacktraces on Crashes (@RiscadoA)

New Team Organization

Next Steps

Release 0.3

New 0.3 Features

On the Editor

Groundwork for a Standalone Editor (@RiscadoA)

On the Engine

A New Physics Solver (@fallenatlas)

Raycasting (@diogomsmiranda)

Intersection with a Box

Intersection with a Capsule