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.

[lextatic]

Okay, from that design I take that the sword and the character should really be separate entities. At least that's how I'd design it.

So, the way I understand the skill you're trying to do now is: your character throws the sword, while the sword is flying it throws fireballs around or leave trails of fire or something.

It might sound weird, but yea I think the sword is the one who has the ability to throw fireballs. The character only has the ability to throw the sword!

Or, another way of seeing this is that the player throws the sword in a way that he imbues the sword with the "Heat Rush" ability. There's a method for granting and activating an ability you could maybe use there: EntityAbilities.GrantAbilityAndActivateOnce(). The player throw ability could call this method on the sword entity granting it the "Heat Rush" ability.

Will try all of this out tomorrow then. Again, thank you for your help and patience.

Good luck and don't worry about bothering me, this is the most fun I've had since I started this project 2 years ago. Up until now I didn't have many people to talk about and test/challenge my designs.

Btw, the periodic + custom execution bug is confirmed and I'm already working on a fix and some unity tests for it. Thanks for helping me find that one.

[Minimata]

Alright I think I got it!

I moved most of the logic inside my WeaponSystem class to handle the events. There, in the Ready method, I permanently grant the ability to fly to the weapon (using a CreateFlyingAbility method). This ability, when triggered by the WeaponStartedFlyingEventTag, applies a new effect to the weapon with the custom execution and the periodic data attached to it. The custom execution just raises the "Flying Tick" event.

WeaponSystem.cs

    public void CreateFlyingAbility()
    {
        var flyingWeaponEffectData = new EffectData(
            "Flying Weapon Effect Data",
            new DurationData(DurationType.Infinite),
            customExecutions:
            [
                new FlyingWeaponExecution(this)
            ],
            periodicData: new PeriodicData(new ScalableFloat(0.2f), false, PeriodInhibitionRemovedPolicy.ResetPeriod) 
        );
        
        var weaponHandToFlyingAbilityData = new AbilityData(
            name: "WeaponHandToFlyingSword",
            abilityTags: WeaponFlyingAbilityTag.GetSingleTagContainer(),
            instancingPolicy: AbilityInstancingPolicy.PerEntity,
            abilityTriggerData: AbilityTriggerData.ForEvent<WeaponEventPayload>(WeaponStartedFlyingEventTag),
            behaviorFactory: () => new ClosureBehavior<WeaponEventPayload>((ctx, payload) =>
            {
                // Store the effect handle for later use
                _flyingWeaponEffectHandle = EffectsManager.ApplyEffect(new Effect(flyingWeaponEffectData, new EffectOwnership(this, this)));
            }));
        Abilities.GrantAbilityPermanently(weaponHandToFlyingAbilityData, 1, LevelComparison.None, this);
    }

The ClosureBehavior is the same as tje behavior in your tests, it simply calls the callback given as a parameter and ends itself. It's the callback that applies the effect.

FlyingWeaponExecution.cs

public class FlyingWeaponExecution(WeaponSystem weaponSystem) : CustomExecution
{
    public override ModifierEvaluatedData[] EvaluateExecution(Effect effect, IForgeEntity target, EffectEvaluatedData? effectEvaluatedData)
    {
        weaponSystem.Events.Raise(new EventData<WeaponEventPayload>
        {
            EventTags = weaponSystem.WeaponFlyingTickEventTag.GetSingleTagContainer()!,
            Source = weaponSystem,
            EventMagnitude = 12f,
            Payload = new WeaponEventPayload(Message: "flying")
        });
        return [];
    }
}

Now, through my state management system (the excellent State Charts plugin btw, highly recommend) I can raise events according to the state changes of my weapon through the WeaponStartedFlyingEventTag and WeaponStoppedFlyingEventTag. While the ability has a convenient way to activate itself through the abilityTriggerData and apply the effect, I still have to remove that effect manually:

WeaponSystem.cs

Events.Subscribe<WeaponEventPayload>(WeaponStoppedFlyingEventTag, 
    data =>  if (_flyingWeaponEffectHandle is { IsValid: true }) EffectsManager.RemoveEffect(_flyingWeaponEffectHandle));

And now, I know that there's a bug preventing the custom execution to fire periodically so I can't be 100% sure, but I think that this works as intended. At least everything triggers when it should, except for the custom execution which at least does trigger when the effect is applied, which gives me some confidence that it works.

But this is only to grant the flying ability and react to changes in state, I still want to spawn fireballs and such while the weapon is flying. As you said, this should be a weapon ability, but I still want the abilities to be handled by the player, so that I can manage the player's inventory at a single location and let the code dispatch abilities as needed.

So I created a new method to grant the ability to the weapon through a Godot Resource given here as an argument. The ability is triggered by the WeaponFlyingTickEventTag which should be raised periodically when the bug will be fixed.

WeaponSystem.cs

    public void GrantNewAbilityForWeaponFly(RExplodingSword ability)
    {
        var weaponFlyingAbilityData = new AbilityData(
            name: "WeaponFlyingSwordAbility",
            abilityTags: WeaponFlyingAbilityTag.GetSingleTagContainer(),
            instancingPolicy: AbilityInstancingPolicy.PerEntity,
            abilityTriggerData: AbilityTriggerData.ForEvent<WeaponEventPayload>(WeaponFlyingTickEventTag),
            behaviorFactory: () => ability.Behavior(this));
        
        var weaponFlyGrantAbilityConfig = new GrantAbilityConfig(
            weaponFlyingAbilityData,
            ScalableLevel: new ScalableInt(1),
            RemovalPolicy: AbilityDeactivationPolicy.CancelImmediately,
            InhibitionPolicy: AbilityDeactivationPolicy.CancelImmediately,
            TryActivateOnGrant: false,
            TryActivateOnEnable: false,
            LevelOverridePolicy: LevelComparison.Higher);
			
        var weaponFlyGrantComponent = new GrantAbilityEffectComponent([weaponFlyGrantAbilityConfig]);
        var weaponFlyGrantEffect = new EffectData(
            "Grant Weapon Fly Ability",
            new DurationData(DurationType.Infinite),
            effectComponents: [weaponFlyGrantComponent]);
        EffectsManager.ApplyEffect(new Effect(weaponFlyGrantEffect, new EffectOwnership(this, this)));
    }

The behaviour comes from the RExplodingSword parameter which is a class that inherits Godot's Resource to receive parameters from the editor, such as the Explosion scene to instantiate:

public partial class RExplodingSword(PackedScene? explosion) : Resource
{
    [Export] public PackedScene? Explosion { get; set; } = explosion;
    
    public RExplodingSword() : this(null) {}
    
    public IAbilityBehavior<WeaponEventPayload> Behavior(Node3D owner)
    {
        return new ExplodingSwordThrowBehavior<WeaponEventPayload>(owner, Explosion);
    }
}

public class ExplodingSwordThrowBehavior<TPayload>(Node3D owner, PackedScene? explosion) : IAbilityBehavior<TPayload>
{
    private Node3D _owner = owner;
    private PackedScene? _explosion = explosion;
    public void OnStarted(AbilityBehaviorContext context, TPayload payload)
    {
        if (_explosion?.Instantiate() is not Explosion explosion)
        {
            context.InstanceHandle.End();
            return;
        }
        if (!_owner.IsInsideTree())
        {
            context.InstanceHandle.End();
            return;
        }
        explosion.Radius = 6f;
        
        _owner.GetTree().GetRoot().CallDeferred(Node.MethodName.AddChild, explosion);
        explosion.CallDeferred(Node3D.MethodName.SetGlobalPosition, _owner.GlobalPosition);
        
        context.AbilityHandle.CommitAbility();
        context.InstanceHandle.End();
    }

    public void OnEnded(AbilityBehaviorContext context)
    {
    }
}

On my player controller, I can reuse the same resource with the same explosion behaviour to spawn the fireball onto the weapon but by reacting to different events.

PlayerController.cs

		// Forward the resource to grant the ability to the weapon
		WeaponSystem.GrantNewAbilityForWeaponFly(weaponAbility);  
		
		var weaponExplosionTag= Tag.RequestTag(tagsManager,"abilities.player.weapon.explode").GetSingleTagContainer();
		var weaponExplosionAbilityData = new AbilityData(
			name: "WeaponExplosionAbility",
			abilityTags: weaponExplosionTag,
			instancingPolicy: AbilityInstancingPolicy.PerEntity,
			behaviorFactory: () => weaponAbility.Behavior(WeaponSystem));

		var weaponExplosionAbilityConfig = new GrantAbilityConfig(
			weaponExplosionAbilityData,
			ScalableLevel: new ScalableInt(1),
			RemovalPolicy: AbilityDeactivationPolicy.CancelImmediately,
			InhibitionPolicy: AbilityDeactivationPolicy.CancelImmediately,
			TryActivateOnGrant: false,
			TryActivateOnEnable: false,
			LevelOverridePolicy: LevelComparison.Higher);
		
		var weaponExplosionGrantComponent = new GrantAbilityEffectComponent([weaponExplosionAbilityConfig]);
		var weaponExplosionGrantEffect = new EffectData(
			"Grant Weapon Left Ability",
			new DurationData(DurationType.Infinite),
			effectComponents: [weaponExplosionGrantComponent]);
		EffectsManager.ApplyEffect(new Effect(weaponExplosionGrantEffect, new EffectOwnership(this, this)));
		
		Events.Subscribe(OtherPlayerEventTag, (data) => Abilities.TryActivateAbilitiesByTag(weaponExplosionTag, data.Target, out var flags));

And that's it! I can reuse the same Exploding Sword behaviour to create abilities on my player and on my weapon, wrap this behaviour in a Godot Resource, manage it from the player controller directly and trigger that ability either from Player events or through the (soon-to-be-working-hopefully) periodic effect of the flying sword which is in itself and ability of the sword. I believe that's everything I wanted this to do!

There's still a lot to do, for example I want to work on better abstractions for interfacing Godot's resources with Forge's entities and systems. For now it's still a bit too hardcoded here and there, e.g. the method to grant the ability to the weapon takes a RExplodingSword as a parameter but I would want to reuse the same method to grant other kinds of abilities that can also be triggered within flight, but it's a different issue.

I'd love to get your advice on this implementation though. Does it makes sense within your design philosophy for Forge? Or am I twisting its arm?

In any case, appreciate the help and work on this framework. The more I use and understand it the more I think it will cover most of the use cases I'll meet through my project better that I could have ever done by myself.

[lextatic]

I still have to remove that effect manually.

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.

You still have to "manually" do something, but it's not remove the effect, is to end the ability. The effect is removed as a consequence.

There's still a lot to do, for example I want to work on better abstractions for interfacing Godot's resources with Forge's entities and systems. For now it's still a bit too hardcoded here and there, e.g. the method to grant the ability to the weapon takes a RExplodingSword as a parameter but I would want to reuse the same method to grant other kinds of abilities that can also be triggered within flight, but it's a different issue.

Just to make sure, have you seen that I provide several types of Resources for defining Abilities and Effects data through the editor already? For custom stuff like IAbilityBehavior you have to write a Resource wrapper, but I think that's best the way of doing it. You can use that as inspiration if that helps.

I'd love to get your advice on this implementation though. Does it makes sense within your design philosophy for Forge? Or am I twisting its arm?

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.

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

To de-escalate things a bit after this warning, I've been a full time game dev since 2010 and am currently working on an indie MMO project since 2017. There I realized how managing attributes and effects can be quite a challenge and decided to find a more robust formalized approach of doing it. Then I learned about GAS at the same time I started learning Godot and decided... why can't we have this nice stuff here too? Bang! Here we are! 😁

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