GearBlocks – How to Make Custom Scenarios

Creating a scenario can make the game last longer by adding challenges, mini-games, or a completely new way to play. Here’s how you can begin making your own:

소개

Instead of playing in a creative way where you can do anything, a scenario is more structured. It has specific goals, a set of limited tools or parts, and sometimes other rules. The tutorial, kit build, and timed lap scenarios are all created in this structured way. They show what you can achieve using this system.

A scenario usually includes a saved scene and a Lua script. The Lua script is loaded when the scenario starts, setting up the game and making the scenario work.

참고하세요: The scenario example in this guide can be found on the Workshop by searching for “AnExampleScenario.”

The Scene

To start creating a scenario, the initial thing is to prepare a scene.

In the CREATIVE panel, 선택하다 “New empty scene” 옵션. Choose a map, set up the environment if you want, and then press the Play button.

If you wish your scenario to begin with an empty scene, you’re finished at this point; you can save it as it is. 하지만, many scenarios require some structures to be present from the beginning.

예를 들어, here we have a forklift truck, a green barrel on a palette, and a cylinder checkpoint:

추가적으로, there’s a circular plate part symbolizing a “gold coin.” This will serve as a template for rewards that we’ll create in the scenario script.

지금, try arranging a scene that resembles the one illustrated.

Once your scene is prepared, go to the SAVE SCENE screen. Provide it with a name, description, 그리고 추가 “대본” as a tag. 기후, click the Save button:

메모: You must tag the save with “대본”, so that it can be loaded from the BEGIN SCENARIO screen later.

Scene IDs

In a scenario, the Lua script needs to identify parts or constructions in the scene to manipulate them. Each part and construction has a unique scene ID for this purpose.

To discover the IDs of objects in the scene, 당신은 사용할 수 있습니다 “PartInspect” script mod provided. Load it from the SCRIPT MODS screen, found under the “built-in examples” 꼬리표.

When you target a part in the scene, it will display the ID of the construction it belongs to:

Remember to jot down the ID numbers of the forklift, barrel, checkpoint, 그리고 “gold coin reward” constructions in your scene.

중요한: Ensure that you are noting the construction IDs, not the part IDs!

The Scenario Script

Go to %USERPROFILE%\AppData\LocalLow\SmashHammer Games\GearBlocks\SavedScenes and locate the folder for your saved scene (예를 들어, AnExampleScenario). 이 폴더 내에서, create a new 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

중요한: Instead of each <id goes here>, replace it with the corresponding construction ID number you previously noted.

지금, include the following functions. These functions deactivate tools and other features, and set up the UI. We’ll invoke these during initialization:

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..."
끝

그 다음에, add the following block of code:

local function onRewardConstructionSpawned( 건설 )
	-- 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 )
끝

The function spawnRewards(numParts) generates several reward parts at random positions by duplicating them from the template part. We will use this function when the player accomplishes the goal.

지금, append the following to your Lua script:

local function onConstructionEnteredCheckpoint( 건설 )
	-- 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, 거짓 )
	끝

	-- 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 ) )
끝

그만큼 initScene() function guarantees that only the forklift is targetable by the player, caches some variables for later use, and establishes a checkpoint OnConstructionEntered event handler.

내에서 onConstructionEnteredCheckpoint(건설) event handler, if the barrel enters the checkpoint, it signifies the goal is accomplished, and we proceed to spawn the rewards.

To complete, insert this final 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 )
끝

그만큼 onGameReady() event handler will trigger our initialization functions when the game is prepared to play. The code in Cleanup() ensures that we clean up appropriately when the player exits the scenario.

Save your script, and you’re all set to give the scenario a try!

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, 여기에서 찾을 수 있어요: 씨:\프로그램 파일 (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!