What is Ability Instancing Policy?
Today we are going to talk about GAS Ability Instancing Policy.
Seems that this property can be confusing, but it’s important to understand it well to know what you can and can not do with a Gameplay Ability.
If you open an ability in its Blueprint, the instancing policy can be found under the advanced section.
In C++ it’s a property that can be assigned at construction.
The 3 Policy Types
When creating an Ability there are three policy types, let’s discuss them.
Non Instanced
This is the default instancing policy. When the abilities are non instanced this means that we will use their CDOs ( Class Default Object ) when executing them.
What this means is that all abilities of this type will use the same UObject to run, which has some side effects that we need to take into account.
The most important one is that we can not store any state in the ability, as all abilities of that type share this object.
We can also not have any latent actions waiting for things. The ability should activate, do its things and then end on that same execution flow.
( This is not exactly like this, you can do certain things knowing how this works, but it would be a sort of best practice )
Instanced Per Actor
This is the instancing policy that I would recommend for a lot of abilities.
When an ability is instanced per actor, an instance of it is created when it’s granted and the actor lives with it.
You can store state in this type of abilities, not only during execution but also between executions, so it becomes an extremely flexible instancing policy.
Instanced Per Execution
Like the name implies, in this instancing policy, the ability is not instanced when granted, but instead, every time it’s executed.
We can store data in this instancing policy but only during the ability execution, once the ability ends it will be gone.
The advantage of this policy is that we can have multiple abilities of the same type running in parallel, as each of them is a separate instance that has been created, with Instanced Per Actor we need to cancel the ability to retrigger it.
Which Instancing Policy should I use then?
Each instancing policy has its pros and cons.
From a performance point of view Non Instanced seems the best one, as we are not creating extra objects, but it’s also the most limiting.
My recommendation is to start with Instanced Per Actor, as that would give you the most flexibility of all of them and later you can switch to another one.
Of course if you don’t need to store state between executions and prefer not to do cleanup of previous state when the ability activates, then Instanced Per Execution is your best bet.
If you want more info, here is the actual description by Epic Games of what each of them means:
One important thing with Instanced Abilities
If you are using Instanced Per Actor Abilities and try to re-activate an ability that is already active ( ex: You are jumping and want to jump again in the air with the same ability ) you will need to set the Retrigger Instanced Ability property flag to true.
This is under the same Advanced section near Instancing Policy and if true will allow you to cancel the already active ability and trigger it again. If you don’t set it to true, you will need to wait until the ability finishes by itself or cancel it manually before triggering it again.
Recap
- Non Instanced runs on the CDO shared by every activation of that ability, so you can not store state and you can not wait on latent tasks. It is the cheapest option and the most limited.
- Instanced Per Actor creates one instance when the ability is granted and keeps it for the life of the actor, so state survives between activations. This is the one I reach for by default.
- Instanced Per Execution spins up a fresh instance on every activation, which lets several copies of the same ability run in parallel but throws the state away when each one ends.
- The gotcha with Instanced Per Actor: re-activating an ability that is already running does nothing unless you set Retrigger Instanced Ability to true. Without that flag you have to wait for it to finish on its own or cancel it first.
What this doesn’t cover
This is about picking a policy, not the cost that comes with each one. Instanced abilities create real objects, so they carry more memory and replication overhead than Non Instanced. If you are shipping a networked game, that trade-off is worth measuring before you commit to one policy everywhere.
