6. World-based features#
For: configurators. Needs: Tutorial 3. You will: run the Hoverboard and Checkpoint features, see what a scenario needs to play in a level (a play-settings asset, a map, tick waits), and learn what to copy for your own world-based feature.
Counter and Inventory run in memory. Most gameplay does not: it needs a world, physics and time. Hoverboard and Checkpoint show how a scenario asks for those without a single line of code in the feature.
The features as text#
Source/ZagalaSpecExamples/Features/Hoverboard.zagalaspec:
@ZagalaSpec.Import.Features.Hoverboard
Feature: Hoverboard
As a player exploring the world, I want to ride a hoverboard that floats
steadily above the ground, accelerates forward and backward on command, and
turns left and right when I steer, so that I have a fun, fast way to move
around and feel in control of my mobility.
Shared Context Extensions:
Given the tick limit is set to 500 ticks
And a test world is ready
And the hoverboard is spawned at the origin
@ZagalaSpec.Import.Features.Hoverboard.HoversAboveTheGround
Scenario: Hovers above the ground
Then the hoverboard hovers between 140 and 160 units above the ground
@ZagalaSpec.Import.Features.Hoverboard.AcceleratesForward
Scenario: Accelerates forward
When I wait 60 ticks for it to hover
And I apply forward throttle
Then the hoverboard has moved forward by more than 100 units
@ZagalaSpec.Import.Features.Hoverboard.SteersLeft
Scenario: Steers left
When I wait 60 ticks for it to hover
And I steer left
Then the hoverboard has rotated to the left by more than 15 degrees
(Two more scenarios, Decelerates and reverses and Steers right, mirror these.) Checkpoint.zagalaspec has the same shape: a tick limit, a test world, a spawned checkpoint, then scenarios that spawn a sphere, launch it, wait for it to arrive and count activations.
Run both: search Features.ZagalaSpec.Import.Features.Hoverboard and …Checkpoint. While they run you will see a Play In Editor session window briefly, and then the session ends. Eight green rows.
The three setup sentences#
Every scenario in these features starts with the same shared context extensions. Each one is a reusable building block for your own features.
Given the tick limit is set to 500 ticksA safety net. Any wait in the scenario fails with tick limit 500 exceeded without satisfying condition instead of hanging. Pick a number that comfortably exceeds your longest wait.
And a test world is readyStarts a Play In Editor session (or loads a level in a packaged build) and puts the running world into the cache for later steps. Select the step: its capture group
test worldhas Group Value Class set toBP_Hoverboard_Data_PlaySettings. That is a tiny Blueprint data class whose default points at theDA_Hoverboard_PlaySettingsasset, which holds the actual configuration:Field
Hoverboard value
Meaning
Map To Load
L_Hoverboard_TestLevelThe level to play. Must have a floor (the hoverboard traces down to it) and uses
BP_Hoverboard_GameMode.Startup Timeout Seconds
30
Fail if the session has not started by then.
Shutdown Timeout Seconds
10
Fail if it has not stopped by then.
Use Fixed Time Step / Fixed Time Step FPS
true / 60
Makes “60 ticks” mean the same thing on every machine. Keep it on for physics scenarios.
Listen Server / Number Of Clients
false / 1
Off for single-player features. When on, the session is a listen server plus that many clients; see 12. Multiplayer in the editor.
If a Play In Editor session is already running when the step executes (usually the previous scenario’s session, still closing), the step ends it and starts a fresh one, so every scenario begins from a clean level. When the scenario finishes, the step’s teardown ends the session it started.
And the hoverboard is spawned at the originSpawns the system under test into the world from the cache and stores a reference to it. Your equivalent is “spawn my actor” or “find my actor in the level”.
Waiting and asserting#
Physics needs frames. When I wait 60 ticks for it to hover advances 60 ticks of the test world and then continues; with a fixed 60 FPS time step that is one second of simulation. Some assertions wait on their own: Then the hoverboard has moved forward by more than 100 units keeps checking each tick until the condition holds or the tick limit is reached, which is why it can follow And I apply forward throttle directly.
In Checkpoint, When I wait 60 ticks for the trigger sphere to reach the checkpoint is a conditional wait: it succeeds as soon as the checkpoint registers one more activation, and fails on the tick limit otherwise. And I reset the trigger sphere position puts the sphere back and re-applies its last launch so a second activation can be counted.
Two sentences in Checkpoint capture words rather than numbers: a trigger sphere is spawned (near) the checkpoint and launched towards the checkpoint at a given (speed). Select them: their capture groups set Group Value Class to BP_Checkpoint_Data_RelativeTriggerSpawnCoordinates and BP_Checkpoint_Data_SphereLaunchMagnitude, two Blueprint data classes whose Class Defaults hold the offset vector and the impulse magnitude. Designers tune those numbers without touching the feature text. Duplicate the Blueprint, change the defaults, point a copy of the scenario at it, and you have a new case.
Running headless#
World-based features do not need a window. On a build machine:
UnrealEditor-Cmd.exe MyGame.uproject -ExecCmds="Automation RunTests Features.ZagalaSpec.Import.Features.Hoverboard; Quit" -unattended -nullrhi -nop4 -log -ReportExportPath=C:\Reports
Play In Editor starts in the background, physics simulates, the report is written. Only features that test rendering itself would need a real RHI.
What to copy for your own feature#
A play-settings asset: duplicate
DA_Hoverboard_PlaySettings, set Map To Load to your level. Duplicate theBP_Hoverboard_Data_PlaySettingsBlueprint and point its default at your settings asset.The three shared sentences: tick limit,
a test world is readywith your…_Data_PlaySettingsas Group Value Class, and a spawn-or-find step for your actor (a programmer writes that one; it is a few lines, see 10. Hoverboard in C++).Waits: reuse
I wait N ticks …wording through your own step entry that maps to the shared wait step, or write conditional waits like Checkpoint’s.Tunables as data classes: anything a designer should be able to change goes in a small Blueprint tagged-data class selected through Group Value Class, or in an asset referenced through Group Value Object.
What you learned#
A world-based scenario is an ordinary scenario whose shared setup starts a play session; the configuration lives in a play-settings asset.
Tick limits turn hangs into failures; fixed time step makes tick counts deterministic.
Group Value Class can point at a Blueprint data class with tuned defaults, so designers change numbers without editing text or code.
Headless runs work for world-based features.
Next: 7. Create a new step in Blueprint to add a sentence of your own. Programmers: 10. Hoverboard in C++ and 11. Checkpoint in C++ read the C++ behind these two features. Multiplayer: 12. Multiplayer in the editor runs a listen server with several clients.