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.

مقدمة

As opposed to open ended “creative mode” يلعب, 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).

ملحوظة: The example scenario shown in this guide is available on the Workshop, بحث عن “AnExampleScenario”.

The Scene

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

في ال CREATIVE panel, انقر على “New empty scene” زر, 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. لكن, often a scenario needs to start with some constructions already spawned.

فمثلا, 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, وصف, and add “scenario” as a tag, then click the Save button:

ملحوظة: 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, تحت “built-in examples” التبويب.

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, نقطة تفتيش, و “gold coin reward” constructions in your scene.

ملحوظة: Be sure to note the construction IDs, not part IDs!

The Scenario Script

انتقل إلى %USERPROFILE%\AppData\LocalLow\SmashHammer Games\GearBlocks\SavedScenes, and find the folder of your saved scene (على سبيل المثال 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 ملف, 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

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

التالي, 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( حقيقي )
	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

ثم, add the following block of code:

local function onRewardConstructionSpawned( construction )
	-- Unfreeze the spawned part.
	ConstructionOps.SetConstructionFrozen( construction.ID, خاطئة )
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

ال 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.

التالي, add the following to your Lua script:

local function onConstructionEnteredCheckpoint( construction )
	-- Check if the construction that entered the checkpoint is the barrel.
	-- لو ذلك, then the goal was achieved.
	if not isGoalAchieved and (construction.ID == barrelConstructionID) then
		Label.Text = "<color=yellow>أحسنت, have some gold coins!</لون>"
		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, خاطئة )
	end

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

	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

ال 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.

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

أخيراً, add this last block of code:

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

-- The GameReady event is raised by the game when the scene has finished
-- loading (أي. 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( يفوز )

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

ال 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” التبويب, you should find your scenario:

Try playing it…

And see if you have the forklift skills…

To get the reward…

نعم, 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: ج:\ملفات البرنامج (إلى x86)\Steam\steamapps\common\GearBlocks\GearBlocks_Data\StreamingAssets\Scenes.

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

أخيراً, 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!