More tutorial and scripting improvements

Hey everyone, it’s been months since my last dev blog update! As you will hopefully have seen, I recently announced the coming release of GearBlocks into early access for November 9th.

A lot of my time lately was spent preparing for this announcement. The trailer video was the biggest chunk of this work: planning, building content in game (including many new built-in constructions!), capturing footage, and editing it all together. I also improved the Steam store page and website with new screenshots, gifs, blurb, presskit, etc.

Tutorial scenario

I recently took the game to a local indie meetup, and had a few people try out the tutorial scenario. It was really useful and informative to watch people play it in person. The feedback was somewhat sobering though, some found it too complicated and struggled with information overload!

So I made some changes to the tutorial to try and simplify the information presented to players, and added more code to handle edge cases where players were getting stuck.

I’ve also set up a new build configuration for a special demo build with just the tutorial scenario in it, which I’m planning to use for the Steam Next Fest (coming on October 9th).

Lua scripting

I’ve continued to improve the Lua scripting interfaces, exposing more properties and methods for manipulating parts and constructions, adding more tool interfaces, and more vector / quaternion math stuff.

Further improvements were made to some of the included script mods, including the builder tool extensions (now with the ability to set / snap the pivot position & orientation, change the manipulators to work in world or local space, etc.)

Kit building

For the trailer video I wanted to show time lapses of some constructions being built. I also want to try creating scenarios where the player follows instructions to build pre-designed blueprint constructions, a bit like building from a model kit.

So I implemented a feature I’m calling “kit building”, to cater for both of these situations. Parts can now be assigned a stage index and constructions have an active stage that can be set (where any of their parts in higher stages than the active one are hidden).

I made a script mod tool for setting part stage indices, and previewing a construction’s stages. I actually used this tool when capturing for the trailer, just manually advancing through the stages in order, revealing the parts.

I also prototyped a kit building scenario with a simple Lua script to allow the player to advance through a blueprint construction’s stages, automatically spawning the parts they need to build that stage. This idea has potential I think, but will need work to make it more user friendly.

Minor demo update

I decided to release another quick demo update, out now with some fixes and other small tweaks:-

  • Minor UI improvements, including a new “getting started” window that shows some helpful pointers when launching into a new game.
  • Improved attachment locking undo / redo (single command for multiple attachments).
  • Bug fixes (including fixing the differential idler gear centre-of-mass again).

GearBlocks Gameplay Trailer – Coming to Steam Early Access this November!

Wishlist and play the demo:

There are many things still to improve, but you guys have been waiting for so long, I think it’s time to finally get GearBlocks into your hands! My planned Steam early access release date is November 9th. I’m also planning on entering the Steam Next Fest from October 9th to 16th, hopefully with a special tutorial demo.

Hey everyone, quite a few fixes and improvements have accumulated since the last demo update, so I decided it was worth releasing another one.

Release notes:-

  • Many optimisations to UI, overlays, and indicators. Improves performance especially with a large number of parts / constructions.
  • Minor tweaks to builder tool:-
    • Click and drag “threshold” now only applies to move manipulator.
    • Prevented dragging the part selection’s pivot point below ground.
    • Increased targeting distance.
    • Removed “Prevent Interpenetration When Attaching Parts” toggle from “advanced options” (still available in the demo by setting “PartPenetrationTestEnabled” to false in the debug console).
    • Added toggle to “advanced options” to disable the centre of mass indicator.
  • Modified control wheel part behaviour to check for player distance and facing direction.
  • Added option to light part behaviour settings for disabling shadow casting.
  • Implemented copy paste for part behaviour settings.
  • Improved part resizing indicator to show numbered unit dimensions.
  • Gear engagement indicators now shown for all gears in part selection when aligning.
  • Added settings to controls options to invert horizontal and / or vertical mouse rotation of the part selection.
  • Updated help UI screen.
  • Bug fixes.
  • Upgraded to Unity 2021.3.26.

New map, and tutorial finished

Hey all, I’ve made a fair amount of progress on the game over the past month, so let’s get into what I’ve been up to.

“Gary Island” map

One conundrum I had while designing the tutorial scenario was where to locate it (i.e. which map to use and whereabouts on that map).  I could have used one of the existing maps but they are all pretty large and “open plan”, which made it hard to lay out the scene for the tutorial.  I needed something small with clear boundaries that spatially confine the player.

For a while I had been resistant to the idea of adding another map for the tutorial scenario, but it became apparent that this was going to be necessary, and worthwhile investing the time and effort in.  So I decided to make a new map, an island surrounded by water, with a 250×250 m playable area.

For long time followers of the game’s development, I resurrected the water from those old procedural island maps!  I was also reluctant to do this actually, as introducing water brings about a whole host of implications (what happens when you go in the water? buoyancy? drag? sound & particle effects? player swimming animations?)  So for now the water is beyond the map boundary and is just there for visual effect.

As usual, first I started with making the terrain height map:


Then, painted the textures (reusing those from the other maps):


Finally, added details (e.g. grass) and trees:


Overall I’m quite pleased with how the map turned out.  It has a central area (which I’ve used for the tutorial scenario), and other areas that are connected via paths for a bit of variety.  I’m thinking this will be good for other scenarios, and also as a general starter map for players.

Water reflection optimisations

After bringing back the water, I needed to do some performance optimisations to the old reflection rendering implementation (water reflections are rendered using another camera with a view that is flipped upside relative to the main camera).

I improved the code by eliminating some expensive per-frame calls (GameObject.Find(), GetComponent(), etc.) and getting rid of GC allocs.  I also reduced the level of detail during the reflection render (by overriding the LOD bias, turning off terrain details, and reducing the tree LOD switch distance).

Finally, I added a “video options” setting to make the water reflection rendering only include the terrain & sky, or be turned off altogether (falling back to a reflection probe).

Tutorial scenario

To finish the final iteration of the tutorial scenario, first I had to create a scene in the new map.  I laid out all the constructions, checkpoints, and so on for each of the tutorial stages that the player completes in sequence.

Then I worked on the scenario scripting, organising the Lua scripts by breaking them up into the tutorial stages.  The scripts are responsible for tracking player progress through the tasks they have to complete for each stage, showing a UI window with instructions (text and videos), and helping the player get back on track if they make a mistake.  This turned out to be a huge amount of work, but I think the results turned out really well.

Here’s a sneak peak of the start of the tutorial scenario:


So the tutorial scenario is now (more or less) complete, which is a huge milestone, as that was the last major task before early access release.  There’s still a bunch of work to do, but I’m now in a position to prepare the game for release which is very exciting!

Part resizing indicator

I’ve implemented another indicator that shows unit dimension numbers near a part when resizing it with the resize manipulator.


This makes it much easier to see the part dimensions while resizing, as it saves having to look down at the part UI overlay.

Script mods

The script mods included with the game have continued to develop.  For example, I implemented a “builder tool extensions” script mod that provides an interface with options for precise part placement.

I also improved and added to the various debug tools, and added a simple “hello world” example.  I can’t wait to see what script mods of their own players can come up with!

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.

GearBlocks on Steam

GearBlocks on Steam

GearBlocks on Steam

GearBlocks on Steam

Tutorials, new features and parts

Hey all, here’s an update on what I’ve been working on for the past couple of months.

Tutorial scenarios

The main challenge I’ve had lately is with the design of the tutorial scenarios, my original idea for these didn’t work out to my liking.  They ended up being rather boring and didn’t give a very good first impression of the game.  So I decided to try a new direction to create a more entertaining experience for first time players while introducing some basic concepts.

Unfortunately this will likely mean scrapping some of the work I’ve already done, but hopefully I can reuse some of it at least.  For now I’ll say no more about the new tutorial scenario design, until I’m further along with it and more confident that it’s going to work out.

I found all this rather dispiriting and frustrating to be honest, so to try and keep myself motivated and move things forward, I’ve also been working on some other stuff!

Building improvements

Recently I’ve been playing the game a lot (to build content for the tutorial scenarios and trailer video), this has highlighted some bugs and other usability annoyances, which I’ve been fixing as I find them.

For example:-

  • When detaching selected parts from other ones, the attachment types between them would be lost, and after re-attaching them you’d have to change the attachments back to the desired type.  Now, the types are saved while the selection is being moved, and restored after re-attachment.
  • Part highlighting has been improved so that tools only highlight parts relevant to them (e.g. only paintable parts for painter tool).
  • Fixed several bugs (such as parts sometimes not attaching to engaged gears, random rotation after freezing a construction, part duplication issues, and so on).


On the subject of annoyances, I built a race car to showcase on the race track map, which was fun to drive around but really emphasised the need for proper braking.

Electric motors provide regen braking by running them backwards, but this was hard to control.  If a vehicle’s wheels had insufficient grip they’d slip and the motor would spin up in reverse.  So I made some changes to the motor part behaviour to address this:-

  • Above a certain speed a “braking direction” is now set, which is then used to prevent the motor from spinning in reverse after coming to a stop during braking (the braking direction is reset once directional control is released).
  • Added a separate tweakable value for braking torque.

Electric motor regen may not provide enough braking on its own however, and so I’ve now implemented a new braking part behaviour for wheels (that can be activated by a bound key).  This makes driving vehicles way more controllable and enjoyable.

When braking is enabled, a brake disc is shown inside the wheel.


I plan on adding separate brake and clutch parts in the future that will also make use of this same part behaviour implementation.

Analog joystick control

After spending some time driving vehicles around, I couldn’t resist implementing something that would greatly improve the experience – analog control.  More specifically, being able to bind a joystick axis to a controllable part behaviour (such as a motor).


This, in combination with braking, transforms the enjoyment of driving vehicles in the game.  It is optional however, and the regular bound keys are still a decent method of control.

Chase camera

Another thing I couldn’t resist adding was a “chase” camera, which is now selectable when the player is seated.  It’s similar to the existing third-person camera except that side-to-side movement is smoothly locked behind the seated player, and the mouse can only move the camera up and down.

This camera mode makes driving vehicles in a third-person view much easier, as you don’t have to manually track the vehicle by moving the mouse.

More parts and improvements

Again, after spending time driving vehicles, I wanted to improve how leaving seats worked:-

  • Rather than having to look down at a seat to leave it, you can now simply press the “jump” action (i.e. Space by default).
  • When leaving a seat, if possible the player is now repositioned at a free position in front or to the side of the seat, rather than on top.  This is more better for a vehicle with a roof for example, where before the player would just be repositioned on top of the roof.

I also improved some other part behaviours (e.g. key bind for differential locking, tweakable light brightness) and added several more parts (e.g. seat, gear, steering wheel, connectors) to facilitate some of the example constructions I’ve been making.

Grabber tool

Finally, I decided to implement the last remaining tool in the game, the “grabber” tool.  Although this wasn’t a particularly high priority, it was quick to implement and I wanted to get it done so that I have the option to include it in the tutorial scenarios, without having to go back and modify them later.

The grabber tool allows constructions to be moved around as physical objects, i.e. without freezing them first.

It has two modes, “grab” and “shove”:-

  1. Target part of a construction, then click the left mouse button and drag, to grab that part and drag the construction around by it.
  2. Target part of a construction, hold the right mouse button to charge up, then release to apply a shove force to that part of the construction.

The grab and shove forces are configurable, as is the ability to have free or locked rotation while grabbing.

What about the full game release?

Before the early access release of the game, there are two main tasks left I need to get done: finish the in-game tutorials and make a trailer video.

The tutorial scenarios have not progressed to where I would have liked by now, but I needed a break from them to clear my head, and work on something else.  Anyway, now I really need to focus back on finishing the tutorial scenarios, finish building content for the trailer video, and get that captured and edited.

I was hoping to release the game before the end of the year, but unfortunately it’s now looking like the date will have to slip by a few months.

This is really disappointing I know, but by way of compensation, I’ve decided to do another demo release update soon, which will include many of the improvements mentioned in this post, so keep your eye out for that!

GearBlocks on Steam

GearBlocks on Steam

Supporting features for tutorials

Hey everyone, here’s a quick update on progress over the past month.  I spent most of my time working on the tutorial scenarios, but also implementing some features that support the scenarios while also being beneficial to the game more broadly.

Attachment locking

For the tutorials, I wanted to be able to prevent the player from detaching certain parts from constructions in those scenarios.

So, I implemented an “attachment locking” feature, which allows attachments to be set as locked, preventing them from being modified or deleted.  Parts that are connected with locked attachments are selected together.

To toggle an attachment locked / unlocked, you just target it and press Left Shift + E.  The attachment’s UI indicator shows when it is locked.


Also, there are now options in the selection menu for locking / unlocking attachments of all selected parts.


Now, when setting up the tutorial scenarios, it’s easy to specify which parts should be non-detachable.

Besides, this feature is just generally useful while building I think.  It allows for creating “sub-constructions” that can’t be accidentally broken apart, but can still be detached from the rest of the construction as a single entity.

Compass HUD

For scenarios that use checkpoints, I thought it would be good to try and direct the player towards those checkpoints.  I figured the same solution could also be used to help the player find “lost” constructions.

So, I decided to add a compass HUD to the top of the screen.  It shows cardinal directions based on the player’s facing direction, as well as the direction to any constructions in the scene.

Parts can optionally override the default icon shown, this allows checkpoints to have their own icon to be more easily identifiable.



As I mentioned, the bulk of my time was spent working on the tutorial scenarios.  This is proving a lot more time consuming than I’d hoped, but I am making progress.  I have the first five tutorials mostly done now, and I’m working on the sixth one, which should hopefully cover most of the remaining basic building concepts.

I’ve also started thinking about more open ended scenarios.  As a test I made a “timed lap” scenario around one of the race track routes.  This worked out pretty well, so I’m going to make a few more of these to include with the game.


Help screen

As a supplement to the tutorial scenarios, I’ve also overhauled the help UI screen to be a better user guide and reference.  I added sections on various topics such as spawning a construction, spawning and attaching parts, changing attachment types, and so on.


I removed the page linking to the old tutorial videos, as some of them are out of date since the builder tool changes a while back.


Lastly, I’ve started looking into adding localisation (for translating in-game text for different languages).

I decided to go with Unity’s own localisation package, it seems to do everything required and I didn’t see any need to go with a third party solution.

Integrating this package and setting up the locales (i.e. languages) was nice and easy.  Right now I have English, French, Italian, German, Spanish, and Russian locales, I can add more later as needed.

As a test, I set up localisation just for the UI menu and screen heading text.  I used Google sheets to make a text translation table (just using Google translate for now), and imported that into the game.

This process worked pretty well, but the prospect of localising all the other in-game text is a bit daunting, I suspect the translation table will end up being pretty large.  I’ll have to prioritise the most important stuff and do it in stages.  Hopefully I can find some volunteers to help with the translations!