Skip to content

Author Your First Ability

last-verified: 2026-07-10 against f9ebdc9a3

This tutorial takes one ability from a blank page to playing it in-game. It uses an existing ability base — an ability shape the engine already supports (a melee attack, a projectile, an area blast, and so on; the wizard's Ability Base picker shows the current roster). If your idea needs a shape that doesn't exist yet, that is engineering work first; hand the one-pager to a programmer and point them at New Ability Archetype Recipe.

Designing a multi-link chain (a skill or proc that sets off a second and third effect, like a slam that opens a corrupting fissure)? That has its own, shorter flow — see How-To: Author an Ability Chain. A single ability, including a simple proc, is this tutorial.

You will: write a one-pager → create the asset with the guided wizard → hand-finish the Blueprint → put it in a kit → play it in PIE (Play-In-Editor — running the game inside the editor) → end with validation green.

Step 1 — Write the One-Pager

Copy Design/Abilities/_TEMPLATE.ability.md (in the repo, next to Documentation/) to a new file named after your ability, e.g. Design/Abilities/MyAbility.ability.md. The template self-documents its format — fill in every section and delete the <angle-bracket> hints.

The one-pager exists so the design is agreed on before any asset exists — there is no formal review step, just get a thumbs-up from the design lead before you start authoring. It is also your answer sheet for the wizard: the template's axes pre-answer the wizard's fields.

One-pager section Where it lands
Axis 1 — Archetype The wizard's Ability Base picker (first field).
Axis 2 — Targeting, Axis 3 — Timing Mostly hand-finish work in the Blueprint (Step 4); numeric parts land in the wizard's Tuning section.
Axis 4 — Effects The wizard's Required Tags and Tuning sections.
Axis 5 — Presentation (cue tags) Hand-finish (Step 4).
Cost / Cooldown The wizard derives the cooldown tag from the asset name (Step 2); cost/cooldown wiring is part of the ability base's contract.
Input The wizard's input-slot field (shown for player-activated ability bases).

Once the asset exists, the asset is the truth — mark the one-pager Authored with the asset path and stop editing it. Never maintain it as a second copy of the design.

Step 2 — Tags: mostly automatic now

The wizard derives your ability's tags from the asset name: naming it GA_CrashLanding proposes Cooldown.CrashLanding, the ability tag Ability.Skill.CrashLanding, and so on, and registers any that don't exist yet when you press Finish (it lists them in the form first, so nothing is written behind your back).

The one kind of tag you still register by hand is a cue tag (GameplayCue.* — the hooks your visuals and sounds hang on). The wizard deliberately doesn't invent those, because a cue tag is only useful together with the cue asset that plays it — you author both in the hand-finish step. If you need a tag outside the derived set, see How-To: Register a Gameplay Tag.

Step 3 — Create the asset with the guided wizard

  1. Open the Ability Workshop tab (it has its own button on the editor's toolbar).
  2. In its toolbar, open Create New and choose New from Ability Base... (guided). (The only other entry, Gameplay Effect, is not for abilities.)
  3. The wizard is a single form. Top to bottom:
  4. Ability Base — pick the row from your one-pager's Axis 1.
  5. Asset name — GA_<YourAbilityName> (the hint text shows the pattern). This drives the tag derivation from Step 2, so name it properly before touching anything else.
  6. Folder — leave the default unless you have a reason not to.
  7. The contract sections (Identity, Required Tags, Effect / Class References, Tuning) — one row per thing this ability base requires. Every field starts pre-filled from the base's template ability, so you only change what your design changes. Two rules of thumb:
    • Tag pickers are filtered to the right namespace per field. Derived tags are already filled in; picking one by hand replaces the derivation for that field.
    • In the Tuning section, values you type become flat numbers. If the one-pager says a value should be curve-driven, leave the field untouched here and author the curve in the Blueprint editor afterwards — the section's own title reminds you.
  8. Watch the blocker line at the bottom: it always names the next unmet requirement, and the Finish button stays disabled until it is empty. It is the checklist — you cannot finish wrong.
  9. Press Finish. The wizard registers any new derived tags, clones the base's template, stamps your values, saves, validates, and opens the new Blueprint.

Headless note: agents and scripts author through the Eternal.Ability.Stamp console command instead — same code path, no UI. Designers skip this; the wizard is your route.

Step 4 — Hand-finish in the Blueprint editor

The wizard does plumbing only. What makes the ability play — animation, hit timing, visuals, sound, feel — is hand-work, and for attack-type abilities the wizard shows a reminder saying exactly that. Work through How-To: Hand-Finish an Ability; it covers the montage, the hit-window notify, cue notifies, and feel curves.

Step 5 — Validate

Validation runs automatically when you save the asset. To sweep everything at once, press Validate All in the Ability Workshop toolbar and read the Output Log. Fix every error — there is no grandfather list in this project; a red asset is a broken asset, however old.

Step 6 — Put it in a kit

Abilities reach a character inside an Ability Kit — a small data asset bundling abilities with their input slots. Open the Kit Composer tab (next to the Ability Workshop's toolbar button):

  1. In the Kits view, create a new kit (or open an existing one — see DA_Kit_GreatswordMomentum in Content/DataAssets/Kits/ for a finished example).
  2. Add your ability as a row and set:
  3. Input slot — which button activates it (from your one-pager's Input section).
  4. Activation policy — activate on press, while held, or automatically when granted (for passives/auras).
  5. The panel's inline validation strip flags anything wrong — an ability with no input to bind to, two abilities fighting over one slot, and so on. Green strip = kit is sound.

Step 7 — Play it

  1. In the Kit Composer's Presets view, pick a preset build (e.g. Preset_Momentum) and add your kit to its granted-kits list. Kit order matters when two kits claim the same input — the later kit wins the slot.
  2. Start PIE from the L_Default level — the play-preset flow needs the main menu to boot, and other levels don't have it.
  3. Press Send to PIE in the Presets view. Your build spawns in and your ability is on its input slot.

From here it's a feel loop: play, tweak the Blueprint, play again — see How-To: Feel-Test Your Ability.

Done when

  • Validate All reports zero errors for your ability and its kit.
  • The ability activates on its input slot in PIE and plays its montage, hits, and cues.
  • The one-pager is marked Authored with the asset path.