Unsure how to grant a periodic ability through an effect

[Minimata]

Hello there!

I've recently started using Forge for my Godot project and I fail to figure out how to implement a specific kind of ability, one where an ability is triggered periodically through an effect. If you've played Hades 2, think of the "Heat Rush" ability. Basically, once you get this ability then as long as you're running you periodically spawn on the ground some damaging surface. I've implemented one-off abilities as well as periodic effects successfully but I can't figure out how to activate a granted ability periodically through an effect.

Here's the ability definition to define the cost, cooldown and behaviour (e.g. Hades' "Heat Rush"). I've implemented it through a Godot Resource.

public class HeatRushAbility 
{
  public AbilityData HeatRush(TagsManager tagsManager, TagContainer? tags)
  {
      return new AbilityData(
          name: "Heat Rush",
          costEffect: CostEffect(tagsManager),  // Created through another method of the same class
          cooldownEffects: [CooldownEffect(tagsManager)],  // Created through another method of the same class
          abilityTags: tags,
          instancingPolicy: AbilityInstancingPolicy.PerEntity,
          behaviorFactory: () => new HeatRushBehavior());
  }
  // ...
}

public class HeatRushBehavior : IAbilityBehavior
{
    public void OnStarted(AbilityBehaviorContext context)
    {
        // This is where I instantiate the burning surface through Godot-specific code, removed for simplicity

        context.AbilityHandle.CommitAbility();
        context.InstanceHandle.End();
    }

    public void OnEnded(AbilityBehaviorContext context) { }
}

Here's the code granting the ability, right on my Player entity:

var dashingTag = Tag.RequestTag(tagsManager,"abilities.dashing").GetSingleTagContainer();
var heatRushGrantAbilityConfig = new GrantAbilityConfig(
	heatRushAbility.HeatRush(tagsManager, dashingTag),
	ScalableLevel: new ScalableInt(1),
	RemovalPolicy: AbilityDeactivationPolicy.CancelImmediately,
	InhibitionPolicy: AbilityDeactivationPolicy.CancelImmediately,
	TryActivateOnGrant: false,
	TryActivateOnEnable: true,
	LevelOverridePolicy: LevelComparison.Higher);

heatRushGrantComponent = new GrantAbilityEffectComponent([heatRushGrantAbilityConfig ]);
var heatRushGrantEffect = new EffectData(
	"Grant Heat Rush Ability",
	new DurationData(DurationType.Infinite),
	effectComponents: [heatRushGrantComponent ],
	periodicData: new PeriodicData(  // This is the part where I would expect the ability to be triggered periodically
		Period: new ScalableFloat(0.2f),
		ExecuteOnApplication: true,
		PeriodInhibitionRemovedPolicy: PeriodInhibitionRemovedPolicy.ResetPeriod)
	);

EffectsManager.ApplyEffect(new Effect(heatRushGrantEffect , new EffectOwnership(this, this)));

And here's the code where I activate the ability (e.g. starting to run)

var dashingTag = Tag.RequestTag(tagsManager,"abilities.dashing").GetSingleTagContainer();
if (dashingTag != null)
	var canActivate = Abilities.TryActivateAbilitiesByTag(dashingTag , target, out var flyingFailures);

And here's the code where I cancel the ability (e.g. when running stops)

var dashingTag = Tag.RequestTag(tagsManager,"abilities.dashing").GetSingleTagContainer();
if (dashingTag != null)
	Abilities.CancelAbilitiesWithTag(dashingTag);

With this code, the ability is only activated only once when the player starts running, but not periodically. I would expect it to be triggered 5 times per second as long as the player is running, as per the PeriodicData indicates.

I'm pretty sure it's just me not being able to understand the ways abilities and effects are supposed to work together but I've read through the documentation many times and tried many things, to no avail.

Can this be done and if so, where's my mistake? Thank you!

[lextatic]

Hey! First of all, thanks a lot for trying out Forge and for taking the time to write this question. It’s really great to see someone actually building something with it.

From what I understood, you're trying to implement something similar to a “fire trail while running”, where something is spawned periodically while an ability is active.

Your current approach uses a periodic Grant Effect to repeatedly grant the ability, expecting that this would drive the behavior over time. Conceptually, this makes sense at first glance, but it’s not how Grant Effects are intended to be used in Forge.

About Grant Effects

A Grant Effect is responsible for giving an ability to an entity. Conceptually, it represents that the entity has "learned" or "unlocked" that ability.

It is not strictly limited to happening only once, but its purpose is still about granting the ability itself, not driving its execution over time.

When a Grant Effect is configured as Execute (either Instant or Periodic), it will execute its logic and grant the ability permanently. In practice, this means the ability becomes permanently available and cannot be removed.

Because of that, making a Grant Effect periodic does not make the ability execute periodically. It just attempts to grant it again, which usually has no effect if the ability is already present.

So your intuition is valid, but this is not the correct layer in the system to implement time-based behavior.

Recommended Approaches

Option 1 (Simplest): Handle it inside the Ability

The most straightforward solution is to grant the ability once (non-periodic), activate/deactivate it as you're already doing, and then handle the periodic spawning inside its behavior using a timer node.

Example:

public class HeatRushBehavior : IAbilityBehavior
{
    private AbilityBehaviorContext _context;
    private Timer _timer;

    public void OnStarted(AbilityBehaviorContext context)
    {
        _context = context;

        // Call on start if you want to immediately create one trail
        SpawnFireTrail();

        _timer = new Timer
        {
            WaitTime = 0.2f,
            Autostart = true,
        };

        _timer.Timeout += SpawnFireTrail;

        // This is a simple way to attach the timer to the scene tree
        var tree = Engine.GetMainLoop() as SceneTree;
        tree?.Root.AddChild(_timer);
    }

    public void OnEnded(AbilityBehaviorContext context)
    {
        if (_timer != null)
        {
            _timer.Timeout -= SpawnFireTrail;
            _timer.Stop();
            _timer.QueueFree();
            _timer = null;
        }
    }

    private void SpawnFireTrail()
    {
        // Your spawn logic here

        // Call CommitAbility here if you want to consume resources every time you spawn a trail
        _context.AbilityHandle.CommitAbility();
    }
}

This approach is simple, explicit, and gives you full control over timing and behavior.

Note that you don't have to call End() for this ability since you're calling CancelAbilitiesWithTag() from somewhere else.

On a separate branch I have an IAbilityBehavior that includes an OnUpdate(double deltaTime) method, which could simplify this implementation and remove the need for the Timer node, but it's not merged or released yet.

Option 2: Drive the behavior separately through events

Another approach, which makes better use of the data-oriented design, is to grant the ability once and keep it passive while something else drives its execution.

For example:

• Grant the ability using a Grant Effect
• Configure the ability to be triggered by an event
• Create a custom execution that triggers the event on the target entity
• Apply a periodic effect with this custom execution while the entity is dashing

In this case, the AbilityBehavior remains simple: it just spawns the trail and ends itself. Each periodic tick re-activates the ability.

A nice advantage of this approach is that you can reuse the same ability in other situations by triggering the same event.

If anything is unclear or you want help implementing one of these approaches, feel free to ask. Happy to help.

[Minimata]

Have you considered that your ability could be the one applying the Periodic effect to the sword? You could apply the effect on the ability OnStarted and remove it OnEnded, but you'd still have to manually End the ability externally at some point instead of ending it immediately OnStarted. Just keep the ability's handle and then call End on it once the sword stops. Since your periodic effect is already Infinite it should last as long as the ability is active, being removed along with the ability deactivation.

I have not considered that, I'll look into it.

Just to make sure, have you seen that I provide several types of Resources for defining Abilities and Effects data through the editor already?

I've seen the code by opening up the forge-godot repo in Rider but I haven't actually gone too deep into these interfaces nor opened the project in Godot so it's not fully mapped in my mind yet. But I was for sure going to have a look at it before attempting my own implementations.

I think you're doing pretty good. Aside from the ability applying the effect, which is purely a design choice, I think I have no critiques to what you're doing.

Good, then I'm starting to get it!

Just a reminder that while I'm actively working on this project nonstop, it's not production ready stuff yet. Expect some API parameters/methods to change while version v1.0 is still not released. Also, I'm yet to use it on an actual game (even though that's the endgoal), validate usage, performance and a bunch of other stuff. I'm no expert in creating actual gameplay with this system either! All those concepts were pretty much inspired on Unreal's GAS with some improvements/adaptations here and there. I also have never built a game on Unreal using GAS, haha. 🙃

That's fine, I get it. But also, it's closer to production-ready than anything I could have tried to do by now. You already have dealt with many walls I would've have to face by myself otherwise. To me, if that means I'll have to adapt to some API changes from time to time, that's good enough. And if I can help to battle test it and contribute in a meaningful way (when I'll understand all of it a bit better) then great!

[Minimata]

Okay I changed the Weapon Flying ability from having the ClosureBehavior that applied the effect in the callback to a new one that applies the same effect OnStarted and removes it OnEnded. Then when the weapon lands, instead of removing the effect directly, I just Cancel the flying ability using its handle and let the OnEnded method deal with the effect. Functionnally changes nothing though it keeps the effect application and removal completely inside the behavior which is a bit neater so thanks for the tip.

Just to make sure, have you seen that I provide several types of Resources for defining Abilities and Effects data through the editor already?

Glad I checked it out, everything is there already, hot damn! Going through the documentation I mainly focuses on the engine-agnostic stuff and didn't quite grasp the extent of your godot-specific plugin. That's amazing! I'm in the process of refactoring my hardcoded, workaroundy code to make better use of these nodes and resources. I'll take some time also to adapt my previous systems to the forge ones so that it's unified across the project. Will let you know if I run into other roadblocks or bugs.

Cheers and thank you for your work and help on this! Do let me know when you get around to fixing the Custom Execution issue as well.

[lextatic]

Cheers and thank you for your work and help on this! Do let me know when you get around to fixing the Custom Execution issue as well.

Let's just say, soon enough 😉

[lextatic]

@Minimata Can you try it out to see if it's working as expected? And if so, could you mark this thread as answer?

[Minimata]

Answered you here because I missclicked in the UI.

[Minimata]

I cloned the repo and copy-pasted-and-replaced the addons folder right in my project's addons/forge folder. Unfortunately the issue is still there, the custom execution triggers once when applied but isn't re-executed according to its periodic data.

I recreated my previous setup using the resources you made available within the plugin, here's the current setup.

This here is an ability that applies an empty effect to the weapon when the weapon is thrown. As seen at the very bottom, the trigger is an Event with the tag events.weapon.startedflying. The effect has a CustomExecution attached to it and a PeriodicData.

I keep a reference to the handle of this ability to cancel it when the weapon stopped flying.

The Periodic Data is set to trigger 5 times per second. The effect itself is empty (no modifier, no components) but it has a CustomExecution that finds the owner of the effect and calls a specific event from it. We can see in yellow above, the raise_flying_tick_event.tres is a ForgeCustomExecution wrapper which takes the event's TagsContainer to raise as a parameter. Below is the code for the execution:

public class RaiseEventTagExecution(TagContainer eventTags) : CustomExecution
{
    public override ModifierEvaluatedData[] EvaluateExecution(Effect effect, IForgeEntity target, EffectEvaluatedData? effectEvaluatedData)
    {
        var owner = effect.Ownership.Owner;
        if (owner == null) return [];
        
        owner.Events.Raise(new EventData
        {
            EventTags = eventTags,
            Source = owner,
            EventMagnitude = 12f
        });
        
        return [];
    }
}


[GlobalClass]
public partial class ForgeRaiseEventTagExecution : ForgeCustomExecution
{
    [Export] ForgeTagContainer EventTags { get; set; } = new();
    
    public override CustomExecution GetExecutionClass()
    {
        return new RaiseEventTagExecution(EventTags.GetTagContainer());
    }
}

So this execution basically raises the events.weapon.flyingtick event, which is supposed to be everytime it's applied (when the weapon starts flying) or executed (5 times per second). Finally, I have another ability on my weapon which is listening to the events.weapon.flyingtick event and spawns an explosion when it's raised:

Again, the issue is still the same. The explosion spawning is only triggered once, when the weapon starts flying. I can say for sure that the CustomExecution is only triggered once as well, when applied, but not again 5 times per second when it should be executed by the periodic data.

Maybe I missed something, somewhere that I can't really communicate correctly? I hope it's going to be clearer when using Godot resources instead of pure code, but it's supposed to be the same setup as before.

[lextatic]

Can you confirm that the plugin version you're using right now is v0.3.0? I've tested it here with your code, adding this custom execution on a periodic effect I already have and it's working as intended.

The plugin is now updated on the asset store if you want to try to update it using the store.

You can also add a GD.Print right at the beginning on the execution too to check if it's getting called, here I got it printing every tick. But if you confirm the behavior of only triggering on application it seems more likely you're not on the latest version yet.

One little problem I had is that the tags for the events were getting reset to empty/none, I solved it removing the new() from:

[Export] ForgeTagContainer EventTags { get; set; } = new();

I think this is causing the container to be recreated at some point, I have yet to figure out why.

[Minimata]

Sorry for the delay, couldn't work on it for a while.

Yes, I do have version 0.3.0 installed

I also had this issue with the tags being reset. I solved it by actually saving the ForgeTagContainer as a standalone resource instead of an in-editor resource that only exists in the inspector. To be safe though, I removed every instance of [Export] ... = new();.

I do have GD.Print in the custom execution to check if the event tags I set using the [Export] value works, and it does.

public class RaiseEventTagExecution(TagContainer eventTags) : CustomExecution
{
    public override ModifierEvaluatedData[] EvaluateExecution(Effect effect, IForgeEntity target, EffectEvaluatedData? effectEvaluatedData)
    {
        var owner = effect.Ownership.Owner;  // The owner here is the WeaponSystem
        if (owner == null) return [];
        foreach (var tag in eventTags.Tags)
        {
            GD.Print(tag);  // This prints "events.weapon.flyingtick" to the console when the weapon is thrown
        }
        
        owner.Events.Raise(new EventData
        {
            EventTags = eventTags,
            Source = owner,
            EventMagnitude = 12f
        });
        return [];
    }
}

[Tool]
[GlobalClass]
public partial class ForgeRaiseEventTagExecution : ForgeCustomExecution
{
    [Export] ForgeTagContainer EventTags { get; set; }
    
    public override CustomExecution GetExecutionClass()
    {
        return new RaiseEventTagExecution(EventTags.GetTagContainer());
    }
}

I also print something when the explosion behavior being triggered by events.weapon.flyingtick is actually called, and it prints EXPLOSION only once when the weapon is thrown:

public class ExplodingSwordBehavior(PackedScene explosion) : IAbilityBehavior
{
    public void OnStarted(AbilityBehaviorContext context)
    {
        if (context.Owner is not Node3D owner)
        {
            context.InstanceHandle.End();
            return;
        }
        
        if (explosion.Instantiate() is not Explosion explo)
        {
            GD.Print("Cannot instantiate");
            context.InstanceHandle.End();
            return;
        }
        if (!owner.IsInsideTree())
        {
            GD.Print("Not inside tree");
            context.InstanceHandle.End();
            return;
        }

        GD.Print("EXPLOSION");

        explo.Radius = 6f;
        
        owner.GetTree().GetRoot().CallDeferred(Node.MethodName.AddChild, explo);
        explo.CallDeferred(Node3D.MethodName.SetGlobalPosition, owner.GlobalPosition);
        
        context.AbilityHandle.CommitAbility();
        context.InstanceHandle.End();
    }

    public void OnEnded(AbilityBehaviorContext context)
    {
    }
}

[Tool]
[GlobalClass]
public partial class ForgeExplodingSwordBehavior : ForgeAbilityBehavior
{
    [Export] public PackedScene Explosion { get; set; }
    public override IAbilityBehavior GetBehavior()
    {
        return new ExplodingSwordBehavior(Explosion);
    }
}

As another debugging attempt, I manually subscribed my WeaponSystem to the events.weapon.flyingtick event:

Events.Subscribe(Tag.RequestTag(tagsManager, "events.weapon.flyingtick"), data =>
{
    GD.Print("Weapon tick triggered!");  // Prints once when the weapon is thrown, not periodically.
});

This further cements that the issue is coming from the custom execution not being called periodically.

In fact, if I set the Execute on application of the Periodic Data to false, it doesn't trigger at all. So the Periodic Data does partially work in this case.

Funnily enough, I have another periodic effect in the project, one that regenerates mana on my player. I tried to attach the same CustomExecution on it to see if the event would be raised periodically and it does! So the CustomExecution code seem to work fine and is indeed triggered periodically by the PeriodicData. I tried to make the weapon flying tick effect data look like the mana regeneration effect data to see if there maybe was a configuration issue (e.g. tried adding modifier data and components to see if it made a difference) but to no avail. The only difference I can see between my mana regeneration effect and flying tick effect is that the first one is applied as a permanent ability while the other one is applied conditionally through another ability.

I'll fiddle around with all of that in the editor and try to wrap my head around it. Honestly, pretty fun to build systems using your Godot resources. It'll be even funnier when I'll get it to work but it's already quite cool and the more I use it the more I understand the power behind these objects.

[lextatic]

In this v0.3.0 you should be able to able to use break points and step into the library's code for debugging, maybe that helps in trying to identify what differs from one effect to another.

It could also easily be yet another bug related to how the effect is applied. Have you tried swapping the effects to see if they swap tick behaviors? Maybe it's related to how you're setting up the effect or ability lifetime, have you tried using a simple modifier instead of the custom execution to see if it's being applied every tick?

Let me know if you find more information about this issue, maybe with more information about how you setup the ability and effects I could replicate it myself to investigate. The CustomExecution and AbilityBehaviors seem okay.

Edit: setting Execute on application to false and not having it tick when the effect applied confirms that you have the most recent fix, this behavior wasn't working before.

[Minimata]

My brother in christ I am as dumb as a table... I was re-reading the effects documentation when I found out that...

🤡🤡🤡 I FORGOT TO CALL EffectsManager.UpdateEffects 🤡🤡🤡

When changing the explosion ability to be part of the weapon instead of the player, I forgot the single most important line for the Effects Manager. While I have entities that make use of your ForgeEntity class that manages this kind of stuff by itself, I decided against it for my player controller and my weapon system because it would shake my current design too much without much benefit... EXCEPT it would have been a benefit if I knew I was going to forget that line!

I am proven once again that 99.9% of the time, the issue in programming is between the chair and the keyboard.

I any case this fixes the issue (duh!) and my weapon triggers nice explosions periodically as it's flying in the air, as expected.

I'll mark this most recent discussion as an answer to the initial question. Working on this issue and having your guidance helped me understand the Forge system way deeper than I would have by myself in the same amount of time, so it's not all bad. I can now move forward with implementing actual features for my game instead of debugging against my stupidity.

Thank you for your help and patience with me. I'll keep you posted if/when the game moves to production using Forge, but I'll probably come back earlier than that with more questions.

Cheers!

[lextatic]

Glad you got it working!

Anxious to see what you're building with it 😉