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 ticks

A 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 ready

Starts 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 world has Group Value Class set to BP_Hoverboard_Data_PlaySettings. That is a tiny Blueprint data class whose default points at the DA_Hoverboard_PlaySettings asset, which holds the actual configuration:

Field

Hoverboard value

Meaning

Map To Load

L_Hoverboard_TestLevel

The 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 origin

Spawns 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#

  1. A play-settings asset: duplicate DA_Hoverboard_PlaySettings, set Map To Load to your level. Duplicate the BP_Hoverboard_Data_PlaySettings Blueprint and point its default at your settings asset.

  2. The three shared sentences: tick limit, a test world is ready with your …_Data_PlaySettings as 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++).

  3. 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.

  4. 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.