Cubos Engine

The First Cubos Jam

2025-10-21T17:00:00+01:00

From September 12th to September 21st, 2025, the first game jam focused on the Cubos Engine took place, with the theme "Retro". This was a major milestone for the Cubos team, which we had been planning for a long time. The idea behind it was to see how people would use the engine to create games, and to gather feedback on the engine and its tools.

The engine is still, of course, very hard to use, due to the lack of a proper editor and a scripting language. Participants had to code their games in C++, which is, as usual, not the most user friendly language. Even so, we still were able to attract 13 participants, which is a great start for a first-time event. Four of the five teams were able to submit a game by the end of the event, which you can check out on the Cubos Jam page.

Restrospective Penguin

Rider or Block

Space Runner

Sushi Chef Shuffle

The jam itself was remote, with an in-person opening and closing event. At the opening event, we held a quick workshop to help participants get started with the engine. At the closing event, we had a small ceremony to showcase the games made during the jam.

The workshop guided the participants through the process of installing the engine and compiling a template project we provided. This required setting up CMake and a C++ compiler (Visual Studio on Windows). Installing the engine and compiling the project itself wasn't a very smooth experience. In the future we plan to improve this process by providing pre-compiled binaries and installers for the engine, as well as better setup documentation.

Cubos Jam workshop, at Instituto Superior Técnico, Lisbon.

After the jam we gathered a lot of useful feedback from the participants. Overall, they saw the potential of the engine, but also highlighted many areas that need improvement. Namely:

Tooling: the engine is still very hard to use for non-programmers, particularly artists, due to the lack of an editor and proper asset management tools.
Documentation: although the features are extensively documented, there are few examples and guides, which makes it hard for new users to get started.
Scripting: integrating a language such as Lua (which is happening right now) would greatly reduce the barrier to entry for new users.
Physics: add capsule shape collisions, and expose a nicer interface for handling multiple types of bodies.

We plan to hold more jams in the future, after improving the engine and its tools. We hope the experience will become more accessible and enjoyable for future participants.

Cubos Jam closing event, at the Gaming Hub, Lisbon.

Roll Racers

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

The Theme

From 2nd of May to the 10th of May, @fallenatlas, @tomas7770, @fkatar, @PedroSimoes24, @RiscadoA, @joaomanita and @mcanais participated in the Coffee N' Jam, a game jam organized by GameDev Técnico, with our engine, Cubos. The goal was to create a game in a week, this time with theme "Blackout" - the huge power outage in the Iberian Peninsula had happened the prior week, and just like during the Covid lockdown, people rushed to the supermarkets to buy toilet paper.

We thought it would be funny to make a game about racing to the supermarket to buy toilet paper - and that's what we ended up doing. Our priorities were to test new features of the engine, and to make a fun local multiplayer game. This idea was a great opportunity to fully use the physics and collision plugins in a game for the first time.

The game is called Roll Racers, and you can play it on its itch.io page. It has a web build and a downloadable version for both Windows and Linux. You can also check out its source code in our demo repository.

The game supports up to 4 players, each having a different car model.

A player holding toilet paper, racing back to the start line to score points.

We had a lot of fun making the game, and we fixed a ton of bugs and missing features in the engine as we went along. Since the jam was a week long, we had some more time to work on the game than in the previous jam.

Voxel Modeling

One major problem we had was that we didn't have any artists in the team, only programmers. We ended up going full programmer art mode, and we used, as usual, MagicaVoxel for this purpose. @PedroSimoes24 focused on making the buildings and the road models, @RiscadoA focused on the cars and some tiles and @mcanais made a few props.

Map Generation

To make our jobs easier, the map is divided into tiles. Each tile is 68x68 voxels wide. Tiles can be road tiles, building tiles or park tiles. @RiscadoA and @mcanais worked on the map generation, which is done procedurally. First, road tiles are placed in a river-like fashion, and then, building tiles are placed around them.

To make the map prettier we also added some park tiles with trees and bushes, which are randomly placed adjacent to the road tiles. For an extra challenge, we added a 'river' tile where the road has a big hole in the middle, and the players have to jump over it by going fast enough on the ramps.

We also have special start and end tiles, the end tile being the supermarket, where the toilet paper is placed. The map regenerates every time a round ends, i.e., when a player brings the toilet paper back to the start line.

Supermarket tile, where the toilet paper can be picked up.

Physics and Collisions

For this game, we decided to go all in on physics. @fallenatlas and @RiscadoA developed physically realistic cars. The cars are essentially composed of a box shape, representing the chasis, and then four empty child entities representing each of the wheels, with origin on the point where the suspension connects to the car. When turning, these wheel entities are rotated on the y-axis. Then, the forces for each individual wheel are calculated and applied on the connection point with the chasis, for realistic behaviour. These forces include:

The suspension force, which lifts the car up and makes it react realistically to the ground bellow.
The steering force, which simulates the cars steering with tire friction and splip angle.
The acceleration force, which applies acceleration and breaking to the cars. The acceleration forces are applied to different wheels, depending if the car is front wheel drive or rear wheel drive, affecting it's handling.

Since each wheel is simulated independently, the cars tilts when going over the sidewalk.

However, if the cars are not on the ground, we do not want to calculate any forces besides gravity. Therefore, we perform a raycast from the wheel origin to the ground. In case it hits bellow the max distance, we calculate the forces, and particularly, we use it's hitpoint for determining the strength of the suspension force.

As mentioned previously, the map is divided into tiles. As it's much fast and accurate than trying to put collision shapes manually, we decided to use voxel collision shapes for every tile. This worked surprisingly well, and the framerate didn't drop as much as we where expecting given how many voxel shapes we had, and the little optimization we currently have for collisions. It's worth noting that we were taking advantage of the collision layers and masks to determine which shapes should detect collision between themselves, which lead to better performance in this scenario.

But this is where things went a little wrong... As we tried to put the car on the map, we noticed that the car would just completly fall through the tile. After finding the root issue, @fallenatlas started working quickly on fixing it. The issue had two parts. The first was related to the component matching on the penetration constraint solving, where we were missing some checks for certain components, leading to the solving being done in the opposite way, effectively pulling bodies to each other, instead of pushing them apart. The second issue was related to the local contact points calculation for voxel shapes, in the narrow phase, where the points were always relative to the center of the entity rather than relative to their relative box center (since the voxel shape is composed of multiple boxes). This lead to the penetration distance being miscalculated in the penetration constraint solving, and therefore, the impulses applied to each entity were incorrect.

Since, we were at it, we wanted to use as much physics features as we wanted, so @joaomanita experimented with using the new Distance Constraint to attach the paper roll to the car, and having it be dragged along. However, the team felt like it was too hard to steal the toilet paper, since it moved around too much, and discarted this idea.

On the last day, a comical situation happened when we where putting ramps on the map. We (@RiscadoA) tried to rotate one of the ramps, by rotating it, and then putting it as a child entity of another entity with the same rotation applied to it. This lead to a huge framerate drop, which took as a couple of hours to figure out. The exact reason for why this happened is still unknown, but we'll be investigating it in the future.

A player can steal another player's toilet paper by hitting them with their car.

UI

This game was also the first time UI was used on a demo. @tomas7770 picked up this task, and made multiple menus and screens for the game. We wanted to briefly explain the game mechanics to the players, so we added a title screen with some information.

The "Press Space/A ..." text color is animated, fading in and out.

Additionally, the players can choose how many players will play the game by pressing the spacebar or the "A" on the gamepad for each of them. Instructions were added to the top of the screen.

After advancing, the players must choose the number of players.

In game, it was important to show the players their score and how it changed over time, to make the game more competitive. We decided to add a score indicator to the top of the screen, which shows the score of each player.

Points are gained by holding the toilet paper.

Finally, at the end of the game, we wanted to reward the players with a scoreboard, showing the score of each player.

The text color helps associate the players with their scores.

The UI ended up working well during the jam. There were only three issues:

Our UI and ImGui were not compatible - this was easily fixed by ensuring they were drawn in the correct order.
There is no support for text wrapping or newlines, so we had to create a different text element for each line.
The text contents only updated when its respective component was reinserted - simply modifying it wasn't enough. We're still unsure on how to handle these scenarios, but the most likely solution is to make the component unmodifiable and thus force the user to reinsert it.

Audio

On the last day of the jam @RiscadoA decided to focus on adding audio to the game. Previously, when making Ondisseia, we had a lot of trouble with adding sound effects. They didn't play reliably and the audio system was a bit of a mess.

To use audio in Roll Racers, we ended up fixing all of the problems we previously had, which means that we can now rely on it for future projects. We added a few sound effects to the game, such as:

Car engine sound, which changes pitch and gain based on RPM and gear.
Pickup sound when picking up toilet paper.
Steal sound when stealing toilet paper from other players.
Fireworks sound when winning the game.
Power cut sound when the race starts.
Honking sound when honking the horn.

While the audio still sounded a bit janky, it was very satisfying to hear sound being used so extensively in a Cubos game for the first time.

ECS Troubles

At the end of the jam, the game's performance was very bad. A bit of profiling quickly showed that a lot of time was being spent iterating over tens of thousands of relation tables - the ones introduced in the relations development note. This was a waste of time, as only less than 15 actually contained entities.

@RiscadoA quickly fixed this by adding logic to clean up unused relation tables every frame. This immediately improved performance by a lot - on one machine, the framerate went from 40FPS to stable 240FPS. In the future, this logic should probably be improved to only clean up the tables when they're not used for a while, to avoid wasting time recreating tables constantly.

Whats Next?

We are very happy with the results of this jam - this demo is and will continue to be a great testbed for the engine, as it really pushes it to its limits. After the jam ended, we met to discuss what went wrong and what issues we should prioritize fixing. One of the biggest problems continues to be the lack of proper tooling for the engine - this will be the focus for the next few months.

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.

The "Ondisseia" of Cubos

2025-05-16T10:00:00+01:00

The Jam

Around a month ago, @mcanais, @NunoBaptista, @RiscadoA and @rsubtil joined forces to participate in the Azul Game Jam. This was the first edition of a Portuguese on-site game jam, where the aim was to join the Portuguese game dev community at the AI Hub, to make games during 48 hours. We were a team of 4 - 3 programmers, 1 artist, and a lot of ideas.

Cubos team participating in the Azul Game Jam - photo by Gonçalo Goulão.

The game is playable on the browser, and can be found at itch.io.

Game Development

It is challenging to work with such a barebones engine, but also really satisfying to have so much control over what is made. This year's theme was waves, and we decided to make a sea battle game, where up to 4 players fight until the last standing. The movement was really inspired on Scraps vs Zombies demo, functioning in a grid wise manner, where the player moves a tile at the time, in for possible directions. To fulfill the jam theme, we've included a cellular automata wave that sweeps across the scene. The player's boat slows down when sailing against this wave, or can catch up speed while riding it. The waves are colossal, sometimes sweeping over the islands on the map. With this game mechanic, we'd hoped to add an interesting twist to the genre of Battle Royale.

Voxel Art (@NunoBaptista)

As an artist, I produce the voxel assets, including the animations, the tiles of the map, and the wave. Currently, we don't have a voxel editor inside Cubos, so we used MagicaVoxel for this purpose. For the animations, we've used a process very similar to pixel art animation, with a model for each frame. Though not strictly necessary, the boat had several animated parts: the sail and the flag, plus the oarsmen and the oars. The oarsmen also served as a game design purpose -to indicate the number of lives the player had, each time the player took damage, one of the sailors would fly out of the boat. Some decoration was created to bring life to the game's world. Plants, houses, and shipwrecks were designed and modeled, but in the end, never made it to the final cut. Currently, each model has to be imported by hand, and even the meta files and ID have to be manually assigned. The 2-day Jam was a very limited time frame for this level of polish.

Models to populate the game world.

Playtest

The game was playtested during the jam's showcase, and it was well received by the community present. A real sense of competition sprout in the players, and fierce fights unfold before our eyes. The game was praised for its engaging gameplay and innovative art style. Some even comment that it locked like pixel art. The voxel resolution and the camera perspective might have helped in this regard.

Cubos showcasing its game in Azul Game Jam - photo by Gonçalo Goulão.

Few days later the Cubos team took the opportunity to showcase the game in a Game Break event, at Gaming Hub. Developers from Portugal and beyond gather at these Game Break events every mouth at Gaming Hub to showcase their latest work, discuss ideas and network. Ondisseia was again showcased in this last april edition, and again, the feedback was really positive. Some suggestions were made about the aiming system - it seemed to some to be too complicated. Only when the player is sideways to other player, over a minimum of 5 chunks, is it possible to shoot arrows. It was also suggested to use a free movement instead of the grid base one. Maybe the most interesting suggestion was to try and make the game run in mobile (browser).

Android Features

Cubos uses Emscripten to export to WebGL. We already had a build from Emscripten for Azul Game Jam, but the formatting was incompatible with itch.io. This build was made for a single web page and not to be embedded on Itch.io. Therefore, we strived to simplify the HTML and customize the CSS classes to our liking.

There were problems with the way Emscripten controls the canvas. Apart from the usual fullscreen bottom, there was a Resize canvas and Lock/hide mouse pointer, for resizing and hiding the mouse in fullscreen, respectively. We've opted to rewrite these functionalities in a new .JavaScript, but we aim to integrate these better in the future.

After this step, we had a functional WebGL build on Itch.io, though no UI and functionalities for mobile devices had yet been included. The game would open, the sound would play, but there wasn't any interactivity.

Screenshot of early test of the game in mobile.

To support mobile devices better, new UI elements were created with HTML and CSS. Still, there wasn't any way to connect them with the game code. For this purpose, this JavaScript Function was created to send the bottom's interaction to the game:

function simulateKey(keyCode, isDown) {
  const event = new KeyboardEvent(isDown ? 'keydown' : 'keyup', {
    keyCode: keyCode,
    which: keyCode,
    bubbles: true,
    cancelable: true
  });
  document.dispatchEvent(event);
}

This combined with this HTML button:

<button class="shoot" ontouchstart="simulateKey(32, true)" ontouchend="simulateKey(32, false)">space</button>

Allowed to interact with the game

Screenshot of the game in a mobile browser.

Despite this progress, a new problem emerged; now we were stuck with these inputs on the PC. To solve this issue, we added a function to hide the mobile control when no longer necessary:

// Detect if it's a touch device (Android or otherwise)
if ('ontouchstart' in window || navigator.maxTouchPoints > 0) {
  // Detect Android specifically
  const isAndroid = /Android/i.test(navigator.userAgent);
  if (isAndroid) {
    // If it's Android, display the touch controls
    document.getElementById('touch-controls').style.visibility = 'visible';
    document.getElementById('fullscreen-btn').style.visibility = 'hidden';
  }
}

With this final touch, we were able to hide the extra UI when the game was running on a PC browser and enable the UI in a mobile device browser. After the jam, we integrated these changes into the main branch of Cubos, so that all samples can be easily ported to mobile devices.

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.

A New Brand Identity

2024-09-09T17:00:00+01:00

Cubos had grown out of its cocoon and needed new wings to fly out of its embryonic phase. The new visual identity aimed at providing a more cohesive and professional look to an increasingly defined and completed game engine. A new logo was designed, alongside a set of visual rules and principals that form Cubos new identity.

The process started with the logo. The team wished to keep the 3D aspect of the former logo, but with a more slick and modern twist. Furthermore, as the project was aimed at a software (a game engine), an icon was necessary for the application, the branding the launch screen, etc. A stylized wordmark, like the previous version, was insufficient. So we set to design the icon. At first, the design followed a more intellectual and less literal approach, adapting an isometric view with 3 sides to establish a deconstructed view of a Cube. The concept of this design was to incorporate the movement and change in the symbol, while representing the assembly purpose of a game engine. In this case, the assembly of a cube, with is faces at the moment they are sliding into place.

First design - horizontal layout

First design - vertical layout

The team received this design with mixed feelings. The logo had little of the 3D aspect that made their previous logo and that also constitutes the main selling point of the engine - voxel base game engine. Therefore, we jumped to a second design, that retained the original while representing a shape made of literal isometric cubes. The final shape was a 3-armed spiral, inspired by the Keltic symbol the Trisquel, without copying the Trisquel GNU/Linux software.

Second design - horizontal layout

Second design - vertical layout

Unfortunately, to some members of the team, the new icon reminded them of some unpleasant symbol. Consequently, we're back to square one. A brainstorming session ensued. Various shapes were tested and debated, but the icons kept getting too complex and unrecognizable.

Logo brainstorming

Eventually, we arrived at an icon that was composed of cubes, that did not bring any bad connotations and that was relatively simple and memorable. As it can be seen in the experiment above, the spiral/movement idea was forsaken in favor of a greater emphasis in the assembly aspect. Three cubes merged to form something more complex, suggesting ideas of union and strength.

Final design - horizontal layout

Final design - vertical layout

Parallel to the icon design process was the font selection. The goals we set at the start were that the font had to transmit a feel of modernity and a certain degree of formality, since those were the goals of this redesign, while conveying the slickness and dynamism of an innovative product. Other concerns that were considered were the versatility and rights of the chosen font. To address this last point, we opted for google fonts library, a largely integrated and open-source collection of great fonts, that complements the open-source aspect of the project. The fonts selected were Russo One for the logo mark and displays/headers, and Roboto font family for text body. Russo One conveys energy and strength while maintaining a dynamic feel to it, while Roboto is a well-established in the space of tech and innovation.

About the logo's colors, it can be observed that these remained virtually unchanged thought out the design process. The contrast of neutral colors with a cyan blue, that aim to represent knowledge and innovation, was well received. Additional colors were added to the pallet for software and marketing purposes. Speaking of which, a Brand Guidelines Document was enacted to specify how the brand and marketing material should be designed and to which principles it should adhere.

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!

Coffee N' Jam 2024

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

From 26th of April to 3rd of May, @RiscadoA and @joaomanita participated in the Coffee N' Jam, a game jam organized by GameDev Técnico, with our engine, Cubos. The goal was to create a game in a week, with the theme "Apocalypse" - and we had a blast!

The game jam was a great opportunity to test the engine in a real game development scenario, and we learned a lot from it. The game is called Scraps vs Zombies, and you can download it from its itch.io page. You can also check out its source code in our demo repository.

We managed to win the "Best Gameplay" and "People's Choice" awards, which we're very proud of!

We found a lot of bugs and missing features during the jam. Additionally, we had performance become a problem for the first time. One particular area that is in dire need of development is Audio, which we've been ignoring so far - people expect to hear something when they play a game! We'll be working on fixing these issues in the next release, and we'll also be profiling the engine to find out where the bottlenecks are.

Hello Relations

2024-01-31T16:30:00+00:00

Hello! This past month I've been tinkering with the ECS, which arguably is the core foundation of Cubos. We structure all of our engine code around it. You can learn more about the concept in our ECS guide!

The Problem

The ECS is a very powerful tool, but it's not without its limitations. One of the most common issues is that it's hard to represent relations between entities. Components are used to associate pieces of data to specific entities. This is great for stuff like position, velocity, health, etc. They can also be used to tag entities as belonging to a certain group. E.g., we could have a Poisonous component. We can then query all entities with a given set of components, and apply some logic to them:

cubos.system("integrate velocity naively")
     .each([](Position& position, const Velocity& velocity) {
         position += velocity;
     });

But what if we want to associate data to not one entity, but to a pair of entities?

Parent-Child Hierarchies

One classical example are parent-child relations. In a standard ECS, we could technically add a Parent component to each entity, which would contain a reference to the parent entity. This way we could build hierarchies and easily discover the parent of an entity simply by accessing its Parent component.

cubos.system("print parents")
     .each([](Entity entity, const Parent& parent) {
         CUBOS_INFO("Entity {} has parent {}", entity, parent.entity);
     });

But what if we wanted to find all children of a given entity? There are two possible solutions:

Query all entities with a Parent component and check if their parent is the entity you're looking for.
Add a Children component to each entity, which contains a list of references to all of its children.

The first option is very slow and inefficient, as it requires a full scan of all entities with a Parent component. The second option means having to store a heap allocated list of references in the component, ruining any cache locality you might have had. Not only that, you would also have to keep the Children component in sync with the Parent component, which is a pain to do.

Physics Constraints

Another use case we had trouble with at Cubos was physics constraints. Eventually we will want to add support for adding constraints between entities such as springs, hinges, etc. Where do we store the data for these constraints? For example, a spring constraint needs to store the two entities it's connecting, as well as the spring constant and rest length. One possible solution would be to represent the constraint itself as a separate entity which stores this data, and the references to the two entities it's connecting. This isn't a bad solution, but we can do better!

Collision Pairs

This was kind of the tipping point for us. The collision plugins works in two phases: broadphase and narrowphase.

The broadphase is collision shape agnostic - it doesn't care whether the entities are spheres, boxes, or whatever. If finds pairs of entities whose AABBs intersect. The narrowphase, on the other hand, is collision shape aware. It takes the pairs generated by the broadphase, and checks if the real shapes are actually colliding.

On our original solution, we stored the pairs generated by the broadphase in a resource (used to share data between systems), which the narrowphase systems then read. This meant filtering the pairs generated by the broadphase by shape, which was not only inefficient but also a mess to implement. Lots of code duplication and boilerplate, which makes it hard to read and maintain.

Adding R to ECS

While searching for possible solutions to our troubles, I came across a post by Sander Mertens, the author of Flecs. I really recommend reading his series of posts on relations if you're interested in the topic. It has been a great source of inspiration and a tremendous help in understanding the concept.

The idea is to add a new kind of 'component', which we'll call... relations! Like components, relations are pieces of data associated to entities. However, unlike components, relations belong to pairs of entities, instead of a single entity.

How does it look like?

Creating and removing relations is very similar to creating and removing components. We just pass one extra argument, which is the second entity in the pair.

commands.relate(alice, bob, ChildOf{});   // Alice is now a child of Bob
commands.unrelate(alice, bob, ChildOf{}); // Alice is no longer a child of Bob

But the real power of relations comes from querying them. We can query all relations of a certain type, and apply filters on both entities in the pair.

cubos.system("access car wheels")
     .each([](const Wheel& wheel, const ChildOf&, const Car& car) {
         // Do something with the wheel and its parent car.
     });

The query above, for example, will match all pairs of entities where the first entity has a Wheel component, the second entity has a Car component, and the first entity is a child of the second entity.

This also allows us to write the narrowphase collision checks in a much more elegant manner:

cubos.system("box vs sphere")
     .each([](const Box& box, const PotentiallyCollidingWith&, const Sphere& sphere) {
        if (shapesIntersect(box, sphere))
        {
            // Do something with it.
        }
     });

We also allow the user to customize the behavior of relation types with two extra options:

Symmetry: Whether the relation type is symmetric or not.
Tree: Whether instances of the relation type should form a tree.

Symmetry is particularly important for collision relations. While the direction of some relations, such as ChildOf, matter, the direction of others, such as CollidingWith, should not. For example, a relation between foo and bar will also be identifiable through bar and foo.

Tree relations are used to specify that each entity can only have at most one outgoing instance of that relation type, and that cycles are not allowed. This is useful for parent-child relations: cmds.relate(a, b, ChildOf{}) would remove any previous relations of type ChildOf from a to other entity.

This is great, but how do we store these relations tightly in memory while also allowing for fast queries?

Implementation

Although I was heavily inspired by Flecs, I decided to implement relations in a slightly different way. Both Flecs and our ECS are Archetype based, which means that entities are grouped into archetypes based on their components. An archetype is the set of all entities which have exactly the same set of components.

To query entities with a given set of components, we just need to find the archetypes which contain those components, and then iterate over all entities in those archetypes. The operation of finding the archetypes may be slow, but it can be cached.

Flecs handles relations by creating different archetypes for each relation target. For example, with four entities with some data we would get, in this case, three archetypes:

Archetype A
Entity	Health	Player	ChildOf(4)
1	100	()	()
2	50	()	()

Archetype B
Entity	Health	ChildOf(4)
3	75	()

Archetype C
Entity	Health	ChildOf(5)
4	80	()

Where Health and Player are components, and ChildOf is a relation type. As you may have noticed, although entities 3 and 4 have the same data types, since they have different parents, they end up in different archetypes.

While this allows for very fast queries for children of the same entity, it also means that data will be heavily fragmented in memory for relations with many different targets. It also means that adding a new relation to an entity will require moving it to another archetype, which can get expensive. This makes this approach unsuitable for our use case, as we want to be able to add and remove relations very frequently (e.g., collision pairs).

Sparse Relation Tables

Instead of touching the archetypes, we store relations in separate tables, which we call sparse relation tables. Each sparse relation table stores all relations of a given type whose entities belong to a given pair of archetypes

We store relations in separate tables. For each pair of archetypes and relation type, we create a table which stores all relations of that type between entities in those archetypes. With the entities of the previous example, we would get only two archetypes:

Archetype A
Entity	Health	Player
1	100	()
2	50	()

Archetype B
Entity	Health
3	75
4	80

The relations would be stored in two separate tables: one for relations between archetype A and archetype B, and another for relations between archetype B and B.

A to B
From	To	ChildOf
1	4	()
2	4	()

B to B
From	To	ChildOf
3	4	()
4	5	()

This means that to query over a given relation, we just need to find all sparse relation tables for that relation type, and whose archetypes match the query filters. This result, once again, can be cached. Feel free to take a look at the code on GitHub if you're interested in the details!

Symmetric Relations

Implementing symmetric relations was actually really easy. On all operations, we simply sort the entities in the pair by their ID, such that the entity with the lowest ID is always the first one. This way, we can guarantee that the same relation will always be stored in the same table, regardless of the order in which the entities are passed to the operation.

It also took some tuning on the query side to look for both orders of the pair, but it didn't take much effort.

Tree Relations

Tree relations were a bit trickier to implement. The main issue was wanting to provide a fast way to perform BFS on the tree. Allowing traversal from top to bottom or bottom to top would allow us to easily implement parent-child transform updates, and I wanted to make sure that the components were laid out in memory in a way that would allow for fast traversal.

To achieve this, I changed the sparse relation tables to not only be indexed by type and archetype pair, but also by their depth. Relations are then stored in the table corresponding to the depth of their destination entity. For example, parent-child relations whose parent has no parent are stored at depth 0, and relations whose parent has a parent but no grandparent are stored at depth 1.

To traverse the tree from bottom to top or vice versa we just need to store the cached sparse relation tables by their depth, and voila!

What's next?

Regarding relations, there isn't anything else really blocking in the near future. It would be cool to extend the query system to support queries with more than two targets, and implement some sort of entity destruction policy for relations (e.g., destroy all children when destroying a parent). But these are not essential features, and can be added later on.

With this out of the way, my focus will now shift to the renderer plugin. I've been wanting to tackle ray tracing for a while now, and I think it's time to give it a shot. We'll also be working on a new demo soon, so stay tuned for that!

Hello World

2023-11-10T10:06:00+00:00

Hello everyone, and welcome to the very first post of the Cubos engine blog. This is where we'll be posting updates and information about Cubos Let's start today by talking about what Cubos is!

Cubos is an open-source game engine with two core features: everything is made out of voxels, and the engine is built on an entity component system. You can find the source right here. Up to this point, our work has built a powerful core and an array of plugins that give Cubos a lot of the necessary functionalities to make a complete game. We have also been working on a suite of tools called Tesseratos that you can plug into any game you're making with Cubos to help with development. It provides, among other things, editors for scenes, entities, palette.

So, what are we working on?

Right now, our current goal is to have an engine that can feasibly be used in game jams. This means building some important engine plugins that we are missing, such as the physics plugin, and to create more tools to allow swift development, like a transform gizmo so you can move objects around with your mouse.

Thank you for your interest in our engine. Come with us, as we keep you updated on the developments, adventures and trials Cubos goes through.

See you soon!

Cubos Engine

The First Cubos Jam

Roll Racers

The Theme

Voxel Modeling

Map Generation

Physics and Collisions

UI

Audio

ECS Troubles

Whats Next?

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

The "Ondisseia" of Cubos

The Jam

Game Development

Voxel Art (@NunoBaptista)

Playtest

Android Features

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)