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 LogZagalaSpec warning 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.