> For the complete documentation index, see [llms.txt](https://docs.allout.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.allout.game/core-engine-concepts/abilities.md).

# Abilities

Abilities are the standard way to implement player actions with:

* A consistent button UI that works well on mobile and PC.
* Cooldowns, charges, toggles and hold-to-charge, all drawn for you
* Optional aiming (tap/drag on mobile, mouse aim on PC)

Abilities are **per-player**. When a player joins, All Out creates an instance of each ability type and stores it on `player.abilities`.

### Quick start (draw ability buttons)

Draw ability buttons in `Player.ao_late_update`, inside `is_local_or_server()`:

```go
Player :: class : Player_Base {
    ao_late_update :: method(dt: float) {
        if this.is_local_or_server() {
            draw_ability_button(this, Shoot_Ability, 0);  // big primary button
            draw_ability_button(this, Dodge_Roll, 1);     // small button
        }
    }
}
```

{% hint style="info" %}
Button indices map to fixed screen positions, so put the most-used action first. Index `0` is the large primary button in the bottom-right corner. Indices `1-4` ring it at thumb's reach, nearest first, and `5-6` sit on a second arc beyond them.
{% endhint %}

### Ability API reference

```go
Ability_Base :: class {
    player: Player;

    name: string;
    icon: Texture_Asset;

    current_cooldown: float;
    charges: int;           // A count badge while above zero.
    toggled_on: bool;       // Lit for as long as it is set.
    charge_progress: float; // 0..1. A ring around the button fills while a hold charges.
    button_visibility: Ability_Button_Visibility; // .ALWAYS, .TOUCH_DEVICES or .NEVER

    type: typeid;
    is_aimed_ability: bool;
    mouse_position_on_press: v2;

    keybind_override: Keybind;
    disable_keybind: bool;
    draw_but_dont_use_keybind: bool; // Show the key hint, but handle its input yourself.

    #interface on_update      :: proc(ability: Ability_Base, params: ref Ability_Update_Params);
    #interface can_use        :: proc(ability: Ability_Base) -> bool;
    #interface on_draw_button :: proc(ability: Ability_Base, rect: Rect);
}

Ability_Update_Params :: struct : Interact_Result {
    can_use: bool;        // cooldown + can_use + Player.ao_can_use_ability (if present)
    drag_offset: v2;      // 0..1
    drag_direction: v2;   // unit direction
}

draw_ability_button :: proc(player: Player, $T: typeid, index: int);
get_ability         :: proc(player: Player, $T: typeid) -> T;
```

### Button states

The engine draws every state of a button from the ability's values, the same way in every game:

| State          | Shown as                                      | Driven by                                                |
| -------------- | --------------------------------------------- | -------------------------------------------------------- |
| Ready          | Dark fill, white ring                         |                                                          |
| Pressed        | Shrinks and brightens                         | The press                                                |
| Cooldown       | The ring sweeps closed, with the seconds left | `current_cooldown`                                       |
| Ready again    | One pulse                                     | A cooldown of a second or more running out               |
| Charges        | A count badge                                 | `charges`                                                |
| Toggled on     | Yellow                                        | `toggled_on`                                             |
| Hold to charge | An outer ring fills                           | `charge_progress`                                        |
| Unavailable    | Dimmed, dashed ring                           | `can_use` or `Player.ao_can_use_ability` returning false |

Give each ability an `icon` that is white with a dark outline so it reads on any background.

### Creating an ability (basic click)

```go
Dash_Ability :: class : Ability_Base {
    on_init :: method() {
        name = "Dash";
        icon = get_asset(Texture_Asset, "icons/dash.png");
    }

    can_use :: method() -> bool {
        // Optional extra gating (in addition to cooldown)
        return true;
    }

    on_update :: method(params: ref Ability_Update_Params) {
        if params.clicked && params.can_use {
            // Apply gameplay here. This path runs through client prediction and on the server.
            // ...

            // IMPORTANT: set cooldown when you activate
            current_cooldown = 1.5;
        }
    }
}
```

### Holding abilities (active while held)

For abilities that are active while held (shield, beam, channel), use `Ability_Utilities.update_holding_ability` so it works on both PC and mobile.

```go
keybind_shield: Keybind;

ao_before_scene_load :: proc() {
    keybind_shield = Keybinds.register("Shield", .B);
}

Shield_Ability :: class : Ability_Base {
    on_init :: method() {
        name = "Shield";
        draw_but_dont_use_keybind = true;
        keybind_override = keybind_shield;
    }

    on_update :: method(params: ref Ability_Update_Params) {
        holding := Ability_Utilities.update_holding_ability(player, ref params, keybind_shield);
        player.shield_up = holding.active && params.can_use;
        toggled_on = player.shield_up; // Lights the button while the shield is up.
    }
}
```

### Jump and sprint (3D)

A player on a `Character_Controller_3D` gets two abilities from the engine, which draws them itself:

* `Stock_Jump_Ability`: Space, and on phones and tablets a button in slot `0`.
* `Stock_Sprint_Ability`: Shift, and pushing the on-screen stick past its ring. For players who turn on Run Lock in their settings, letting the stick go further up locks it into auto-run until it is touched again. It has no button by default.

They are ordinary abilities, so `Player.ao_can_use_ability` gates them and their fields are yours to change:

```go
Player :: class : Player_Base {
    ao_start :: method() {
        // Our own attack takes the big button, so jump moves to the arc.
        jump := get_ability(this, Stock_Jump_Ability);
        jump.slot = 1;

        // Give sprint a button on phones and tablets.
        sprint := get_ability(this, Stock_Sprint_Ability);
        sprint.slot = 2;
        sprint.button_visibility = .TOUCH_DEVICES;
        sprint.icon = get_asset(Texture_Asset, "icons/sprint.png");
    }
}
```

Their keys are the `Jump` and `Sprint` keybinds, which players can rebind. A keybind you register under either name in `ao_before_scene_load` is shared with the stock ability, `Keybinds.find("Jump")` returns the one in use, and `keybind_override` points an ability at any other keybind.

To replace one entirely, clear its bit from `player.defaults` (`PLAYER_DEFAULT_JUMP_CONTROLS`, `PLAYER_DEFAULT_SPRINT_CONTROLS`) and draw your own ability. `controller.request_jump()` and `player.request_sprint()` are what the stock abilities call. Clearing the sprint bit also removes the stick's sprint zone and auto-run; while it is set, `is_stick_sprinting()` is true when the stick is past its ring or locked.

On a touch device, a drag that starts on a button also turns a 3D player's camera, so a held attack can still be aimed. Aimed abilities are the exception: their drag aims the ability.

### Aimed abilities (drag to aim on mobile)

If you want “always aiming” behavior (mouse aim + click to fire on PC, press-drag-release on mobile), use `Ability_Utilities.full_update_aimed_ability`:

```go
Shoot_Ability :: class : Ability_Base {
    on_init :: method() {
        name = "Shoot";
        is_aimed_ability = true;
        disable_keybind = true;
    }

    on_update :: method(params: ref Ability_Update_Params) {
        activation := Ability_Utilities.full_update_aimed_ability(player, ref params);

        if activation.activate && params.can_use {
            // activation.direction is a unit vector
            // shoot_projectile(player.entity.world_position, activation.direction);
            current_cooldown = 0.5;
        }
    }
}
```

If you want “click to enter aim mode” (PC toggles aim mode; right-click cancels), use `Ability_Utilities.full_update_targeted_aimed_ability`:

```go
Roll_Ability :: class : Ability_Base {
    on_init :: method() {
        name = "Roll";
        is_aimed_ability = true;
    }

    on_update :: method(params: ref Ability_Update_Params) {
        activation := Ability_Utilities.full_update_targeted_aimed_ability(player, this, ref params);
        if activation.activate && params.can_use {
            current_cooldown = 1.25;
        }
    }
}
```

### Game-wide ability restrictions (optional)

Implement `ao_can_use_ability` on your `Player` class to enforce global rules (dead players can't use abilities, disabled during cutscenes, etc).

```go
Player :: class : Player_Base {
    ao_can_use_ability :: method(ability: Ability_Base) -> bool {
        if health.is_dead return false;
        return true;
    }
}
```

### Best practices

* Always draw buttons in `ao_late_update` and guard with `is_local_or_server()`
* Set `charges`, `toggled_on` and `charge_progress` instead of drawing your own counters, highlights or timers on a button
* Set `current_cooldown` when you activate (otherwise it can be spammed)
* Use `Ability_Utilities` helpers for holding/aiming so mobile + PC behave consistently
* Put global rules in `Player.ao_can_use_ability`, not duplicated per ability
