> 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/lua-handle.md).

# Lua handle

The object api.register returns. Your Lua's identity, cleanup tracker and hook holder, for every Lua type.

```lua
local lua = api.register(name: string, type: "ragebot planner" | "misc" | "both")
```

Any other `type` errors.

## Fields

| Field           | Type        | Description                   |
| --------------- | ----------- | ----------------------------- |
| `lua.name`      | `string`    | the name you registered       |
| `lua.kind`      | `string`    | the type you registered       |
| `lua.alive`     | `boolean`   | `false` once unloaded         |
| `lua.on_unload` | `function?` | set it; called once on unload |

`name`, `kind` and `alive` are read only.

## Methods for every Lua

### `lua:override()`

Makes this Lua the active owner of its slot(s), unloading whatever was there. Called for you when loading from the menu.

### `lua:unload()`

Unloads this Lua. Safe to call more than once. See [Lifecycle & slots](/elite-zone/getting-started/lifecycle-and-slots.md) for what gets cleaned up.

### `lua:connect(signal, fn)` → `RBXScriptConnection`

Like `signal:Connect(fn)`, but disconnected automatically on unload.

### `lua:on_changed(idx, fn)`

Calls `fn(value)` whenever menu element `idx` changes, until unload.

### `lua:tab(name, before?)` → `Tab`

Adds a tab to the Elite Zone window, removed on unload. Pass `before` (an existing tab's name) to place it before that tab; otherwise it goes at the end. Errors if a tab with that name already exists.

```lua
local tab = lua:tab("my lua", "world")   -- sits between main and world
local box = tab:AddLeftGroupbox("settings")
```

### `lua:box(tab, side, name)` → `Groupbox`

Adds a groupbox to **any** tab, including Elite Zone's own. `tab` is a tab name or a tab object, `side` is `"left"` or `"right"`. Removed on unload.

```lua
local box = lua:box("main", "right", "my lua")
box:AddToggle("my_lua_enabled", { Text = "enabled", Default = true })
```

### `lua:tabbox(tab, side)` → `Tabbox`

Adds a tabbox to **any** tab, for when a Lua has several groups of settings that are easier to switch between than to scroll. `tab` is a tab name or a tab object, `side` is `"left"` or `"right"` and defaults to left. Removed on unload, and it takes its tabs with it.

Each tab you add to the returned tabbox is a groupbox, so settings attach to it directly.

```lua
local tab = lua:tab("my lua")
local tabbox = lua:tabbox(tab, "right")
tabbox:AddTab("general"):AddToggle("my_lua_enabled", { Text = "enabled", Default = true })
tabbox:AddTab("advanced"):AddSlider("my_lua_depth", { Text = "depth", Default = 3, Min = 1, Max = 10, Rounding = 0 })
```

{% hint style="info" %}
Prefix your element names with your Lua's name (`my_lua_...`) so they never collide with Elite Zone's own.
{% endhint %}

## Methods for ragebot planners

### `lua:add_method(kind, name, fn)` → `DependencyBox`

Adds `name` to the ragebot `"strafe"` or `"shooting"` dropdown. Errors if the name already exists. Returns a **settings box** inside the ragebot box that is only visible while your method is selected. See [custom methods](/elite-zone/api-reference/api.ragebot.md#custom-methods).

### `lua:allow_manual(allowed)`

By default, loading a planner hides the ragebot settings so the user can't fight with it. `lua:allow_manual(true)` keeps them visible, for Luas that only add presets or methods. `lua:allow_manual(false)` hides them again.

## Hooks

Set these as fields on the handle.

| Hook             | For              | Arguments            | Return                          |
| ---------------- | ---------------- | -------------------- | ------------------------------- |
| `lua.step`       | ragebot planners | `dt, duel, status`   | `"stop"` \| `"void"` \| `nil`   |
| `lua.target`     | ragebot planners | `duel, item`         | target \| `nil`                 |
| `lua.can_shoot`  | ragebot planners | `target, item`       | `false` to block the shot       |
| `lua.anti_aim`   | ragebot planners | `dt, cframe, target` | `CFrame` to use \| `nil` (keep) |
| `lua.aim_select` | misc Luas        | `feature`            | target \| `false` \| `nil`      |
| `lua.aim_target` | misc Luas        | `feature, target`    | target \| `false` \| `nil`      |

Ragebot hooks are on [api.ragebot](/elite-zone/api-reference/api.ragebot.md#hooks), aim hooks on [api.targeting](/elite-zone/api-reference/api.targeting.md#hooks).

{% hint style="warning" %}
`lua.step` returns **`"void"`**, not `"evade"`. Returning `"evade"` does nothing and your planner keeps acquiring targets and shooting.
{% 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/lua-handle.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.