The Machinery - Part 1

Intro

The Machinery is an exciting SDK and toolset that is currently in a closed beta period and I was recently given access (anybody can apply, I have no contacts or special credits to my name).

There are many reasons why The Machinery is interesting and I'll try to avoid repeating things you can read on the blog.

Two things stand out to me and motivate exploration:

• The SDK and engine are primarily developed in C with some excellent constraints to keep the design clean. This provides developers with interesting possibilities right out of the gate.
• Modularity is a principal goal for all aspects of the SDK.

Getting Started

The invitation to the beta comes in the form of an invitation to their forums. It's powered by Discourse which is a nice and familiar platform these days.

Beta releases, like their alpha releases before that, are distributed as attachments to associated topics in the forum. The current beta package is a delightful 34Mb in size! It only targets Windows initially. Internally they support other platforms, but sensibly the beta releases are limiting the platforms to focus on more important things.

In addition to the SDK archive, there is a sample projects archive that's 165Mb. This consists of a series of projects with asset data actually baked into project files, and a set of focused plugin examples with source code.

Once downloaded I don't have any idea how the SDK is meant to be used or organized so I just plopped it into c:\projects\slowgames which is my monorepo for all things slowgames.

I have been using Perforce for this monorepo for a while, however recently I started using PlasticSCM to see if I like it a bit more given it's git-like proclivities. So far, the answer is 'meh'.

So, now with these archives downloaded and unpacked let's continue by looking at the SDK contents:

c:\projects\slowgames\OurMachinery>ls -l
total 76
-rw-r--r-- 1 phote phote 62326 Jul  9 18:25 README.md.html
drwxr-xr-x 1 phote phote     0 Jul  9 18:25 bin
drwxr-xr-x 1 phote phote     0 Jul  9 18:25 code
drwxr-xr-x 1 phote phote     0 Jul  9 18:25 doc
drwxr-xr-x 1 phote phote     0 Jul  9 18:25 headers
drwxr-xr-x 1 phote phote     0 Jul  9 18:25 lib
drwxr-xr-x 1 phote phote     0 Jul  9 18:25 samples
drwxr-xr-x 1 phote phote     0 Jul  9 18:25 utils

I really really hate the Windows 10 desperate need to chop off the 'x' from my username. What the hell is the reason for that?

Nice, a README. A 61kb README full of excellent information about how to work with The Machinery, the key concepts introduce and outline the ideas behind how data should be worked with, ideas for scene organization, introductions to the primary editor modes, and the basics of extending the engine via the plugin system.

After going over the README a bit and getting that early feel for things, it's time to run the editor and play with some samples.

When you open bin\the-machinery.exe You get the default scene:

That isn't entirely true, what you get is a "Windows Defender" warning about this being an unsigned binary or something. Which is perfectly reasonable given the beta status.

From here you can easily load any of the sample projects and dig around.

The pong example provides an interesting look into using the Graph component, which is their visual scripting system.

The first and third person gameplay examples take the approach of showing how to implement gameplay via the plugin system.

The other samples all try to demonstrate particular available systems or features. There is a lot to take in, the samples are focused and good at their job I think.

Building a Component

Our Machinery have a nice post explaining their thinking behind the provided build tools.

The short version is that The Machinery includes a tool called tmbuild that generates projects with premake, runs the build, and possibly any unit tests in the plugin you're building.

I've never used premake so this is all a bit new to me. I'm disappointed that I'm not able to easily use CLion. I'm comfortable with VS Code and Visual Studio. I just consider CLion and Emacs to be better at editing code. My current Emacs setup for working with C and C++ relies on a clang compilation database to be available and without it, VS Code is just the better choice. Can premake generate compilation databases?

It does all of this quickly and easily, but also in a bit of an annoying way. The first thing I did was run around the SDK and run tmbuild in any directory that contained a premake5.lua. But the result, aside from everything building fine and dandy, is that the SDK is now litered with extraneous folders and solutions.

For every build you'll end up with a lib folder which contains 7zip and premake. You'll also get a Visual Studio solution next to your premake script and a folder named build with any project files referenced by the solution as well as a folder for intermediate build outputs. For now I'm just going to accept that as it is and contiue on my merry way.

We can use the editor to initialize a new component for us (including a premake script :+1:).

As someone new to premake it's a wallop to take in, but thankfully some key lines are easy to spot at the bottom:

project "foo_component"
    location "build/foo_component"
    targetname "tm_foo_component"    kind "SharedLib"
    language "C++"
    files {"*.inl", "*.h", "*.c"}
    sysincludedirs { "" }
    filter "platforms:Win64"
        targetdir "$(TM_SDK_DIR)/bin/plugins"

So in the end, we have premake generating projects and setting the actual output to the SDK plugins folder. This means that it would likely be straight-forward to use another build system or project structure.

Something about this makes me wonder what is expected for project organization. Should you vendor in the SDK per-project? It certainly seems that way.

Going Forward

This is a difficult post to write because I've been mostly working from memory and trying to recap my process of fumbling around and starting to feel comfortable with everything. I don't want to copy and paste information you'd get in the README, or from their blog. And in general I have a lot of opinions and reactions I'm still chewing on a bit.

In the next post I'll talk about how I've decided to structure my exploration for the time being, and we can look at a minimal component and play around with building and hot reloading. Posts should get a bit more focused after that.