ToyMaker is an open source, extensible, single-threaded 3D game engine written in C++ on top of SDL3 and OpenGL.

In ToyMaker, scene data is described in JSON and managed through a combination of ECS and scene tree APIs. Demo projects using ToyMaker have been compiled successfully for Windows and Linux.

Fill Container 1

Fill Container 2

Fill Container 3

Examples/FillContainer – shows spheres spawning at a steady rate filling an invisible container, with several collision checks and corrections taking place every frame.

Triple Pendulum

Examples/TriplePendulum – shows set of granular single degree of freedom position constraints being used to model the behaviour of a hinge joint in a triple pendulum.

Slope Friction

Examples/SlopeFriction – demos friction forces causing a moving block to slow and come to a stop sliding down a gentle incline.

Many Lights

Examples/ManyLights – scene containing 441 point lights and 441 models (2 meshes each) rendered with instancing for both.

One One Collision

Examples/LeftRightCollision – shows single one-to-one collision between two spheres.

Resizable UI

Examples/UILayout – shows UI elements being dynamically repositioned in response to window resizing.

Interactive Center Text

Examples/CenterText – demo featuring clickable text that spins on interaction.

Technologies

History

ToyMaker started out as a personal learning project in 2023, when I began studying OpenGL and learning graphics programming. It was undifferentiated from Game of Ur until 2026, when it was moved into its own respository. ToyMaker’s commit state history leading up to the division may be browsed on this Game of Ur tag.

Architecture

Entity-Component-System (ECS)

ToyMaker is built on top of an ECS system that exists side-by-side with its scene system. Scene data, such as transforms, object bounds (or colliders), physics state, etc., are stored as simple (or as close as possible) plain-old-data types, in tightly packed component arrays. Each component instance is additionally tagged with the entity ID of its owning object. The set of all components across all arrays marked with a specific entity ID describe a single object in the scene that the ID names.

An example of ECS in action.

ECS systems (derived from ToyMaker::System) roughly represent the various ways in which scene data is mutated over an application’s lifetime. Each system tends to access no more than a handful of components for each entity (e.g., the render system mainly deals with transforms and models, while the physics system cares primarily about object bounds and physics state), and declares which components these are. Components named by these systems end up becoming ECS components.

Keeping component data in tightly packed arrays, coupled with the fact that any single system only requires data from a handful arrays at most, leads to significant performance gains owing to cache locality. For convenience, however, the ECS::Entity class provides an interface for accessing object data in a near object-oriented fashion.

Resource Database

Static resources, i.e., reusable resources which aren’t likely to change over the runtime of an application, are tabulated, serialized/deserialized, and provided shared access to through ToyMaker::ResourceDatabase. Examples of data of this kind include 3D models, images/textures, sounds, and even shader programs.

An example scenario involving the storage and use of resources.

Each resource may be constructed in a variety of ways; models, for example, may be generated procedurally, or loaded into memory from a file. Accordingly, each resource, inheriting from ToyMaker::Resource, may be associated with several resource constructors.

The resource database is a global object that shares references to named resources already in memory, or otherwise constructs that resource according to its user-provided description, where the description is usually registered with the database at the start of the application.

Update loop

ToyMaker’s update loop is broadly split into 3 distinct steps:

  1. The fixed update: This is where logic that ought to be independent of the speed of the underlying hardware goes. ToyMaker’s Physics system lives here, mostly. The size of a single fixed-step is configurable. How often this runs relative to the variable update depends on a number of factors, including user hardware, and the number of simultaneously running applications.

  2. The variable update: This is where logic that is less sensitive to time goes. Typically, scripts will receive input and set input related parameters from here. Updates related to game visuals, that don’t depend on a reliable simulation, often also go here.

  3. The render update: This is where ToyMaker’s render system will use scene data and render it to a 2D image to be displayed to the user. How often this runs once again depends on user hardware, application configuration, and the current state of the user’s machine.

Scene System

ToyMaker’s scene system provides a logically hierarchical representation of the scene. It is comprised of a number of scene nodes, inheriting from ToyMaker::SceneNodeCore where each node holds a weak reference to its parent, and strong references to its children.

Usually, each child node will apply its local transform after its parent has applied its global transform in order to obtain the node’s final position, orientation, and scale. The combination of the current node’s local transform and its parent’s world transform becomes the current node’s world transform.

From the point of view of the resource database, a scene is merely another type of resource that can be constructed either through its description, or loaded from a scene file.

Viewports

The scene may also have viewport nodes. A viewport node, along with its associated camera, provide a rendering target for a single ECS world. Multiple viewport nodes can be associated with one ECS world, potentially showing the state of the world with different perspectives and rendering configurations. Alternatively, a viewport node may opt to own its own ECS world, marking the boundary between its parent’s world and its own.

A viewport node with its own ECS world is useful for a number of things, including making a UI overlay over a 3D scene, or making a game-in-game style feature. A viewport node that shares its world with its parent can be used to implement interesting features, like reflections, FPS scopes with a different FOV from the regular first-person camera, or a split-screen for local multiplayer.

Aspects & Sim Objects

Quite often it is the case that developers would like to define behaviour directly on top of the object that should exhibit that behaviour – as opposed to fiddling with the constraints and indirectness of ECS systems. For that purpose, ToyMaker provides a component-based scripting interface, that it calls sim objects and aspects.

An aspect is a user-defined script – similar to a MonoBehaviors from Unity, or scripts in Godot – that are hooked into application loop events, and that provide full access to the components of the scene node that owns it. It also provides methods for querying scene nodes relative to the one it’s attached to.

A sim object is simply a special subclass of scene node that is capable of hosting one or more aspects. It is also the only scene node class eligible to be the root of a scene described by a scene file or scene description.

Rendering System

The render system is responsible for actually displaying the scenes ToyMaker manages. It does so by periodically reading scene data and turning it into images through a combination of various techniques.

The render system is divided into render sets – a set of target color and depth-stencil buffers allocated for a single viewport – and some sequence of render stages. Each render stage represents a combination of CPU and GPU work, resulting in the addition of a specific effect to a target image, or the creation of a certain resource that is intended to be used with the target image.

Clip showing intermediate textures generated in the rendering pipeline

A flowchart describing the rendering pipeline.

At present, each render stage is associated with a single OpenGL shader program, and the only rendering pipeline supported by ToyMaker is a 3D Blinn-Phong deferred shading pipeline with the following stages:

  1. ToyMaker::GeometryRenderStage – Converts input mesh-material pairs into albedo, specular, and position textures, collectively called geometry textures.
  2. ToyMaker::LightingRenderStage – Uses geometry textures and light data to produce a texture of the lit scene.
  3. ToyMaker::SkyboxRenderStage – Adds a cubemap background to the lit scene.
  4. ToyMaker::TonemappingRenderStage – Applies gamma correction and camera exposure post-processing effects to the lit scene.

Physics & spatial query systems

The physics system is responsible for simulating physics for appropriately tagged entities in the scene. It does so through an implementation of XPBD, or Extended Position-Based Dynamics.

Each entity managed by the physics system possesses physics state, and object bounds. Every fixed step, the physics system predicts where each object should end up next:

  1. Using the sum of forces acting on the center of mass of the object, compute the change to its velocity, and add it to the object’s previous velocity to find its new velocity.

  2. Using the sum of torques acting on the object, compute the change to its angular velocity, and add the change to its previous angular velocity to find its new angular velocity.

  3. Using the velocity of the object, compute and apply the change to the object’s position in this timestep.

  4. Using the angular velocity of the object, compute and apply the change to the object’s orientation in this timestep.

Then, the physics system corrects all violations of applicable physical constraints:

  1. Get the collision response data for a pair of intersecting objects.

  2. Compute the generalized inverse mass for each object.

  3. Use collision data to compute a Lagrange multiplier delta.

  4. Use the Lagrange multiplier delta to compute a positional correction impulse.

  5. Apply the correction impulse (in opposing directions) to both objects.

  6. Derive the new velocities of each object.

… where a constraint is anything from a collision, to a joint between two objects, to an implied spring connecting two objects.

This update is performed one or more times every fixed update, where the fixed update itself takes place 10s of times each second per the application configuration. Optionally, the system can use signals to report collision events to scripts and other systems. Collisions are resolved using GJK, with sweep and prune used to minimize the number of times GJK is required to run.

ToyMaker’s spatial query system provides an interface for answering most spatial queries; for example, what is the closest object to this object? Do these two objects intersect? What objects exist within a given region? And so on. It does so through a dynamic Octree implementation.

Inputs

ToyMaker’s input system translates raw input from the platform running the application into actions, which are abstracted normalized inputs directly consumable by systems and scripts. The input configuration informs the application which raw inputs map to which actions. It tends too look something like:

   W    ______
 A|S|D        \___.--> Character : Move (2 Axes) --> (Move handlers)
<keyboard>     /
              /
             /
 (( L ))----/
<controller>

Window context

For the time being, the window context is a simple wrapper over SDL that requests a window from the operating system, initializes the OpenGL context, performs initialization for other libraries ToyMaker depends on, and reports window level changes to scripts and systems managed by the ToyMaker engine.

Signals

This is a two-part lightweight implementation of the observer pattern, enabling the decoupling of signal publishers from its consumers in the engine environment. An object will either play the role of a signal publisher, broadcasting the fact that some specific event took place, or the role of a signal observer, which takes some action when such an event occurs. Any single object often plays both roles, advertising its signals to other objects, and listening for events from other objects, and this capability is represented as the signal tracker base class.

As to why this is necessary: a script that is responsible for applying damage in a game, for example, should not need to know that the damage should cause a sound to play, or for some metric to be updated. It should only do what it is intended to do, which is update health numbers, and leave further processing to systems subscribed to its signal.

References