A lightweight ability system for fast-paced action games. Handles ability granting, cooldowns, activation callbacks, and custom data storage. Perfect for Nuclear Throne-style arcade games with quick ability activations and passive mutations.
Added:
- Tag System for Abilites! they can now be grouped and manipulated collectively (e.g., "disable all movement abilities", "remove all temporary abilities")
Author: SalmanShh
Made using CAW
To build the addon, run the following commands:
npm i
npm run build
To run the dev server, run
npm i
npm run dev
| Property Name | Description | Type |
|---|
| Action | Description | Params |
|---|---|---|
| Activate ability | Trigger an ability activation callback. Only works if ability is ready (off cooldown and enabled). | Ability ID (string) |
| Clear all abilities | Remove all abilities from the object. Triggers removal event for each ability. | |
| Create ability | Give the object an ability. Creates a new ability slot if it doesn't exist. | Ability ID (string) |
| Create ability with cooldown | Give the object an ability and set its cooldown in one action. Useful for initial setup. | Ability ID (string) Cooldown (number) Reset cooldown instantly (combo) |
| Create ability with cooldown and stacks | Give the object an ability and set its cooldown and max stacks in one action. Perfect for charge-based abilities. | Ability ID (string) Cooldown (number) Max stacks (number) Reset cooldown instantly (combo) |
| Create temporary ability | Create an ability that automatically removes itself after a duration. If ability already exists, just schedules new removal time Perfect for temporary power-ups and time-limited buffs. | Ability ID (string) Duration (number) |
| Remove ability | Remove an ability from the object. Deletes all associated data. | Ability ID (string) |
| Remove ability after duration | Schedule automatic removal of an ability after a duration. Useful for temporary power-ups and time-limited abilities. | Ability ID (string) Duration (number) |
| Set ability active | Set whether an ability is currently active (for channeled/duration abilities). | Ability ID (string) Active (combo) |
| Set ability enabled | Enable or disable an ability. Disabled abilities cannot be activated even if off cooldown. | Ability ID (string) Enabled (combo) |
| Reset cooldown | Instantly reset an ability's cooldown to 0, making it ready to use immediately. | Ability ID (string) |
| Set ability cooldown | Set the cooldown time for an ability. The ability will not be usable until the cooldown expires. | Ability ID (string) Seconds (number) |
| Set ability data | Store custom data on an ability (for passive bonuses, damage values, etc). Data is stored as strings. | Ability ID (string) Key (string) Value (any) |
| Add ability stacks | Add charges to an ability. Will not exceed max stacks. | Ability ID (string) Count (number) |
| Consume ability stack | Manually consume one charge of an ability without triggering activation. Starts stack regeneration. | Ability ID (string) |
| Set ability max stacks | Set the maximum number of charges an ability can have. Current stacks will be clamped to new max. | Ability ID (string) Max stacks (number) |
| Set ability stacks | Set the current number of charges for an ability. Clamped between 0 and max stacks. | Ability ID (string) Stacks (number) |
| Add tag to ability | Add a tag to an ability. Tags let you group abilities and manipulate them together. | Ability ID (string) Tag (string) |
| Clear all tags from ability | Remove all tags from an ability. | Ability ID (string) |
| Remove all abilities with tag | Remove every ability that has a specific tag. Fires OnAbilityRemoved for each one. | Tag (string) |
| Remove tag from ability | Remove a specific tag from an ability. | Ability ID (string) Tag (string) |
| Reset cooldown for all abilities with tag | Instantly reset the cooldown to 0 for every ability that has a specific tag. | Tag (string) |
| Set enabled for all abilities with tag | Enable or disable all abilities that have a specific tag. Useful for disabling a group of abilities during a stun or cutscene. | Tag (string) Enabled (combo) |
| Condition | Description | Params |
|---|---|---|
| Compare cooldown remaining | Compare the remaining cooldown time of an ability. | Ability ID (string) Comparison (cmp) Value (number) |
| Compare stacks | Compare the current number of charges for an ability. | Ability ID (string) Comparison (cmp) Value (number) |
| Has ability | Check if the object has been granted a specific ability. | Ability ID (string) |
| Has stacks available | Check if an ability has at least one charge available. | Ability ID (string) |
| Is ability active | Check if an ability is currently active (for channeled/duration abilities). | Ability ID (string) |
| Is ability enabled | Check if an ability is enabled (can be used when off cooldown). | Ability ID (string) |
| Is ability ready | Check if an ability is off cooldown, has stacks available, and is enabled (ready to use). | Ability ID (string) |
| Ability has tag | Check if an ability has a specific tag. | Ability ID (string) Tag (string) |
| On ability activated | Triggered when an ability is activated. | Ability ID (string) |
| On ability created | Triggered when an ability is created for the object. | Ability ID (string) |
| On ability ready | Triggered when an ability's cooldown expires and becomes ready to use. | Ability ID (string) |
| On ability removed | Triggered when an ability is removed from the object. The ability may be removed due to expiration or manual removal. | Ability ID (string) |
| On max stacks reached | Triggered when attempting to add charges beyond the maximum stack limit. Useful for UI feedback or sound effects. | Ability ID (string) |
| On stack consumed | Triggered when a charge is consumed from an ability. The ability may lose charges due to activation or manual consumption. | Ability ID (string) |
| On stack gained | Triggered when a charge is regenerated or added to an ability. The ability may gain charges due to regeneration or manual addition. | Ability ID (string) |
| Expression | Description | Return Type | Params |
|---|---|---|---|
| GetAbilityCount | Get the total number of abilities currently granted. | number | |
| GetAbilityData | Get custom data stored on an ability. Returns empty string if not found. | string | Ability ID (string) Key (string) |
| GetCooldownProgress | Get the cooldown progress from 0 (ready) to 1 (just started). Useful for UI progress bars. | number | Ability ID (string) |
| GetCooldownRemaining | Get the remaining cooldown time in seconds for an ability. | number | Ability ID (string) |
| GetExpirationProgress | Get the expiration progress from 0 (just created) to 1 (about to expire). Useful for countdown UI bars. | number | Ability ID (string) |
| GetExpirationTime | Get the time remaining in seconds before an ability is automatically removed. Returns 0 if no removal scheduled. | number | Ability ID (string) |
| GetMaxExpirationTime | Get the maximum expiration duration in seconds that was set for an ability. Returns 0 if no expiration was set. | number | Ability ID (string) |
| GetMaxStacks | Get the maximum number of charges for an ability. | number | Ability ID (string) |
| GetStackCooldownRemaining | Get the time remaining in seconds until the next stack regenerates. | number | Ability ID (string) |
| GetStackProgress | Get the stack regeneration progress from 0 (about to regenerate) to 1 (just used). Useful for UI. | number | Ability ID (string) |
| GetStacks | Get the current number of charges available for an ability. | number | Ability ID (string) |
| ListActiveAbilities | Get a comma-separated list of all ability IDs currently granted. | string | |
| CountAbilitiesByTag | Get the number of abilities that have a specific tag. | number | Tag (string) |
| ListAbilitiesByTag | Get a comma-separated list of ability IDs that have a specific tag. Use with tokencount() and tokenat() to loop through them. | string | Tag (string) |
Added:
- Tag System for Abilites! they can now be grouped and manipulated collectively (e.g., "disable all movement abilities", "remove all temporary abilities")
Added:
- Creating Abilities with cooldowns now have added parameter for it to be activated instantly, so theres less need to do it via another action. (CreateAbilityWithCooldown & CreateAbilityWithCooldownAndStacks)
- Create Guide documentation
Fixed:
- "IsAbilityReady" condition now properly includes stack availability
Added:
- GetMaxExpirationTime() expression.
Fixed:
- performance improvements, the addon will now scale significantly better. With 1000+ instances having mostly idle abilities, only the few with active cooldowns/regeneration will consume CPU time, meaning it only ticks if theres an active timer (expiration/cooldowns)
Added:
- Expiration TIme for abilities shows up on Debugger.
- GetExpirationProgress(Ability ID) expression
Added: Add trigger for max stacks reached event in ability system
Added: Implement temporary ability management and automatic removal features
Changed: Debugger: Abilities retain their behaviour's name so its easier to know which behaviour instance they originate from.
Added: Ability Management
- Create/remove abilities with unique IDs
- Enable/disable abilities independently
- Active state tracking for channeled abilities
Cooldown System
- Automatic cooldown tracking per frame
- "On Ready" triggers when cooldowns expire
- Manual cooldown manipulation
Stack/Charge System
- Multi-use abilities (dash 3 times, throw 5 grenades)
- Automatic charge regeneration
- Individual stack consumption with triggers
Custom Data Storage
- Store arbitrary key-value data per ability
- Perfect for damage values, range, passive bonuses
- Lazy-loaded for memory efficiency
Event Triggers
- On Ability Ready/Activated/Created/Removed
- On Stack Consumed/Gained
- Filter by specific ability or catch all
Added: Initial release.