Ability System

The Ability System is a framework for creating extensible and reusable gameplay abilities in Verse. With this system, you can create gameplay abilities that grant the player magic spells, superpowers, or other special capabilities.

The Ability API is a framework for creating reusable gameplay abilities in Verse. It separates ability activation, runtime data, gameplay logic, and lifetime management into distinct layers, making abilities easy to extend and reuse.

Core Concepts

Every ability consists of four parts:

• An Ability Context that stores per-activation data.

• An Ability that defines the ability and its requirements, validates activation, and creates the effect.

• An Ability Effect that represents the spawned gameplay entity.

• An Ability Effect Component that controls the effect's behavior and lifetime.

Separating ability activation, runtime data, gameplay logic, and lifetime management into distinct layers makes abilities easy to extend and reuse. As a result, you can create many variations of the same ability without duplication.

Below is a table to compare and contrast the components of custom abilities.

Ability Context

An ability_context is a temporary container for contextual data that stores the data related to a single activation.   

The base context provides:

• Instigator - The agent responsible for activating the ability.

• Participants - The entities related to the ability that aren't direct targets, such as weapons, inventory items other players.

• Targets - The entities that receive the ability's effects.

Contexts can be subclassed to carry additional gameplay data.

heal_context := class(ability_context):
    HealPerTick : float = 5.0

Ability

An ability is a persistent definition that governs when it can be used and creates the gameplay effect in the given context.

Abilities store references to the context and effect types they expect to work with. This provides type safety throughout the activation process, meaning mismatched types are caught during development, rather than during gameplay.

heal_ability := class(ability(heal_context, heal_effect)):

An ability is responsible for:

• Validating activation against a set of restrictions, such as cooldown or resource cost

• Creating the context

• Creating the effect

• Tracking active effects

• Broadcasting begin and end lifecycle events

Validating Activation

Override CanUse() to determine whether an ability can activate.

Typical checks include:

• Cooldowns

• Mana or resource costs

• Target validation

• Existing active effects

• Game-specific requirements

CanUse<override>(AbilityEffectParent:entity,AbilityContext:heal_context)<reads><decides>:void =

    (ActiveEffects.Length = 0)

Creating Contexts and Effects

An ability creates the objects it uses by overriding two factory functions.

MakeContext() constructs the context passed to the effect.

MakeContext<override>()<transacts>:heal_context =

    heal_context{

        HealPerTick := 5.0

    }

MakeAbility() constructs the effect entity that will execute the gameplay logic.

MakeAbility<override>()<transacts>:heal_effect =

    heal_effect{}

Activating an Ability

To activate an ability:

• Construct a context.

• Populate any required data.

• Call Use().

HealContext := heal_context{

    Instigator := option{PlayerAgent}

    Participants := array{}

    Targets := array{PlayerEntity}

    HealPerTick := 10.0

Ending an Ability

Call EndUse() when an ability completes normally.

EndUse(false)

Override OnEndUse() to perform cleanup.

OnEndUse<override>(Reason : ?cancel_reason)<transacts> : void =

     # Cleanup: unbind events, remove visual effects, etc.

     return

Cancelling an Ability

Abilities can also end through cancellation.

Create custom cancellation reasons by subclassing cancel_reason.

sprint_cancel := class(cancel_reason):

External systems can request cancellation through Cancel().

Override CanCancel() to determine whether the ability can be cancelled.

CanCancel<override>(Reason : cancel_reason)<transacts><decides> : void =

     true?

The heal example cancels itself whenever the player begins sprinting.

Ability Events

Abilities expose events that allow external systems to observe their lifecycle.

• BeginUseEvent

• EndUseEvent

Abilities also maintains an ActiveEffects list that contains every currently running effect instance. This can be used to implement behavior, such as limiting the number of simultaneous effects.

Ability Effect and Effect Component

The ability_effect is the transient spawned gameplay entity. The effect is typically defined as a prefab with suitable visual, audio, and other supporting components attached.

The ability_effect_component is attached to the ability_effect entity and controls the effect's runtime behavior and lifecycle. The effect component also has access to the related ability and context.

The component has access to:

• The activation context

• The originating ability

• The effect's lifecycle

heal_effect_component := class(ability_effect_component):

Effect Lifetime

Override OnBeginUse() to perform initialization before gameplay begins.

OnBeginUse<override>()<transacts>:void =
    if (HealContext := heal_context[Context?]):
        set HealPerTick = HealContext.HealPerTick

  Long-running behavior typically executes inside OnSimulate().

OnSimulate<override>()<suspends>:void =
    loop:
        Sleep(TickInterval)
        # Gameplay logic.

The heal example periodically heals each target until the duration expires.

Complete Example - Heal Ability

The following example implements a channeled heal-over-time ability.

It demonstrates:

• A custom context

• A custom effect component

• A custom ability

• Ability activation

• Runtime gameplay logic

• Cancellation

• Cleanup

# Verse Ability Workflow - Working Example
# A channeled heal-over-time ability that cancels if the player sprints.

using { /Verse.org/Input }
using { /UnrealEngine.com/Abilities }
using { /Fortnite.com/Characters }
using { /Fortnite.com/Game }
using { /Fortnite.com/Input }
using { /Fortnite.com/Playspaces }
using { /Fortnite.com/Input/Character }

Learn More

See the following pages to learn more about the ability system.

• Create Your First Ability  — Learn how to create a simple periodic healing ability.

• Fortnite Template Abilities  — Create simple, responsive, timeline-driven Fortnite abilities.

  • Fortnite Template Ability Quickstart — Build your first Fortnite template ability.

• Verse Abilities API  —- Learn technical details about the Abilities module.

• Ability and Effect Lifecycle  — See reference for the lifetime of abilities and effects.