7. Abilities and statuses

In short: An ability is anything a unit can do in battle: a sword strike, a spell, a heal, a thrown bomb. A status is a lasting effect on a unit: poison, haste, a shield, charm. Both are data assets. One ability works in every battle mode, with its own rules per mode. You build new content by filling fields and picking effects, not by writing code.

7.1 Basics

7.1.1 The words

7.1.2 Make your first ability

1. Open RPG Saga Engine → Studio → Content → New ability, or right-click a folder in the Content Browser and choose RPG Saga → Ability. The wizard walks through the same fields as the asset, and its last step shows the ability in action.
2. Give it a Description, an Ability Type tag (Ability.Type.Attack, Skill, Magic or Action: this decides which command of the battle menu lists it), an optional Element, and a Target Filter (enemies, allies, allies and self, self, all units).
3. Under Costs add what it consumes (for example Resource.MP, 8). Under Item Costs you can add ammunition (1 Arrow).
4. Under Effects press + and pick Damage. Choose the Kind (Physical, Magical or Fixed), the Power, and whether it can miss or crit. Add Apply Status next to it if you want, with a Chance.
5. Fill the rules for the modes you use. A grid battle reads Tactics Rules (range, area, Action Point cost), a classic battle reads ATB Rules (scope, row behavior, charge time). The turn-based mode uses the ATB rules too.
6. Give the ability to someone: add it to a class's ability list, to a piece of equipment's Granted Abilities, to a Pact, or teach it with a story effect (see Learning and forgetting abilities).
7. Press Test ability (below) to measure it without playing.

The plugin ships a full set of examples in /RPGSagaEngine/Data/Abilities/: DA_Ability_Strike, DA_Ability_Fire (area, elemental, costs MP), DA_Ability_Cure, DA_Ability_Raise (a revive), DA_Ability_ShieldBash (a use condition), DA_Ability_PoisonDart (a status), DA_Ability_TK_Overwatch (a reaction) and many more. Open them to see how a finished ability looks.

7.1.3 Test an ability without playing

Every ability sheet has a Test & preview tab and a Test ability button. The Studio wizard shows the same tools.

1. Pick the battle mode (Grid, Live, ATB or Turn), the caster (any character or an archetype) and the targets (a preset: one enemy, three enemies, an ally and two enemies, a boss, three allies).
2. Set the level, the seed and the number of runs. For abilities usable only at low HP, set the caster's HP %.
3. Press Test ability. Each run uses a fresh headless mini battle, so hundreds of runs take about a second. The report lists, per unit, how often it was affected, hits, misses, crits, damage and healing per use (lowest, highest, average), the real chance each status landed, what one use costs, the area it covers and a Step by step trace of the first use.
4. Copy as text puts the report on the clipboard.

The same seed always gives the same numbers, so you can change one value and compare. Above the table a 3D preview plays the ability's presentation (animation, effects, projectile, floating numbers) in a small private world, with Loop, speed and camera choices. Defaults for both are in Project Settings → RPG Saga Engine → Ability Test and Studio → Ability Preview.

7.2 How it works

An ability's life, in every battle mode:

1. A unit has a list of abilities, gathered from its class, equipment, Pact and the abilities it learned.
2. When the player (or the AI) picks one, the battle checks the use conditions, the costs (resources, item costs, Action Points in grid battles) and the mode's own rules (range, scope, ready state). A refusal carries a reason that the menu shows.
3. The battle resolves each effect in the Effects array. Effects that work per target run once per affected unit. Effects that move the user or change the field (leap, dash, teleport, zones, summons) run once per use before the per-target ones.
4. Every change becomes a battle event (damage dealt, status applied, unit moved, reaction triggered...). The presentation layer listens to those events to play animations and numbers. The rules never wait for the presentation.
5. After the action, queued reactions resolve (a counterattack, a guard), up to a depth limit that stops endless chains.

All randomness comes from one seeded stream per battle. The same seed and the same commands always give the same battle, in the editor, in the simulator and over the network.

7.2.1 Per-mode rules

Each mode block has a Power Multiplier so you can balance one mode without touching the others.

Area shapes for Tactics are Single, Diamond, Cross, Line, Cone, Ring, Rectangle and Mask (a hand-drawn pattern). Power can fall off with distance from the center, and an Arc trajectory flies over lower obstacles.

7.2.2 Effects you can pick

Pick effects in the Effects list; the display names below are what you see in the picker.

Position effects have a documented meaning in the classic modes too. A knockback becomes a row change, a swap exchanges rows, a spawned wall does nothing. The picker's tooltip and the validation tell you when an effect has no meaning in a mode.

7.2.3 Statuses

A status (URSEStatusData) is data too. The main fields:

• Status Tag: its identity (Status.Poison). Tags let abilities, conditions and the AI refer to it.
• Duration Turns: counted in the bearer's own turns. 0 means until removed.
• Stacking: Refresh restarts the duration, Ignore keeps the first application.
• Immunity Tag: a unit with this tag (from equipment, a class trait, a Pact) cannot receive the status.
• Persists After Battle and Removed By Damage.
• While Active: stat Modifiers, element Affinities and Granted Tags. Tags such as Status.Block.Move, Status.Block.Act and Status.Block.Turn stop moving, acting or the whole turn.
• Periodic: Periodic Timing (turn start or turn end) and a percent of max HP. Positive damages (poison), negative heals (regeneration).
• Toolkit: Polarity (Neutral, Buff, Debuff), Dispellable, Shield Absorbs (None, All, Physical, Magical) and Taunt.
• AI Value Scale: how much the AI values applying the status. 0 ignores it, 2 doubles it.
• Behaviors (control): see below.

Stat modifiers always combine in the same order: base, add, percent, multiply, override, clamp, then the attribute's own bounds. The result never depends on which status or item came first.

7.2.4 Control statuses

A status can change who decides what its bearer does. Add a Behavior under Control → Behaviors:

They work in every battle mode and the AI follows them. A party member under control is played by the AI until the status ends (by duration, a cure, damage if Removed By Damage is on, the unit falling, or the battle's end). When the last fighter of a side is charmed away, that side has lost. The starter content includes Confuse, Charm and Frenzy statuses with example abilities (Bewilder, Enthrall, Incite).

7.2.5 Use conditions

Use Conditions is a list of checks on the user. All must hold in every mode. The menus show a failed ability disabled with a reason: the ability's Use Conditions Text when filled in, otherwise the failing condition's own text. The AI and the simulator never choose a disabled ability.

Conditions about "the target" cannot go here, because no target is chosen yet. Validation reports them.

7.2.6 Item costs and ammunition

Item Costs consume items from the team's items on every use. The menu shows "1 Arrow (x12)". Without enough items the ability is disabled. Enemies ignore item costs unless Enemies Pay Item Costs is on in Ability Toolkit.

7.2.7 Reactions and passives

An ability with Passive ticked never appears in menus. Two lists make it useful:

• Reactions: each URSEAbilityReaction has a Trigger (Damage Taken, Attacked, Ally Damaged, Enemy Moved, Defeated, Kill, Turn Start, Turn End), a Source (who may trigger it), a Response ability, an Aim, a Chance, Max Per Turn and more. Enemy Moved is overwatch, grid only.
• Passive Modifiers: stat modifiers, affinities and tags applied while their conditions hold.

Reactions are queued and resolved after the action that caused them, up to Max Reaction Depth (default 1, so a counter is not countered).

7.2.8 Tier families

A URSEAbilityTierFamily asset lists abilities from the base tier up. The battle menu shows the family as one entry, and choosing it opens the tiers the unit knows, each with its own cost and power. A new family is one data asset.

7.2.9 Learning and forgetting abilities

A character can learn an ability for good outside its class progression. Learned abilities appear after class, equipment and Pact abilities, in every battle mode, and are saved.

• Learn Ability and Forget Ability are story effects (dialog choices, quest rewards, puzzles, interactions). The learner can be one character, every member, or members whose tags match.
• A manual is a consumable whose use ability has the effect Learn Ability, is usable in the field and targets an ally. See DA_Item_ManualBerserkSlash in /RPGSagaEngine/Data/Items/.

7.2.10 Presentation and action commands

How an ability looks (animation, effects, camera, sounds) is separate from what it does. The Presentation block points to a timeline asset; empty means a default from the approach (melee, ranged, in place) and the moment (normal or super move). See Camera and battle presentation.

An ability can also ask for a timed button press (Action Command): a ring closes and a Good or Perfect press adds a bonus, and enemy attacks can be blocked with a timed press. The windows and bonuses are on the ability; the global rules are in Project Settings → RPG Saga Engine → Action Commands.

7.3 Key classes and assets

7.4 Settings

Project Settings → RPG Saga Engine:

The full lists are in Appendix B. The asset types are in Appendix D.

7.5 Blueprint usage

Teach an ability from a Blueprint:

1. Event (for example On Interact) → Learn Ability (Character = DA_Char_Hero, Ability = DA_Ability_Fire).
2. Branch on the returned result to show a message if the character already knew it.

Related nodes in the party library (category RPG Saga | Party | Abilities): Forget Ability, Has Learned Ability, Get Learned Abilities, Get Member Abilities. The party subsystem has an On Ability Learned event.

Run the headless test from a script:

1. Make Ability Test Request (Ability, Mode tag).
2. Adjust the request (caster, targets, runs, seed).
3. Run Ability Test → Ability Test Report To Text → Print String.

Write a custom effect:

1. Create a Blueprint class with parent Custom (Blueprint) (URSEEffect_Custom).
2. Override On Apply (Battle, Source Id, Target Id, Target Tile, Power Multiplier). Inside, call the battle's nodes: Deal Damage, Heal Unit, Change Resource, Apply Status, Remove Statuses, Shift Turn.
3. Draw random numbers only with Roll Int and Roll Percent. They come from the battle's stream, so replays and the simulator stay exact.
4. Override Preview Damage to give the AI and the damage forecast an expected value. Without it the AI sees no value in the effect.
5. Tick Once Per Use if the effect should run once instead of per target.
6. Add your class to an ability's Effects list.

A custom reaction condition is a Blueprint subclass of Reaction that overrides Can Trigger. A custom passive overrides Is Active For. A custom use condition is a subclass of AI Condition: override Is Met and Get Requirement Text.

The full node list is in Appendix A.

7.6 C++ usage

A new effect in C++ is a subclass of URSEAbilityEffect. Override Apply and, so the AI can see it, AddToPreview.

UCLASS(meta = (DisplayName = "Drain Morale"))
class UMyEffect_DrainMorale : public URSEAbilityEffect
{
    GENERATED_BODY()
public:
    UPROPERTY(EditAnywhere, Category = "Morale", meta = (ClampMin = "0"))
    float Amount = 10.f;

    virtual void Apply(const FRSEAbilityContext& Context, int32 TargetId) const override
    {
        Context.Battle->ChangeResource(Context.SourceId, TargetId, MoraleTag, -Amount);
    }

    virtual bool AppliesOncePerUse() const override { return false; }

private:
    FGameplayTag MoraleTag;
};

The picker lists every concrete subclass with its DisplayName, so no registration is needed. Useful overrides: AddToPreview (what the AI and the forecast read), CheckRequirement (extra conditions beyond costs), ApplyInField (what the effect does from the party menu), AppliesOncePerUse, DescribeEffect (tooltip text) and ValidateInAbility (editor validation).

Run the headless ability test from C++:

FRSEAbilityTestRequest Request = URSEAbilityTestLibrary::MakeAbilityTestRequest(Ability, ModeTag);
Request.Runs = 200;
const FRSEAbilityTestReport Report = URSEAbilityTestLibrary::RunAbilityTest(Request);
UE_LOG(LogTemp, Log, TEXT("%s"), *URSEAbilityTestLibrary::AbilityTestReportToText(Report));

7.7 Advanced

7.7.1 Gameplay Ability System bridge (RSEGAS)

Teams that already use Unreal's Gameplay Ability System can keep it. The RSEGAS module is a bridge: the battle stays the source of truth for hits, damage and turns, and the bridge mirrors values in and out. RSECore never uses GAS types, and nothing happens until an actor has the component.

Setup:

1. Create an RSE GAS Attribute Map data asset. Add one row per value the battle should read or write: the RSE tag (Stat.Attack, Resource.HP), the GAS attribute, a Direction (In, Out or Both) and a Scale. With the included RSE GAS Sample Attribute Set, press Fill Sample Rows.
2. Optionally create an RSE GAS Status Map (statuses to loose tags and effects) and an RSE GAS Ability Map (an event tag or ability tags sent when an RSE ability is used).
3. On your character Blueprint, add the RSE GAS Bridge component. Set Character (the RSE character data asset) and the maps. If the Ability System Component lives elsewhere, call Set Ability System.

What flows:

• In: stats and resources at battle start, outside attribute changes while the battle runs, GAS tags to statuses.
• Out: resource changes as instant Gameplay Effects, statuses as tags and optional effects, battle events as Gameplay Events (tags such as Event.RSE.Damaged and Event.RSE.AbilityUsed), and with Restore After Battle the attributes return to their old values.

The component's options (Supply Stats, Apply Results To GAS, Mirror Statuses, Forward Events, Forward External Changes, Restore After Battle, Priority) are all on by default except Restore After Battle.

RSE abilities can also run your GAS content. In an ability's Effects list add Apply Gameplay Effect (GAS) or Activate Gameplay Ability (GAS). In a presentation timeline add the Gameplay Cue (GAS) step. These do nothing on units without a bridge or on a machine that is not the authority.

Export to GAS (editor, one way) generates Gameplay Effects and Gameplay Abilities from your statuses and abilities (RPG Saga Engine → Advanced tools → Content → Export to GAS..., or the RSEGASExport commandlet). Always start with a dry run. The report lists what GAS cannot hold (grid rules, reactions, control behaviors...). Defaults live in Project Settings → RPG Saga Engine → GAS Export.

7.7.2 Content from spreadsheets and AI

Abilities, statuses and their use conditions can be created and updated from spreadsheets (Configurator → Tools → Content Import), and they appear in the AI prompt packs. The effect type in a sheet is the display name without spaces, for example KnockbackPull(Distance=2). See Editor tools.

7.7.3 Network and performance notes

• The battle runs on the host; effects, statuses and reactions are deterministic, so guests see the same results (Co-op and online).
• Effects run on the authority only. GAS effects follow the same rule.
• Keep AddToPreview cheap. The AI calls it for every ability and target it considers.

7.8 Troubleshooting

7.9 See also

• Battle fundamentals, Grid Tactics and ATB and turn-based for the rules each mode adds.
• Items, inventory and economy for consumables whose use is an ability.
• Enemy AI and adaptive difficulty for how the AI values abilities and statuses.
• Product pages: docs/product/abilities.md, docs/product/gas-interop.md.