11. Checkpoint in C++#
For: C++ programmers (advanced). Needs: Tutorial 10. You will: read a two-actor feature: references to several actors in one cache, numbers tuned in Blueprint data classes rather than sentences, a conditional wait built on UZagalaSpecPDWaitForTicks, and a reset step that makes a physics interaction repeatable.
This page describes the design; the source ships in the installed plugin under Source/ZagalaSpecExamples/Public/Checkpoint/ and the matching Private/ folder.
Class map#
flowchart LR
subgraph Shared context extensions
T["UZagalaSpecCESetTickLimit"] ~~~ W["UZagalaSpecCEEnsureTestWorld"] ~~~ SC["UZagalaSpecCESpawnCheckpoint"]
end
SC --> PSC["UZagalaSpecPDSpawnCheckpoint"]
S1["UZagalaSpecStepSpawnTriggerSphereNearCheckpoint"] --> D1["UZagalaSpecDSLSpawnTriggerSphereNearCheckpoint"] --> P1["UZagalaSpecPDSpawnTriggerSphereNearCheckpoint"]
S2["UZagalaSpecStepLaunchTriggerSphereTowardsCheckpoint"] --> D2["UZagalaSpecDSLLaunchTriggerSphereTowardsCheckpoint<br/>(chainer)"] --> P2a["UZagalaSpecPDTriggerSphereToCheckpointCoordinates"] --> P2b["UZagalaSpecPDLaunchTriggerSphere"]
S3["UZagalaSpecStepWaitForActivation"] --> D3["UZagalaSpecDSLWaitForActivation"] --> P3["UZagalaSpecPDWaitForActivation<br/>: UZagalaSpecPDWaitForTicks"]
S4["UZagalaSpecStepResetTriggerSphere"] --> D4["UZagalaSpecDSLResetTriggerSphere"] --> P4["UZagalaSpecPDResetTriggerSphere"]
S5["UZagalaSpecStepAssertActivationCount"] --> D5["UZagalaSpecDSLAssertActivationCount"] --> P5["UZagalaSpecPDAssertCheckpointState"]
PSC --> CP["AZagalaSpecExamplesCheckpointActor"]
P1 --> TS["AZagalaSpecExamplesTriggerSphereActor"]
P2b --> TS
P4 --> TS
P3 --> CP
P5 --> CP
Sentence |
Pattern |
Step |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Tagged data (all under ZagalaSpec.DSL.Data.Examples.Checkpoint.*): UZagalaSpecDataCheckpointRef and UZagalaSpecDataTriggerSphereRef (weak actor pointers), UZagalaSpecDataTriggerSphereSpawnCoordinates and UZagalaSpecDataTriggerSphereLaunchCoordinates (both UZagalaSpecDataVector), UZagalaSpecDataTriggerSphereLaunchMagnitude (a float). Expected counts use the shared UZagalaSpecDataInteger.
The systems under test#
AZagalaSpecExamplesCheckpointActor is a UBoxComponent with the Trigger profile; BeginPlay binds OnComponentBeginOverlap and every overlap does ++ActivationCount. AZagalaSpecExamplesTriggerSphereActor is a physics USphereComponent; Launch(Impulse) stores CachedImpulse, Tick keeps driving the body toward that velocity, BeginPlay records SpawnLocation, and ResetToOrigin() teleports back and zeroes velocity. Neither knows about tests.
Several actors, one cache#
The checkpoint is spawned once per scenario by the shared extension (UZagalaSpecCESpawnCheckpoint → UZagalaSpecPDSpawnCheckpoint) and stored as UZagalaSpecDataCheckpointRef. The sphere is spawned by an expectation step relative to it. UZagalaSpecPDSpawnTriggerSphereNearCheckpoint reads three things and fails with a distinct message for each if absent: the world (through FZagalaSpecWorldHelper::GetWorldFromCache), the checkpoint ref, and a UZagalaSpecDataTriggerSphereSpawnCoordinates. It then spawns an AZagalaSpecExamplesTriggerSphereActor at checkpoint location + offset with AlwaysSpawn collision handling and stores a UZagalaSpecDataTriggerSphereRef.
Each actor has its own ref class and therefore its own tag, so both coexist in the cache. Refs hold TWeakObjectPtrs, which is why every driver checks IsValid() first: PIE can end, actors can be destroyed, and a stale pointer should produce a readable failure rather than a crash.
Numbers that live in Blueprint data classes#
a trigger sphere is spawned (near) the checkpoint captures the word near, not a vector. In the feature asset, that capture group’s Group Value Class is BP_Checkpoint_Data_RelativeTriggerSpawnCoordinates, a Blueprint subclass of UZagalaSpecDataTriggerSphereSpawnCoordinates whose Class Defaults hold the offset. When the step calls AddLocalSetupDataToCache, the default converter finds no IZagalaSpecValueStore on that class and simply instantiates it, defaults included, under its tag. The driver above reads SpawnData->Vector and never sees the word.
at a given (speed) works the same way with BP_Checkpoint_Data_SphereLaunchMagnitude (a UZagalaSpecDataTriggerSphereLaunchMagnitude subclass holding Magnitude).
This is the third way a capture group can carry data, next to parsed text (IZagalaSpecValueStore) and Global rows: a class with defaults. It suits values a designer tunes but a stakeholder should not have to type.
Composing drivers in a DSL action#
Launching needs a direction and a magnitude. UZagalaSpecDSLLaunchTriggerSphereTowardsCheckpoint builds a UZagalaSpecDefaultExecutionChainer with two drivers so each stays single-purpose:
UZagalaSpecPDTriggerSphereToCheckpointCoordinatesreads both refs, computes the normalised vector from sphere to checkpoint and writes it asUZagalaSpecDataTriggerSphereLaunchCoordinates.UZagalaSpecPDLaunchTriggerSpherereads that vector and theUZagalaSpecDataTriggerSphereLaunchMagnitudeand callsLaunch(Direction * Magnitude)on the sphere.
If the sphere ref is missing, the first driver fails and the chainer stops before the second runs.
A conditional wait#
UZagalaSpecPDWaitForActivation extends UZagalaSpecPDWaitForTicks (Tutorial 10) and overrides two methods:
virtual void InternalExecute_Implementation(const TScriptInterface<IZagalaSpecTaggedDataCacher>& AssignedCacher) override;
virtual EZagalaSpecTickCheckResult OnTickCheck(IZagalaSpecTaggedDataCacher* Cacher, int32 TicksSoFar, FString& OutFailureReason) override;
InternalExecute reads the checkpoint ref (failing if absent), records its current ActivationCount as a baseline, then calls Super to start counting ticks of the test world. OnTickCheck re-reads the ref each tick: if it has become invalid it returns Fail with a reason; if ActivationCount has grown past the baseline it returns Succeed; otherwise Continue.
Two details make it robust. It records a baseline rather than waiting for “count == 1”, so the same step works for the first and the second activation. And it leaves the deadline to the base class: I wait 60 ticks … sets WaitTicks to 60, the shared tick limit caps it at 300, and the base tick loop succeeds at 60 ticks even without an activation. The following Then the checkpoint has been activated 1 time is what actually asserts the count (ProtocolDriver_AssertCheckpointState: Expected activation count %d, but found %d.). Waits move time forward; assertions judge.
Making it repeatable#
Checkpoint can be activated multiple times launches once, waits, then:
And I reset the trigger sphere position
And I wait 60 ticks for the trigger sphere to reach the checkpoint
Then the checkpoint has been activated 2 times
UZagalaSpecPDResetTriggerSphere calls TriggerSphere->ResetToOrigin(). The sphere teleports back to SpawnLocation with zero velocity, but CachedImpulse is still set, so its Tick drives it toward the checkpoint again and the overlap fires a second time. No second launch step is needed; the SUT was designed so that “reset” means “replay”. When you design your own SUT for testing, this kind of small affordance (a reset, a deterministic replay) is worth more than any test helper.
Checkpoint spawning happens in a shared extension, so each scenario gets a new checkpoint and a count of zero; the first scenario, Checkpoint is inactive before contact, asserts exactly that.
What to copy#
One ref tagged-data class per actor, holding a
TWeakObjectPtr, validated in every driver.Blueprint data classes as Group Value Class for designer-tuned vectors and magnitudes.
Chain small drivers inside a DSL action when an operation needs an intermediate value.
Baseline-relative waits that succeed on change, plus a separate assertion step for the exact value.
SUT affordances for reset/replay, so scenarios can repeat an interaction without extra steps.
You have now read every bundled single-player feature. The API reference covers the remaining classes; the FAQ collects the questions these tutorials usually raise.
Next: 12. Multiplayer in the editor starts a listen server with several clients and checks that every one of them joins.