8. Create a new step in C++#
For: C++ programmers. Needs: Tutorial 3; a C++ project with the ZagalaSpec plugin enabled. You will: add the sentence Then the counter value is at least N to the Counter feature with one tagged data class, one step and one step entry, then use it from a scenario.
Module setup#
In your game module’s Build.cs add the plugin modules you use:
PrivateDependencyModuleNames.AddRange(new[]
{
"GameplayTags",
"ZagalaSpec", // core: steps, chain links, tagged data, registry
"ZagalaSpecNativeTags", // the plugin's native tags (only if you reuse them)
"ZagalaSpecToolkit", // only if you reuse UZagalaSpecChainLinkOnStep, the shared data types or the world helpers
"ZagalaSpecExamples", // only if you reuse example SUTs
});
This tutorial reads the Counter example’s data, so it needs ZagalaSpecExamples, which brings ZagalaSpecToolkit with it. Your own features normally need only ZagalaSpec and GameplayTags; add ZagalaSpecToolkit when you derive from its base classes.
1. The tagged data#
A tagged data class is a UZagalaSpecTaggedData with a tag. Implement IZagalaSpecValueStore when the value should be parsed from captured text.
// MinimumValueData.h
#pragma once
#include "Core/Data/ZagalaSpecTaggedData.h"
#include "Core/Interface/Data/ZagalaSpecValueStore.h"
#include "NativeGameplayTags.h"
#include "MinimumValueData.generated.h"
UE_DECLARE_GAMEPLAY_TAG_EXTERN(TAG_MyGame_Data_MinimumValue);
UCLASS(Blueprintable, BlueprintType)
class UMinimumValueData : public UZagalaSpecTaggedData, public IZagalaSpecValueStore
{
GENERATED_BODY()
public:
UPROPERTY(EditDefaultsOnly, BlueprintReadWrite, Category = "Data")
int32 Value = 0;
virtual void StoreValue_Implementation(const FString& ValueToStore) override
{
Value = FCString::Atoi(*ValueToStore);
}
protected:
virtual FGameplayTag GetLoadTag() const override { return TAG_MyGame_Data_MinimumValue; }
};
// MinimumValueData.cpp
#include "MinimumValueData.h"
UE_DEFINE_GAMEPLAY_TAG(TAG_MyGame_Data_MinimumValue, "MyGame.Data.MinimumValue");
GetLoadTag() is the key under which the object is stored in the cache. One object per tag: a second SetData with the same tag replaces the first.
2. The step#
Derive from UZagalaSpecDefaultExecutionStep, override InternalExecute_Implementation, finish every path with exactly one broadcast.
// Step_CounterIsAtLeast.h
#pragma once
#include "Core/Step/ZagalaSpecDefaultExecutionStep.h"
#include "Step_CounterIsAtLeast.generated.h"
UCLASS()
class UStep_CounterIsAtLeast : public UZagalaSpecDefaultExecutionStep
{
GENERATED_BODY()
protected:
virtual void InternalExecute_Implementation(const TScriptInterface<IZagalaSpecTaggedDataCacher>& AssignedCacher) override;
};
// Step_CounterIsAtLeast.cpp
#include "Step_CounterIsAtLeast.h"
#include "MinimumValueData.h"
#include "Core/Data/ZagalaSpecTaggedDataHandler.h"
#include "Counter/Data/ZagalaSpecDataCounterRef.h"
#include "Counter/SUT/ZagalaSpecExamplesCounter.h"
void UStep_CounterIsAtLeast::InternalExecute_Implementation(const TScriptInterface<IZagalaSpecTaggedDataCacher>& AssignedCacher)
{
AddLocalSetupDataToCache(AssignedCacher); // converts the captured N into UMinimumValueData
const UZagalaSpecDataCounterRef* Ref = UZagalaSpecTaggedDataHandler::GetDataT<UZagalaSpecDataCounterRef>(AssignedCacher);
if (!Ref || !Ref->Counter)
{
BroadcastFailure(TEXT("Step_CounterIsAtLeast: no counter in the cache. Is 'Given a fresh counter' missing?"));
return;
}
const UMinimumValueData* Minimum = UZagalaSpecTaggedDataHandler::GetDataT<UMinimumValueData>(AssignedCacher);
if (!Minimum)
{
BroadcastFailure(TEXT("Step_CounterIsAtLeast: minimum value missing. Set the capture group's Group Value Class to MinimumValueData."));
return;
}
const int32 Actual = Ref->Counter->GetValue();
if (Actual >= Minimum->Value)
{
BroadcastSuccess();
return;
}
BroadcastFailure(FString::Printf(TEXT("counter value %d is below the minimum %d"), Actual, Minimum->Value));
}
Failure reasons are what stakeholders read in the Session Frontend; write them in product terms and include the numbers.
Skipping the Group Value Class
If you would rather not ask configurators to set a Group Value Class, read the raw text in Setup_Implementation and skip the tagged data class:
void UStep_CounterIsAtLeast::Setup_Implementation(FZagalaSpecExecutionStepData StepData)
{
Super::Setup_Implementation(StepData);
if (StepData.CaptureGroupCustomizer && StepData.CaptureGroupCustomizer->GetCaptureGroup(0))
{
CachedMinimum = FCString::Atoi(*StepData.CaptureGroupCustomizer->GetCaptureGroup(0)->GetCaptureGroupValue());
}
}
UZagalaSpecCEFocusItem in the Inventory example does this. The trade-off: the value is no longer in the cache for other links (DSL, drivers) to read.
3. The step entry#
A step entry is a UZagalaSpecRegexStepEntry whose constructor sets Pattern and StepClass. Native entries register their CDO automatically when the module loads.
// StepEntry_CounterIsAtLeast.h
#pragma once
#include "Step/ZagalaSpecRegexStepEntry.h"
#include "StepEntry_CounterIsAtLeast.generated.h"
/** Maps "Then the counter value is at least N" to UStep_CounterIsAtLeast. */
UCLASS()
class UStepEntry_CounterIsAtLeast : public UZagalaSpecRegexStepEntry
{
GENERATED_BODY()
public:
UStepEntry_CounterIsAtLeast(const FObjectInitializer& ObjectInitializer = FObjectInitializer::Get());
};
// StepEntry_CounterIsAtLeast.cpp
#include "StepEntry_CounterIsAtLeast.h"
#include "Step_CounterIsAtLeast.h"
UStepEntry_CounterIsAtLeast::UStepEntry_CounterIsAtLeast(const FObjectInitializer& ObjectInitializer)
: Super(ObjectInitializer)
{
Pattern = TEXT("^(?:Then |And )the counter value is at least (-?\\d+)$");
StepClass = UStep_CounterIsAtLeast::StaticClass();
}
Pattern rules that keep configurators happy:
Anchor with
^and$.Put keywords in a non-capturing group
(?:Then |And )so only values are captured.Keep patterns unique. The first entry registered for a pattern wins; a duplicate logs a
LogZagalaSpecwarning and is ignored.If a template form is wanted (
at least <minimum>for examples rows), add a second entry with pattern…at least <(?:.+)>$mapping to the same step, as the Counter example does.
4. Use it#
Compile, start the editor, open the DA_Counter feature, and in Increment by N add And the counter value is at least 4. Matched Step Entry shows StepEntry_CounterIsAtLeast. In the capture group set Group Value Class to MinimumValueData. Press Check: green. Change 4 to 6: red, with your reason.
For Blueprint-only teammates, every class above is Blueprintable/BlueprintType where it matters, so they can subclass your data and steps.
5. Going layered#
When a second step needs the same game interaction, split:
// A DSL action (names the intent) ...
UCLASS() class UDSL_ReadCounterMinimumCheck : public UZagalaSpecChainLinkOnChainLink { /* creates and runs the driver */ };
// ... and a protocol driver (touches the SUT)
UCLASS() class UPD_CompareCounterToMinimum : public UZagalaSpecDefaultChainLink { /* reads cache, compares, broadcasts */ };
and make the step a UZagalaSpecChainLinkOnStep that assigns Action, subscribes and executes, exactly like UZagalaSpecStepIncrementBy in Tutorial 3. Both ChainLinkOn… bases live in ZagalaSpecExamples; copy them into your module if you prefer not to depend on it. To run several links in order, create a UZagalaSpecDefaultExecutionChainer and AddLinkT<...>() each link, as UZagalaSpecStepCounterIs does.
6. Test it like the plugin does#
The plugin’s own tests exercise steps directly: create the step with NewObject, give it a cache (a UZagalaSpecContext or any IZagalaSpecTaggedDataCacher), subscribe an IZagalaSpecSubscriber, call Execute, and assert which broadcast arrived. For the scenario-level check, running the feature from the command line (see Usage) is enough.
Next: 9. Inventory in C++, 10. Hoverboard in C++ and 11. Checkpoint in C++ read the full example implementations, including iteration, play sessions and latent waits. The API reference documents every class used here.