> For the complete documentation index, see [llms.txt](https://scripter-sm.gitbook.io/elite-zone/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://scripter-sm.gitbook.io/elite-zone/api-reference/api.ragebot.md).

# api.ragebot

Steer the ragebot every frame. Targets, shots, movement, desync, anti aim, healing, custom methods and presets.

A **ragebot planner** (`"ragebot planner"` or `"both"`) plugs into the ragebot's own frame loop. New here? Read the Ragebot planner guide first.

{% hint style="info" %}
The ragebot only steps while `ragebot_enabled` is on and its keybind is active. A planner can turn it on itself with `api.ui.set("ragebot_enabled", true)`.
{% endhint %}

## Menu while a planner is loaded

When a planner takes the Ragebot slot, the ragebot box keeps only the **enabled** toggle and its keybind, then a divider and the label **ragebot is controlled by ragebot planner**. Presets and every other ragebot setting are hidden.

* The settings are **hidden, not deleted**. The ragebot still reads them, and your planner can still change them with `api.ui.set` and presets.
* They are still saved in configs.
* When the planner unloads, everything comes back.

Planners that only add presets or methods and let the user choose should call `lua:allow_manual(true)` to keep the settings visible.

## Where hooks run

```mermaid
flowchart TD
    A[Heartbeat] --> B{ragebot enabled?}
    B -- no --> Z[idle]
    B -- yes --> S["lua.step(dt, duel, status)"]
    S -- stop --> Z
    S --> L{round live?}
    L -- no --> E[void / equip]
    L -- yes --> H{healing?}
    H -- yes --> HV[void + medkit]
    H -- no --> W{step returned void?}
    W -- yes --> E2[void]
    W -- no --> G["lua.target(duel, item)<br/>or built-in acquire"]
    G -- nil --> E2
    G --> C["lua.can_shoot(target, item)"]
    C --> M[strafe / melee position]
    E2 --> AA["anti aim<br/>lua.anti_aim(dt, cframe, target)"]
    M --> AA
    AA --> F[shooting method]
```

If `api.ragebot.desync(cframe)` is set, it replaces the position from strafe, void and anti aim in every state.

## Hooks

### `lua.step(dt, duel, status)` → `"stop" | "void" | nil`

Runs every ragebot frame, in **every** round state: `"Voting"`, `"RoundStarting"`, `"RoundStarted"`, `"RoundFinished"`, or anything else. `duel` may be `nil`.

| Return   | Effect this frame                              |
| -------- | ---------------------------------------------- |
| `nil`    | normal behaviour                               |
| `"void"` | no target: hold the void position, never shoot |
| `"stop"` | release everything, as if the ragebot were off |

{% hint style="warning" %}
The string is **`"void"`**. `"evade"` was the old name and no longer does anything — returning it leaves your planner acquiring targets and shooting as normal.
{% endhint %}

### `lua.target(duel, item)` → target | `nil`

Replaces target selection. Return a target, or `nil` for none.

### `lua.can_shoot(target, item)` → `boolean`

Return `false` to hold fire this frame. Movement continues.

### `lua.anti_aim(dt, cframe, target)` → `CFrame` | `nil`

Runs every ragebot frame once the round has started, after the ragebot decided where to put you and before it shoots, even when the anti aim toggle is off. `cframe` has the menu's anti aim already applied (`nil` if the toggle is off). Return a `CFrame` to use instead, or `nil` to keep it. Not called for the `underground` strafe.

{% hint style="danger" %}
If any hook errors, Elite Zone shows `<name> error: ...` and **unloads the planner** so the ragebot keeps working.
{% endhint %}

## Desync: put yourself anywhere

| Function                      | What it does                                                                                                                    |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `api.ragebot.desync(cframe)`  | from now on, the server sees you at `cframe` every ragebot frame; your own screen doesn't move. Pass `nil` to go back to normal |
| `api.ragebot.desynced()`      | the current desync `CFrame`, or `nil`                                                                                           |
| `api.ragebot.client_cframe()` | your real, visible position, or `nil` if the ragebot isn't running                                                              |

* It overrides strafe, void and anti aim, in every round state the ragebot runs in.
* While it's set, shots are fired from it.
* It's cleared automatically when your planner unloads.

## Custom methods

`lua:add_method(kind, name, fn)` adds `name` to the ragebot's strafe or shooting dropdown. While it's selected, `fn` replaces the built-in method. Select it with `api.ui.set("ragebot_strafe", name)` or `api.ui.set("ragebot_shooting", name)`.

It **returns a settings box** inside the ragebot box, only visible while your method is selected. Put your method's settings there:

```lua
local box = lua:add_method("strafe", "tight orbit", function(target)
    local head = target.head.Position
    local angle = os.clock() * speed.Value
    local pos = head + Vector3.new(math.cos(angle) * radius.Value, 0, math.sin(angle) * radius.Value)
    return CFrame.lookAt(pos, head)
end)
radius = box:AddSlider("tight_orbit_radius", { Text = "radius", Default = 5, Min = 1, Max = 20, Rounding = 1 })
speed = box:AddSlider("tight_orbit_speed", { Text = "speed", Default = 6, Min = 1, Max = 50, Rounding = 1 })
```

{% hint style="info" %}
`radius` and `speed` are declared as `local radius, speed` above the method in a real script. The box sits inside the ragebot settings, so call `lua:allow_manual(true)` or the user won't see it.
{% endhint %}

{% tabs %}
{% tab title="Strafe" %}
**`fn(target, root_part, client_cf, duel)` → `CFrame` | `nil`**

Return where you are for the server this frame, or `nil` to dodge. Anti aim is applied on top, and shooting uses this position.
{% endtab %}

{% tab title="Shooting" %}
**`fn(target, item, cframe, dt)` → `{ pitch, yaw }` | `nil`**

Runs every frame while there's a target. `cframe` is where you are for the server this frame and `item` is the weapon. Fire the UseItem remote yourself with `api.game.use_item`, and return the camera angles (degrees) to send with it, or `nil`. Limit the rate yourself.
{% endtab %}
{% endtabs %}

## Targets

| Function                          | Returns                                                                                        |
| --------------------------------- | ---------------------------------------------------------------------------------------------- |
| `api.ragebot.target()`            | the target this frame, or `nil`                                                                |
| `api.ragebot.acquire()`           | Elite Zone's pick: lowest health, then closest; skips allies, protected and deflecting players |
| `api.ragebot.make_target(player)` | `{ player, head, root }`, or `nil` if not loaded                                               |

## Healing

The ragebot can heal with your medkit in the void. With the **medkit heal** toggle on (`ragebot_medkit`) it does this by itself below the **heal below** health; a Lua can also ask for a heal at any time.

| Function                  | What it does                                                                                                                                           |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `api.ragebot.heal(mode?)` | heal as soon as possible, even with the toggle off. `mode` is `"quick heal"` (+25) or `"long heal"` (+70); `nil` uses the menu's `ragebot_medkit_mode` |
| `api.ragebot.healing()`   | `true` while the ragebot is in the void equipping or using the medkit                                                                                  |

* The request only goes through during a live round, with a medkit in your inventory that's off cooldown and you below max health. Otherwise it's dropped.
* While healing, the ragebot sits in the void and doesn't target or shoot. Your hooks' `target` and `can_shoot` aren't called.

```lua
lua.step = function(dt, duel, status)
    local hum = game.Players.LocalPlayer.Character and game.Players.LocalPlayer.Character:FindFirstChildOfClass("Humanoid")
    if hum and hum.Health < 40 and not api.ragebot.healing() then
        api.ragebot.heal("quick heal")
    end
end
```

## Presets

| Function                               | Description                         |
| -------------------------------------- | ----------------------------------- |
| `api.ragebot.presets()`                | sorted preset names                 |
| `api.ragebot.get_preset(name)`         | a preset's data table               |
| `api.ragebot.capture()`                | the current settings as preset data |
| `api.ragebot.apply_preset(name)`       | apply; `false` if it doesn't exist  |
| `api.ragebot.save_preset(name, data?)` | save `data` or the current settings |

Presets from the user's config are included, so a planner shipped with a config can switch between that config's presets.

{% hint style="warning" %}
`Default`, `UE Killer`, `Honest` and `OOB Baiting` are built-in and can't be overwritten.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://scripter-sm.gitbook.io/elite-zone/api-reference/api.ragebot.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.