Ability Asset Identifier SO Documentation

This document covers the Active Ability (AbilityDefinitionSO) and Passive Ability (PassiveDefinitionSO) ScriptableObjects — what they are, how to create them, what every field does, and what parameters are available.

---

Table of Contents

1. Overview
2. Class Hierarchy
3. Creating a New Ability SO
4. Assigning a GUID
5. Registering in the Catalogue
6. AbilityDefinitionSO — Field Reference
   • Base Fields
   • Target Conditions
   • Ability Effect Configs
   • Animation Data
7. PassiveDefinitionSO — Field Reference
   • Base Fields
   • Passive Targeting
   • Passive Effect Conditions
   • Passive Effect Configs
8. Enum Reference
9. Pre-Build Catalogue Validation

---

1. Overview

Ability SOs are data containers that define what an ability is and how it behaves — its name, description, range, targets, effects, and animations. They do not contain runtime state; that lives in AbilityInstance / PassiveInstance, which are created at runtime from these definitions.

There are two distinct types:

Type	Class	Menu Path	Catalogue Key
Active Ability	AbilityDefinitionSO	Ability / Ability Definition	ABILITY_CATALOGUE
Passive Ability	PassiveDefinitionSO	Ability / Passive Definition	PASSIVE_CATALOGUE

Active abilities are used on a unit’s turn as their ability action. Passives trigger automatically in response to in-game events (e.g., on turn start, when hit).

Both types inherit from the same base chain, so they share the GUID and displayName fields.

---

2. Class Hierarchy

ScriptableObject  (Unity)
└── AssetIdentifierBaseSO
        guid  (string, SCREAMING private, read-only in editor)
        GUID  (string property)
        GetGUID() → string
        GenerateNewGUID()  [ContextMenu]
    └── DefinitionSO  (abstract)
            displayName  (string)
        ├── AbilityDefinitionSO
        └── PassiveDefinitionSO

Scripts:

• AssetIdentifierBaseSO — Assets/Scripts/Game Management/Asset Identifiers/AssetIdentifierBaseSO.cs
• DefinitionSO — Assets/Scripts/DeveloperConsole/ConsoleCommands/DefinitionSO.cs
• AbilityDefinitionSO — Assets/Scripts/Ability System/Active/AbilityDefinitionSO.cs
• PassiveDefinitionSO — Assets/Scripts/Ability System/Passive/PassiveDefinitionSO.cs

---

3. Creating a New Ability SO

Active Ability

1. In the Project window, navigate to Assets/Assets/Asset Identifier SOs/Abilities/.
2. Choose the correct subfolder for the unit that owns this ability (e.g., Player/Construct/ or Enemy/Banshee/).
3. Right-click → Create → Ability → Ability Definition.
4. Name the asset to match the ability’s display name (no spaces required in file name, but consistency helps).

Passive Ability

1. Navigate to Assets/Assets/Asset Identifier SOs/Passives/.
2. Choose the subfolder for the owning unit.
3. Right-click → Create → Ability → Passive Definition.
4. Name the asset accordingly.

---

4. Assigning a GUID

Every ability SO must have a unique GUID before it can be used by the game. The GUID is what the runtime uses to look up the ability — it is stable across renames and moves.

To generate a GUID:

1. Select the ability SO in the Project window.
2. In the Inspector, right-click the component header (or use the three-dot menu) and choose Generate New GUID.
3. The guid field will populate with a UUID v4 string (e.g., 6d7732c9-dad6-475a-ab3b-5449b1e38961).
4. Save the asset (Ctrl+S or File → Save).

Warning

Never manually edit the guid field. It is marked read-only in the Inspector for this reason. Never copy-paste a GUID from another SO — duplicate GUIDs will cause AssetCatalogueSO.InitializeCatalogue() to silently skip one of the assets, causing runtime lookup failures. The commit history includes a specific fix for this (fixed duplicate guid).

The GUID field is serialised in the .asset file under the guid: key. If a SO is missing a GUID, the catalogue will log an error and skip it at runtime.

---

5. Registering in the Catalogue

After creating and assigning a GUID, the SO must be added to the appropriate AssetCatalogueSO:

1. Navigate to Assets/Assets/Catalogues/ and open Ability Catalogue (key: ABILITY_CATALOGUE) or Passive Catalogue (key: PASSIVE_CATALOGUE).
2. In the Inspector, scroll to Auto-Fill Catalogue.
3. Select Active Abilities (or Passive Abilities) from the dropdown.
4. Click the green Fill with ActiveAbilities button.

This scans the entire project for all AbilityDefinitionSO / PassiveDefinitionSO assets and replaces the catalogue list. Assets are sorted alphabetically by name.

Note

The Auto-Fill button replaces the existing list, so it is safe to re-run at any time. Run it whenever you add, remove, or rename an ability SO.

A pre-build check (AssetCataloguePreBuildCheck) runs automatically before every build. If the count of SOs in the project does not match the count in the catalogue, it will prompt you to stop the build and re-sync. This prevents shipping with a stale catalogue.

---

6. AbilityDefinitionSO — Field Reference

6.1 Base Fields

These fields are inherited from the base classes.

Field	Type	Description
guid	string	Read-only. The unique identifier for this asset. Generated via context menu. See Section 4.
displayName	string	The human-readable name shown in the UI and developer console (e.g., "Bash", "Ram").
description	string	Flavour text / tooltip shown to the player (e.g., "Bash a unit, dealing 20 damage.").
cooldown	int	Number of turns that must pass before this ability can be used again. 0 means no cooldown.

6.2 targetConditions

Type: TargetConditions (struct defined in TargetFlags.cs).

Describes how the ability selects its primary target — range, direction type, what counts as a valid target, and the area of effect around that target.

Sub-field	Type	Description
maxRange	uint	Maximum cell distance to the targeted cell/unit.
minRange	uint	Minimum cell distance. Should be 1 for most abilities. Set to 0 only if the ability can target the caster’s own cell.
targetType	ETargetType (flags)	How the ability reaches its target. Can be combined. See Section 8.
validTargets	EValidTargets (flags)	Who or what can be selected as the primary target. Can be combined. See Section 8.
aoeType	EAOEType	The shape of the area-of-effect around the primary target. None for single-target abilities. See Section 8.
aoeRange	uint	Radius or extent of the AOE (only relevant for Radius and Square AOE types).
aoePattern	PatternAOE	Only shown when aoeType is Pattern. Defines a bespoke cell offset pattern relative to the target.

Targeting example — single-target melee:

maxRange: 1, minRange: 1
targetType: Cardinal | Diagonal   (= All adjacent cells)
validTargets: Opponent
aoeType: None

Targeting example — line shot (piercing):

maxRange: 5, minRange: 1
targetType: Cardinal | Piercing
validTargets: Opponent
aoeType: Piercing

6.3 abilityEffectConfigs

Type: AbilityEffectConfig[]

An ordered array of effects that execute when the ability is used. Most abilities have one effect; some chain multiple (e.g., deal damage then apply a status effect).

Each AbilityEffectConfig has the following fields:

Sub-field	Type	Description
effectSO	AbilityEffect	Reference to the AbilityEffect ScriptableObject that contains the execution logic.
effectCondition	EffectCondition	(Optional) A condition SO that must pass before this effect executes. Leave blank if the effect should always run.
effectParameters	EffectParameters	(Polymorphic via [SerializeReference]) The data values passed to the effect at runtime (e.g., baseDamage, damageMultiplier, status effect reference). The type shown in the Inspector changes based on the selected effectSO.
effectEventName	StringAsset	(Animancer) The animation event name that triggers this specific effect when driveAbilityEffectsThroughAnimation is true. Leave blank when using the sequential system.

Important

effectParameters is a [SerializeReference] field, which means it stores the parameters inline in the asset rather than as a separate file. The concrete type of effectParameters must match what the effectSO expects. Mismatches will produce a NullReferenceException at runtime. The commit the unfuckening of items and effect params is here fixed a widespread issue with mismatched parameters — always verify parameter types match the effect.

6.4 Animation Data

Field	Type	Description
driveAbilityEffectsThroughAnimation	bool	If true, each effect in abilityEffectConfigs is triggered by a named animation event (set via effectEventName) rather than being fired sequentially by code. Use this for abilities where the hit timing must align with a specific animation frame (e.g., a swing landing). If false, all effects execute in array order via the sequential system immediately when the ability is used.
abilityAnimationSequence	AnimationSequenceRequest	Defines the animation clip transitions to play when this ability is used. Check HasAnimationSequence() — returns true if the sequence has at least one transition configured.

---

7. PassiveDefinitionSO — Field Reference

7.1 Base Fields

Field	Type	Description
guid	string	Read-only. Unique identifier. See Section 4.
displayName	string	Human-readable name (e.g., "Refraction Veil", "LAN Repair").
description	string	Tooltip text shown in the UI (e.g., "On turn end, gain Invisible.").
passiveType	EPassiveType	The in-game event that triggers this passive. See Section 8.

7.2 passiveTargeting

Type: PassiveTargeting (struct defined in PassiveDefinitionSO.cs).

Describes which units are affected when the passive triggers — similar in purpose to TargetConditions on an active ability.

Sub-field	Type	Description
validTargets	EValidTargets (flags)	Who can be affected when the passive fires. Can be combined. See Section 8.
aoeType	EAOEType	The shape of the area searched for valid targets. See Section 8.
aoePattern	PatternAOE	Only shown when aoeType is Pattern. Bespoke cell offset pattern.
minRange	uint	Minimum cell distance to affected targets.
maxRange	uint	Maximum cell distance to affected targets.

7.3 passiveEffectConditions

Type: EffectCondition[]

An ordered array of condition SOs that are all evaluated before the passive’s effects fire. All conditions must pass. If the array is empty, the passive always triggers when its passiveType event fires.

EffectCondition is abstract (Assets/Scripts/Item System/Effects/EffectCondition.cs). Concrete implementations live in Assets/Scripts/Item System/Conditions/ and can be created as SOs via Create → Items → Conditions → ....

7.4 passiveEffectConfigs

Type: AbilityEffectConfig[]

The same structure as active abilities — an ordered array of effects to execute when the passive fires. See Section 6.3 for the full field breakdown.

---

8. Enum Reference

ETargetType (flags — can be combined)

Defined in TargetFlags.cs. Controls how the targeting ray/area extends from the caster.

Value	Meaning
Cardinal	Targets can be selected along the four cardinal directions (up, down, left, right).
Diagonal	Targets can be selected along the four diagonal directions.
Piercing	The targeting line passes through obstructions rather than stopping at the first hit.
Trail	Affects cells along the path to the target, not just the target cell.
Radius	Targets any cell within the specified range (omnidirectional, no line).
All	All of the above combined.

Multiple values can be combined with the bitwise OR (|) operator in code, or by ticking multiple checkboxes in the Inspector (the field is a [Flags] enum).

EValidTargets (flags — can be combined)

Controls who or what the ability can target.

Value	Meaning
Self	Can target the caster’s own cell/unit.
Ally	Can target friendly units.
Opponent	Can target enemy units.
Cover	Can target cover/obstacle entities.
EmptyCells	Can target empty cells (no unit present). Useful for movement or placement abilities.
FirstInLine	Only the first valid target along the targeting line is selected (stops at first hit).
All	All of the above combined.

EAOEType

Controls the shape of the area-of-effect around the primary target.

Value	Meaning
None	No AOE; only the primary target is affected.
Radius	A circular/diamond area of aoeRange cells around the target.
Square	A square area of aoeRange cells around the target.
Trail	Affects all cells along the targeting path up to and including the target.
Piercing	Continues along the targeting line past the target.
Pattern	Uses a bespoke PatternAOE definition for an irregular shape.

EPassiveType

Determines when a passive triggers.

Value	Trigger Condition
onEquip	Fires once when the passive is first applied to a unit (e.g., apply a permanent buff).
onHit	Fires when the unit bearing the passive deals a hit.
onTakeDamage	Fires when the unit bearing the passive takes damage.
onStatusGained	Fires when the unit bearing the passive gains a status effect.
onHeal	Fires when the unit bearing the passive is healed.
onTurnStart	Fires at the start of the unit’s turn.
onTurnEnd	Fires at the end of the unit’s turn.
onBattleStart	Fires once at the very beginning of a battle.

---

9. Pre-Build Catalogue Validation

AssetCataloguePreBuildCheck (Assets/Scripts/Game Management/Asset Catalogues/Editor/AssetCataloguePreBuildCheck.cs) runs automatically before every Unity build.

It checks the following catalogues:

Catalogue	Key	Type checked
Active Abilities	ABILITY_CATALOGUE	AbilityDefinitionSO
Passive Abilities	PASSIVE_CATALOGUE	PassiveDefinitionSO

If the number of SOs found in the project does not match the count in the catalogue, a dialog will appear asking whether to stop the build or continue anyway. The recommended action is always to stop and re-sync using the Auto-Fill button on the catalogue asset.

To re-sync manually at any time, open the relevant catalogue SO in the Inspector, scroll to Auto-Fill Catalogue, pick the correct type, and click Fill.