Tutorial, optimisations, and other improvements

Hey everyone, time for another long overdue update on what I’ve been up to lately!  I’ve mostly been focused back on building the in-game tutorial scenario, but I’ve also continued working on the game, both adding features to support scenarios, and making other general improvements.

Performance Optimisation

I noticed some performance issues, particularly with a large number of parts or constructions, so I decided to spend some time addressing these.

UI optimisations:

  • UI elements now only resize themselves to content when something changes, rather than every update.
  • Improved performance of link and part intersection indicators when looping through part instances.
  • Improved the compass overlay implementation (no longer sets gameobjects active / inactive).
  • Optimised the scene tool UI’s construction list update.

Other optimisations:

  • Removed unnecessary calculations from the construction update function.
  • Eliminated the composite update function altogether.
  • Eliminated or simplified some other fixed update functions.

These changes save over 1 ms on the main thread when there are a lot of parts / constructions in the scene (totalling a couple thousand parts or so).

Speaking of which, I’ve also investigated using Unity jobs to move work off the main thread.  This has the potential for some more significant performance improvements.

Here’s what I have planned:

  1. Gear and pulley wheel behaviour constraint updates – The code that figures out if a pair of gears are engaged, and the location of their engaged “teeth” (info that’s then used to update the ConfigurableJoints).  This could be done in parallel in jobs I think.
  2. Wheel behaviour constraint updates – Each wheel does a CapsuleCast and some other trickery to approximate a cylinder that smoothly rolls on the ground.  This is a prime candidate for using the CapsulecastCommand instead.
  3. Part selection’s “find valid attachments” code – Does a lot of OverlapBox calls if a large number of parts are selected, should be perfect case for replacing with the OverlapBoxCommand.
  4. Collision contact reporting (used for impact sounds etc.) – Horribly inefficient at the moment, but Unity just introduced the Physics.ContactEvent, which should be exactly what I need to improve this.

All but the first of these tasks will require upgrading to Unity 2022.2 though, which feels a bit risky at the moment.  I’m going to hold off until the LTS version comes out.

Unity 2021 upgrade

In the meantime however, I have upgraded to Unity 2021.3 LTS.  I had tried upgrading to 2021 a while ago, but found a couple of game breaking issues.  These seem to have been fixed now, and the upgrade went pretty smoothly this time.

The only slight issue is that old saved construction preview images now won’t load (compressed image size needs to be multiple of 4), but this can be resolved just by re-saving them first.

Building improvements

I’ve made various minor improvements and fixes to the building system:

  • The part selection pivot point can no longer be moved below the ground, preventing a construction from being “lost” underground.
  • Now only the move manipulator handle has “drag thresholding”, the translation handles move instantly.
  • Engagement indicators are now shown for all gears in the part selection during alignment.
  • Commands are now added to the undo / redo history when links are removed while detaching parts.
  • Fixed a bug where destroying an unfrozen construction didn’t add a command to the undo / redo history.


I’ve also made a few minor improvements and additions to the parts:

  • Implemented a resizable “L Plate” part, useful for connecting stuff at right angles.
  • Added checks for player distance and facing direction to the control wheel part behaviour (prevents the control wheel from being used when the player is too far away).
  • Added a light part behaviour option to disable shadow casting, useful if you want to save performance for a construction with a large number of lights.
  • Fixed a bug where spring damper / linear actuator pistons could be attached to the wrong alignment point.

Here’s what the L Plate part looks like:

Lua scripting

I’ve worked on various new features that are available for use from within Lua scripts (as scenarios or script mods), mostly to support what I need for the tutorial scenario.

Video player

Implemented an in-game video player, with an interface that allows video players to be created from Lua scripts.  Here’s a test Lua script, showing a video playing in a window:

I’m planning on using this to show short explanatory video clips in the tutorial scenario.

Scroll list UI element

Implemented a scroll list UI element, can be added to a window like any other element, but then other elements can be added to it (including more scroll lists!)  For example the undo / redo command history script mod can now show a larger history that can be scrolled through:

Unlabelled UI elements

Added unlabelled variants of the slider, input field, and dropdown UI elements for more flexibility.  Shown here in this Lua UI unit test:

Profiling metrics

Exposed performance profiler metrics (e.g. memory, rendering etc.), so that script mods can implement custom profiler UI windows, for example:

Tutorial scenario

My original plan was to have multiple little tutorial scenarios, each one introducing a few new concepts at a time.  As I mentioned in a previous post, this idea turned out to be a bit boring in practice, and didn’t really create a good first impression for the game.

So then I pivoted to having one large scenario with a lot of things to do in it, essentially combining the separate tutorials into one that are followed through step by step.  However as I started to build this out I realised it was getting too big and complicated.  Apart from anything else, performance was getting to be marginal with so much going on in the scene at once.

So, I went back to the drawing board and reworked my design, trying to really focus on what concepts I wanted to introduce in each tutorial stage, and what concepts to reinforce from previous stages.

The result is a bit more pared back than what I had before, but I think it should still be fun.  It will still be a single scenario / scene containing multiple activities that the player goes through, but with less extraneous stuff.

The first few activities will get the player used to activating and using part behaviours, using the construction menu, and so on.

After which, each activity will require the player to do something (e.g. attach a control wheel, reposition a gear, link some pulleys, etc) that will allow them to open a box with a part inside.  When they’ve completed all the activities they can collect all the parts together and build something out of it, as the final step (using everything they’ve learned so far).

For example, the first of these activities is to simply use the builder tool to move a weight and place it on a platform.  Things ramp up in complexity from there!

The design is now complete, I have built all the individual constructions for the scenario, and made a good start on the Lua scripting.  I’m planning on making another (small) map for the game, to be used for this tutorial (and any others to follow).

This tutorial scenario is really there to get new players used to using the building controls, it doesn’t go much beyond that.  I would like to also build additional tutorial scenarios that teach advanced use of gears, mechanical principles, have more complex puzzles to solve etc.  These will have to come after the early access release though.