The Machinery — February 2022 (version 2022.2)

Are you interested in meeting up with some of the Our Machinery team? Niklas, Tobias, and Karl will be in San Francisco during GDC week and if you are interested in using The Machinery or just want to chat, we’d be happy to talk to you. You can either come to our meetup on Wednesday, March 23rd, 4-6pm at Causwells, 2346 Chestnut Street (RSVP here) or schedule a private meeting with us by mailing [email protected]. We stay away from the crowds and always mask up to keep things as safe as possible.

As usual we have a bunch of fixes and new features for you this month.

If you are already running The Machinery, this new release should pop up in your Downloads tab. Otherwise, get it from our download page and have a look at this quick introduction video. We are also working on two books about The Machinery. One is an overview of the engine and the other one a collection of tutorials on how to do specific things. Note that both these books are still works in progress.

If you find bugs in this release or have requests for specific features, post them to our issue tracker. For more general discussions, hit us up on GitHub discussions or Discord.

Key highlights in this release are:

And as usual, we have a number of smaller updates.

Cinematic Depth of Field

A new component has been added that implements physically based cinematic/bokeh Depth-of-Field. The implementation is based on A Life of a Bokeh presented at Siggraph 2018, and Real-time Rendering of Physically Based Optical Effect in Theory and Practice from Siggraph 2015. The implementation aims to provide artists with a workflow based on real-life camera optics in order to keep optical consistencies. There is still more work to be done for this effect like improving the quality for very large bokehs.

Cinematic Depth of Field

Cinematic Depth of Field

Custom UI Icons

The icon interface in ui_icon.h has been extended with support for custom icons. You can either add additional icons from The Machinery’s default icon font — Ionicons — or you can extend it with completely custom icons from your own font.

Custom UI icons

Custom UI icons

Compressed Buffers

We’ve added support for LZ4 compressed buffers in saved projects (both in the Database and the Directory format). The compressed buffers can significantly reduce the size of the project data.

Currently, the engine will read projects with compressed buffers, but it will never write compressed buffers to disk.

The reasoning behind this is that if we enabled compressed buffers for all projects immediately, then a project saved with a new executable could never be opened by an old executable (since it wouldn’t understand the compressed format). By enabling reading of compressed buffers first, once we enable writing, older executables will already know how to

Thanks to Tisten for contributing to this feature.

Community Contributions

  • Thanks to Tisten for multiple contributions:
    • More logging during collaboration. #886
    • Fix for the dropdown menu width. #885
    • Scroll view for the reference inspector. #884
    • Fix for duplicate type names confusing the Visual Studio debugger. #870
  • Thanks to Selmar for fixing a crash in the Open File Dialog of the Truth Inspector. #876
  • Thanks to lachsinc for a fix in locating Visual Studio. #857


  • Fix for crash related to Discord integration and shutting down the Discord Application.
  • You can now host a server via: --host-nat-server [password], --host-internet-server [port], or --host-lan-server
  • The last collaboration mode is now remembered.
  • Bad serialization data from a client now won’t crash the host. #1023
  • Fix for crash from client_load_state(). #1045
  • Fix for synchronization of overridden flags. #1013
  • Fix for deleted assets duplicating on client after Undo of delete. #869
  • Import DCC assets and extracting assets is now more reliable in collaboration.
  • Fix for crash when synchronizing projects larger than 4 gigabytes over collaboration.


  • Fix for some debug visualizations not being stable when TAA is enabled.
  • Fix for crash in the Vulkan render backend when a resource is not freed that uses a dynamically allocated debug name.
  • Fix for area light not taking color and attenuation into account for clear coat layer.
  • Make sure readbacks of GPU buffers and images end up in CPU cached memory.
  • Vulkan backend now correctly respects the tm_renderer_memory_map_flags and will guarantee that CPU cached memory is returned when requested.
  • Fixed resource barrier issue in GPUSim system.
  • Performance fix for forgetting to reset update_shader_variables in tm_render_component_public_t after updating.
  • Code cleanup and documentation pass of tm_ui_renderer_api.
  • Removed feature flag for vector fonts as it’s been enabled for more then a year without any issues.
  • Fix for SSAO artifacts causing an outline for objects against the skydome.
  • The Light Component now uses a clustered acceleration structure for culling of all local light sources. Clustering runs in two passes: First all lights are binned into a course cluster structure on the CPU to estimate a reasonable maximum number of intersecting lights per cluster. Then a more fine-grained cluster structure (32x16x32) is built on the GPU using compute which becomes the final acceleration structure.


  • Fix for scrollbars always rendering to main UI layer instead of the specified one.
  • Fix for camera controller not accepting Alt Gr as a valid Alt key.
  • Fix for EV100 and false color legend text getting cut off.
  • The Default OS window sizes will now be used if a window bigger than the available screen resolution is created. #233
  • Substantial performance improvements to Device Memory Debug visualization.
  • Fix for one frame glitch in preview tab: make sure to reset primitive drawer buffers on tab__set_root().
  • Clean up of image previewing. Avoid showing UI if no image is active. Fix for frame glitches when switching between image assets.
  • Better numbering scheme for duplicated objects. #951
  • Fix for mouse up events being lost during long stalls. #1050
  • Fix for possible infinite loop when rendering multiple lines of text. #1048
  • The Crash Recovery dialog is now only shown if there were any actual changes to the project data before shutdown. Previously changes to things like the selection could trigger the Crash Recovery dialog. #784

Volume Component

  • Revamp for the volume component sorting API function. This is now split up into two functions for clarity and safety.


  • A new Simulate Tab is now opened for each different Entity when the Play button is pressed in the Scene Tab. #976
  • The Network Node Type Menu is now disabled if there is none available.

Entity Tree

  • Automatically enter Rename mode when adding child Entity. #719
  • Added “Move to New Parent” feature #716
  • Open root context menu if right clicking on background. #718
  • Fix for Shift + click selection not always working properly. #721
  • Fix for focus event being sent on both mouse Pressed and Released. #822
  • Implemented Multi-object context menu. #715
  • Fix for Entity Name not being clipped correctly when buttons are not present.
  • Multiple optimizations to improve child reordering and sorting time. #1007

Entity Spawner

  • Added physics to the Entity Spawner, any instanced entity that has a physics shape specified will automatically have a physics representation created for them when they are spawned by the Entity Spawner Component.

Graphs (general)

  • Added shortcut Ctrl+Left/Right for moving in the Graph History. #1077
  • Graphs show now a visual indication of what kind of graph they are and the name which is either the owning entity or the asset in case the graph has no name set. #924
  • Instantiated nodes are now marked with a blue triangle in the corner as opposed to having a blue line under the name.
  • Invalid connectors now have a red marking on the connector instead of a general marking on the node, so one knows which connectors are in error.
  • Many nodes that previously had required connectors are now optional.
  • The connector rectangle is now only filled if there is a connection connected to the connector, if there just is data on the connector, then it will not be filled. If data and connection is missing and the connector is not optional, then a red warning will be shown on the connector.
  • Added support for tooltips on connectors. #1038
  • Fix for tinting of comments being disabled.
  • Graph comments can now be resized by dragging any side of the comment. #998
  • Added a tooltip on how to move a comment without dragging the contents within.
  • Comments now snap while resizing. #996
  • If an output or input lacks both name and display name, the input or output node will now write the type name on the connector.
  • Fix for subgraph nodes not showing correct values when viewing public inputs of instantiated graphs. #880
  • Fix for inherited and removed connections being editable by dragging their endpoints.
  • Graph nodes are now pasted at the mouse location. #1033
  • Any endpoint of the graph connections can now be click-dragged to reconnect the connection. Holding Ctrl force-creates a new connection instead of dragging an old one. #997

Creation Graph

  • Fix for a crash in the Creation Graph when a graph is destroyed while it is running.
  • Preview of a Paint Node in the Creation Graph. This node can be used to do general painting and will see lots of development in the coming releases. It is hidden behind feature flag “Paint Node”.
  • Creation Graph nodes can now expose scene tab toolbars for when the component containing the creation graph is selected. This is used by the Paint Node.
  • Creation Graphs can now have general auxiliary data, i.e. data living within the Creation Graph object but outside of the Graph object that is contained within the Creation Graph. This is so that data associated with the Creation Graph can be changed without invalidating the Graph itself. This is used to store Paint Node brush strokes.
  • Fix for Cached Node Results leaking and not being deinitialized correctly. Put in a migration to remove the previously leaked items, which could make it so that you had more buffers that you should have in the project.
  • There’s now support for up to 16 indirect draw call commands per GPUSim System.
  • Added an Entity Spawner - Refresh event node that lets you schedule a refresh of all channels in an Entity Spawner component directly from within a creation graph.
  • Crash fix when setting the name of a Variable node to an empty string.
  • Refactored how images are managed internally, it’s now possible to build long image processing pipelines that correctly evicts GPU representation of images between each step.
  • Fixes to the Compress Image (Crunch) node
    • Separation between low-level settings and high-level settings.
    • Proper support for cancelling ongoing compression tasks.
    • Support for setting the compression format to Uncompresed which results in a pass-through node.
    • Bug fix for failing to detect compression settings on frequent changes or even hanging The Machinery.
  • Helper methods in tm_creation_graph_api to simplify detection of dirty marked or version bumped Creation Graphs.
  • tm_creation_graph_api->has_event() now gracefully handles invalid creation graph instances.
  • New Submit Draw Call event node for explicit scheduling of draw calls on an event.
  • There’s now a public interface for tm_gpu_simulation_system_o that allows for creating a GPUSim system from any plugin.
  • Fixes for race conditions regarding queued background tasks and creation graphs getting destroyed.
  • Fix for Construct Transform node not taking scale into account correctly.

Entity Graph

  • Added support for Default Preferred Output connectors via the GGN_PARAM_CONNECTOR_PREFERRED macro. #963
  • Debugger Tooltips in the Entity Graph are always visible #1067
  • Entity Graph components are now also created for the entity context used by Scene Tab. One possible use case is for building various types of tools and editor interactions directly using entity graphs.


  • The tm_physx_scene_api has new functions for directly creating actors and physics shapes, this is used by the Entity Spawner to create physics representation for instanced entities.
  • Added a Culling Box when the PhysX Visualization is active. This means that there is a configurable box size that follows the active camera, outside of it, no physics visualization is drawn.
  • Fixed rounding error in PhysX height field visualization
  • Fix for crash if we fail to create a PhysX actor. #1052

Scene Tab

  • Fix for drag-and-drop placement of entities not working correctly in the sense that the entities were not placed on top of the entity under the cursor.
  • Fix for a performance issue when duplicating many objects. #1010

Asset Browser

  • The asterisk marking modified assets is now always visible. In detailed views it now sits to the left of the name. In the icon view it sits in the corner of the icon.
  • Optimization to make refresh of thumbnails faster.


  • Creating a workspace with the default layout now works as expected.

Task Manager

  • Fix for task manager not being possible to interact with when it is drawn in the overlay mode.


  • Command line argument --headless can be used to start in headless mode.
  • Headless mode has some extra logging so you can see what is going on.
  • TM_LOG_HEADLESS(...) can be used to do headless-specific logging.


  • Projects can be published from command line by combining --publish with --load-project.

Truth Inspector

  • Still in preview but the feature flag has been removed.
  • The list of objects per type can be sorted by Name.
  • The list of objects per type shows names of type prototypes if the name is not present but part of the Asset.
  • Generally added paging to all long lists.
  • We added a new tab that allows you to see type differences between the original type (registered via the tm_the_truth_create_types_i) and what is actually currently present in your Truth.
  • Better highlighting for temporary objects — objects that wont be saved to disk when you save your project) in the object list.
  • Visual Highlighting for Default Objects in the object lists.
  • We added a new tab that allows you to have a overview of all temporary objects.
  • We added a overview of all objects that are referenced the current object.
  • We added a overview of all objects that use the current object as prototype base.


  • Fix for rare race condition in tm_runtime_data_repository_api.
  • Crash fix when writing crash recovery change lists to disk if it they exceed 4GB.
  • tm_the_truth_api->uuid() is now safe to call from any number of threads running in parallel.
  • Fix for rare crash after attempting to load a broken project.
  • Added tm_task_system_api->wait_for_task(). #1051
  • Added TM_FEATURE_FLAG__MATCH_REFERENCES_ON_IMPORT — when set, we will try to match references in the existing project when importing assets instead of duplicating references from the imported project.


  • Selecting a state now updates the Properties view even if that state was selected before. #1003
  • Selecting any node in the Animation Tree now sets the Preview to preview the Animation State Machine. #1002
  • Better copy/paste behavior in the Animation Tree.
  • Duplicate, Rename and Delete shortcuts in the Animation Tree.
  • Selecting a state in the Animation Tree View now updates the State Graph. #994
  • Fix for drawing issues in the Animation Preview.

Build System

  • The Debug project configurations in Visual Studio are now properly called Debug instead of Debug | Win64.
  • The Samples can now be built with TM_SDK_DIR set to point to either a binary release or the checked out source code of the project.
  • Fix for building The Machinery with spaces in the project path. #878

Entity Component System

  • Fix for crash when setting non-existent entity properties. #873
by The Machinery Team