How to Create Scenarios in GearBlocks

A scenario can extend gameplay by creating a challenge, mini-game, or even a whole new game mode. Here’s how to get started making your own.

Introduction

As opposed to open ended “creative mode” play, a scenario is more structured. It might have objectives to complete, a limited part selection or tool availability, or some other restrictions.

The included tutorial, kit build, and timed lap scenarios were all made this way, and are examples of the kind of thing you can do with the system.

A scenario typically consists of a saved scene, along with a Lua script which gets loaded when the scenario starts (it configures the game and implements the scenario behaviour).

NOTE: The example scenario shown in this guide is available on the Workshop, search for “AnExampleScenario”.

The Scene

The first step in making a scenario is to set up a scene.

In the CREATIVE panel, click the “New empty scene” button, choose a map (and configure environment settings if you like), and then click the Play button.

If you want your scenario to start with an empty scene, then you’re done already, you can save it like this. However, often a scenario needs to start with some constructions already spawned.

For example, here we have a forklift truck, a green barrel on a palette, and a cylinder checkpoint:

There’s also a circle plate part representing a “gold coin”, this will be a template for some rewards we’ll spawn in the scenario script:

Now try setting up a scene that looks something like the one shown.

Once your scene is ready, enter the SAVE SCENE screen. Give it a name, description, and add “scenario” as a tag, then click the Save button:

NOTE: You must tag the save with “scenario”, so that it can be loaded from the BEGIN SCENARIO screen later.

Scene IDs

For a scenario Lua script to manipulate parts or constructions in the scene, it needs to be able to identify them. Each part and construction has a unique scene ID that can be used to do this.

To find out the IDs of objects in the scene, the included “PartInspect” script mod can be used. Load it from the SCRIPT MODS screen, under the “built-in examples” tab.

Targeting a part in the scene will show the ID of the construction it belongs to:

Make a note of the ID numbers of the forklift, barrel, checkpoint, and “gold coin reward” constructions in your scene.

NOTE: Be sure to note the construction IDs, not part IDs!

The Scenario Script

Navigate to %USERPROFILE%\AppData\LocalLow\SmashHammer Games\GearBlocks\SavedScenes, and find the folder of your saved scene (e.g. AnExampleScenario). Inside this folder, create an empty text file and name it scenario.lua:

When loading a scene from the BEGIN SCENARIO screen, the game will automatically load scenario.lua if it finds it.

Edit the scenario.lua file, and type in the following Lua code:

-- IDs of constructions in the saved scene:
local checkpointConstructionID = <id goes here>
local barrelConstructionID = <id goes here>
local rewardTemplateConstructionID = <id goes here>
local forkliftConstructionID = <id goes here>

local checkpointPosition = Vector3.Zero
local rewardTemplatePart = nil

local isGoalAchieved = false

IMPORTANT: In place of each <id goes here>, substitute the relevant construction ID number you noted down earlier.

Next, add the following functions, they disable tools and other features, and create the UI. We’re going to call these during initialisation:

local function disableFeatures()
	-- Set variables to disable game features.
	NoBuilderTool.Value = true
	NoMaterialTool.Value = true
	NoLinkerTool.Value = true
	NoPainterTool.Value = true
	NoGrabberTool.Value = true
	NoSceneTool.Value = true
	NoPartSpawnDestroy.Value = true
	NoConstructionSaveLoad.Value = true
	NoSceneSave.Value = true
end

local function initUI()
	-- Create a UI window.
	Win = Windows.CreateWindow()
	Win.SetAlignment( align_RightEdge, 20, 300 )
	Win.SetAlignment( align_TopEdge, 80, 200 )
	Win.Title = 'FORKLIFT CHALLENGE'
	Win.Show( true )
	Win.IsCloseable = false

	-- Add a text label to it.
	Label = Win.CreateLabel()
	Label.SetAlignment( align_HorizEdges, 10, 10 )
	Label.SetAlignment( align_VertEdges, 10, 10 )
	Label.FontSize = 30
	Label.Alignment = textAnc_MiddleCenter
	Label.Text = "Use the forklift to put the barrel in the target zone..."
end

Then, add the following block of code:

local function onRewardConstructionSpawned( construction )
	-- Unfreeze the spawned part.
	ConstructionOps.SetConstructionFrozen( construction.ID, false )
end

local function spawnRewards( numParts )
	-- Add a handler to the ConstructionSpawned event.
	-- This gets raised by the game when a construction is spawned.
	ConstructionSpawned.Handler.add( onRewardConstructionSpawned )

	-- Temporarily enable part spawning.
	NoPartSpawnDestroy.Value = false

	-- Spawn the reward "gold coin" parts by duplicating them from the template.
	if rewardTemplatePart then
		for i = 1, numParts do
			-- A random location near the checkpoint.
			local spawnPosition = checkpointPosition + Vector3.__new( math.random() * 5 - 2.5, math.random() * 2 + 2, math.random() * 5 - 2.5 )
			local spawnOrientation = Quaternion.Euler( math.random() * 360, math.random() * 360, math.random() * 360 )

			-- Spawn the duplicate part.
			PopConstructions.DuplicatePart( rewardTemplatePart.ID, spawnPosition, spawnOrientation )
		end
	end

	-- Disable part spawning again.
	NoPartSpawnDestroy.Value = true

	-- Tidy up by removing our ConstructionSpawned event handler.
	ConstructionSpawned.Handler.remove( onRewardConstructionSpawned )
end

The spawnRewards( numParts ) function spawns in a bunch of reward parts at random locations, by duplicating them from the template part. We’ll call this function when the player achieves the goal.

Next, add the following to your Lua script:

local function onConstructionEnteredCheckpoint( construction )
	-- Check if the construction that entered the checkpoint is the barrel.
	-- If so, then the goal was achieved.
	if not isGoalAchieved and (construction.ID == barrelConstructionID) then
		Label.Text = "<color=yellow>Well done, have some gold coins!</color>"
		spawnRewards( 10 )
		isGoalAchieved = true
	end
end

local function initScene()
	-- Start by making all constructions in the scene non-targetable.
	for construction in Constructions.Instances do
		ConstructionOps.SetConstructionTargetable( construction.ID, false )
	end

	-- Then make the forklift targetable so the player can get in and drive it.
	ConstructionOps.SetConstructionTargetable( forkliftConstructionID, true )

	local checkpointConstruction = Constructions.GetInstance( checkpointConstructionID )
	local checkpointPart = checkpointConstruction.GetPart( 0 )

	-- Cache the checkpoint part's world position for later use.
	checkpointPosition = checkpointPart.Position

	-- Add a handler to the checkpoint behaviour's OnConstructionEntered event.
	-- This is raised whenever a construction enters the checkpoint.
	for behaviour in checkpointPart.Behaviours do
		if behaviour.Name == 'Checkpoint' then
			behaviour.OnConstructionEntered.add( onConstructionEnteredCheckpoint )
			break
		end
	end

	-- Cache the reward "gold coin" template part for later use.
	local rewardTemplateConstruction = Constructions.GetInstance( rewardTemplateConstructionID )
	rewardTemplatePart = rewardTemplateConstruction.GetPart( 0 )

	-- Move the template part 1km below ground, so that the player doesn't see it!
	ConstructionOps.FreezeConstructionAtGround( rewardTemplateConstruction.ID, Vector3.__new( 0, -1000, 0 ) )
end

The initScene() function ensures only the forklift is targetable by the player, caches some variables for later use, and sets up a checkpoint OnConstructionEntered event handler.

In the onConstructionEnteredCheckpoint( construction ) event handler, if the barrel has entered the checkpoint, then the goal is achieved and we spawn the rewards.

Finally, add this last block of code:

----- Game Event handlers -----

-- The GameReady event is raised by the game when the scene has finished
-- loading (i.e. the map and any saved constructions in it).
-- Here we add a handler to this event, in it we initialise everything for the scenario.
local function onGameReady()
	disableFeatures()
	initUI()
	initScene()
end
GameReady.Handler.add( onGameReady )

----- Entry functions -----

-- Cleanup() is called by the game when the script is unloaded.
function Cleanup()
	Windows.DestroyWindow( Win )

	-- Make sure to remove our GameReady event handler.
	GameReady.Handler.remove( onGameReady )
end

The onGameReady() event handler will call our initialisation functions when the game is ready to play. The code in Cleanup() ensures we tidy up properly when the player exits the scenario.

Save your script and you’re ready to try out the scenario!

Playing Your Scenario

Now enter the BEGIN SCENARIO screen, and under the “Locally saved” tab, you should find your scenario:

Try playing it…

And see if you have the forklift skills…

To get the reward…

OK, that wasn’t exactly a hard challenge to play, but hopefully it gives you an idea of the possibilities!

More information

This guide only scratches the surface of what’s possible with scenarios.

To learn more, the built-in scenarios are a good reference, you’ll find them here: C:\Program Files (x86)\Steam\steamapps\common\GearBlocks\GearBlocks_Data\StreamingAssets\Scenes.

If you want to try modifying them, copy them into your local SavedScenes folder first!

Finally, here is the full documentation for the GearBlocks Lua scripting API. This will evolve over time as I expose more features and functionality in the API, so bookmark it for future reference!