> ## Documentation Index
> Fetch the complete documentation index at: https://luau.limerence.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> api.feature: per-feature namespaces (Auto Loot, Music HUD, Auto Peek, Anti Aim).

`api.feature` groups the per-feature namespaces. The table itself exists in every game, but a sub-namespace is only present where its feature is, so check before using it:

```luau theme={null}
if api.feature.autoloot then
    -- Apocalypse Rising 2 only
end
```

| Namespace                | Games                                                      |
| ------------------------ | ---------------------------------------------------------- |
| [`autoloot`](#auto-loot) | Apocalypse Rising 2.                                       |
| [`musichud`](#music-hud) | Every game.                                                |
| [`autopeek`](#auto-peek) | Bloxstrike, Rivals, Overkill, Murderers vs Sheriffs Duels. |
| [`antiaim`](#anti-aim)   | Bloxstrike.                                                |

## Auto Loot

`api.feature.autoloot` — **Apocalypse Rising 2 only.** Watch and shape the Auto Loot feature. You can read whether it's on, react when it acts, block items or action types it isn't allowed to do, force it to grab specific items, and kick off a loot pass on demand.

Everything here only ever **limits or nudges** Auto Loot. Your filters can stop it from doing things the menu would otherwise allow, but they can't make it ignore the user's own settings, and a forced item is still only grabbed when there's room for it.

### What you can read

| Call          | Returns   | What it tells you                                 |
| ------------- | --------- | ------------------------------------------------- |
| `isEnabled()` | `boolean` | Whether Auto Loot is turned on in the menu.       |
| `isActive()`  | `boolean` | `true` while it's mid-pass, working through loot. |

### Things that notify you

Call `:Connect(callback)`. Disconnects on unload.

| Signal     | Your callback receives                                                       |
| ---------- | ---------------------------------------------------------------------------- |
| `onAction` | `(action)`: each time Auto Loot performs a loot action. See the table below. |

The `action` table:

```luau theme={null}
{
    type = "pickup",   -- pickup | drop | equip | unload | fill | craft | removeAttach | slotUtility
    kind = "weapon",   -- weapon | mag | ammo | heal | food | drink (pickups only, else nil)
    name = "AK-47",    -- item name when known, else nil
    caliber = "7.62x39",
    slot = "Primary",  -- equip slot when relevant, else nil
}
```

See [AutoLootAction](/reference/types#autoloot-types).

<Note>
  `api.autoloot` is a deprecated alias for `api.feature.autoloot`. It still works and warns once per script; new scripts should use `api.feature.autoloot`.
</Note>

### Shaping what it does

All registrations return a handle with `:Release()`, `:IsReleased()` and `:GetPriority()`; filter handles also support `:SetPriority(n)`. They're also released when your script unloads.

| Call                             | What it does                                                                                                    |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `addItemFilter(fn, priority?)`   | Decide whether Auto Loot may pick up / keep an item.                                                            |
| `addActionFilter(fn, priority?)` | Decide whether a chosen action may run.                                                                         |
| `blockItem(name or {names})`     | Shortcut: never pick up the named item(s).                                                                      |
| `blockAction(type or {types})`   | Shortcut: never perform the named action type(s), e.g. `"drop"`.                                                |
| `forceItem(name, durationSec?)`  | Always grab the named item off nearby loot when there's room, ahead of normal priorities. Optional auto-expiry. |
| `scan()`                         | Kick off a loot pass right now.                                                                                 |

* **`addItemFilter(fn(item))`**: runs for pickup / utility-slot decisions. The `item` is `{ name, rawName, type, caliber, slot }`. Return `false` to block that item. Every filter must pass.
* **`addActionFilter(fn(action))`**: runs right before an action executes. The `action` is the same shape as the `onAction` table. Return `false` to block it. Every filter must pass.
* Higher `priority` runs first; equal priority runs in registration order. A blocked action goes on a short cooldown and Auto Loot moves on to the next best thing, so blocking one item or action never stalls the rest.

### Auto Loot examples

```luau theme={null}
-- Never loot a specific gun, and never let it drop your gear
api.feature.autoloot.blockItem("Makarov")
api.feature.autoloot.blockAction("drop")

-- Only ever pick up 7.62 ammo
api.feature.autoloot.addItemFilter(function(item)
    if item.type == "Ammo" then
        return item.caliber == "7.62x39"
    end
    return true
end)

-- Force-grab medkits for the next 30 seconds, then scan now
api.feature.autoloot.forceItem("Medkit", 30)
api.feature.autoloot.scan()

-- Log everything it does
api.feature.autoloot.onAction:Connect(function(action)
    print("autoloot", action.type, action.name)
end)
```

## Music HUD

`api.feature.musichud` — **every game.** Read what the Music HUD is showing (current track, playback progress, synced lyrics), or plug in your own music and lyrics source.

Track and lyric data is only available while the Music HUD is enabled in the menu and a source is playing.

### What you can read

| Call            | Returns           | What it tells you                                                            |
| --------------- | ----------------- | ---------------------------------------------------------------------------- |
| `isEnabled()`   | `boolean`         | Whether the Music HUD is turned on in the menu.                              |
| `isPaused()`    | `boolean`         | `true` while playback is paused or nothing is playing.                       |
| `getTrack()`    | `MusicTrack?`     | The current track, or `nil` when nothing is playing.                         |
| `getPlayback()` | `MusicPlayback?`  | Live playback progress, or `nil` when nothing is playing.                    |
| `getLyrics()`   | `{ MusicLyric }?` | All synced lyric lines for the current track, or `nil` when none were found. |
| `getLyric()`    | `string?`         | The lyric line at the current playback position, or `nil`.                   |

The `MusicTrack` table:

```luau theme={null}
{
    id = "...",            -- provider track id
    title = "Song Title",
    artist = "Artist",
    album = "Album",       -- nil when unknown
    coverUrl = "https://", -- cover art url, nil when unknown
    duration = 213,        -- seconds
}
```

The `MusicPlayback` table:

```luau theme={null}
{
    elapsed = 42.5,   -- seconds into the track
    duration = 213,   -- seconds
    paused = false,
}
```

Each `MusicLyric` is `{ time, text }`, where `time` is the second the line starts at.

### Music HUD signals

Call `:Connect(callback)`. Disconnects on unload.

| Signal           | Your callback receives                                                     |
| ---------------- | -------------------------------------------------------------------------- |
| `onTrackChanged` | `(track: MusicTrack?)`: the track changed, or `nil` when playback stopped. |
| `onPauseChanged` | `(paused: boolean)`: playback paused or resumed.                           |

### Bringing your own source

| Call              | What it does                                                                                           |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| `setSource(spec)` | Overrides where the HUD gets its music from. Pass `nil` to go back to the provider picked in the menu. |
| `setLyrics(fn)`   | Overrides where lyrics come from. Pass `nil` to go back to the built-in lyrics lookup.                 |

While a source override is set, the HUD polls it instead of the provider selected in the menu. It is cleared automatically when your script unloads. Setting a new one replaces the previous one.

**`setSource(spec)`**: the `spec` table:

| Field      | Type                        | What it does                                                                                                    |
| ---------- | --------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `poll`     | `() -> (track?, playback?)` | **Required.** Called on the poll interval. Return the current track and playback, or `nil` for nothing playing. |
| `interval` | `number?`                   | Seconds between polls. `0.25` to `30`, default `1`.                                                             |
| `reset`    | `(() -> ())?`               | Called when the HUD starts using your source, so you can drop cached state.                                     |
| `name`     | `string?`                   | Label for your source.                                                                                          |

Your `poll` return values:

```luau theme={null}
-- track
{
    id = "...",            -- optional, defaults to title + artist
    title = "Song Title",  -- required
    artist = "Artist",     -- optional
    album = "Album",       -- optional
    coverUrl = "https://", -- optional, http(s) image url
    duration = 213,        -- required, seconds
}
-- playback
{
    elapsed = 42.5,        -- seconds into the track
    paused = false,
}
```

A malformed track or playback counts as nothing playing. Elapsed time between polls is interpolated for you, so a 1 second interval still gives a smooth progress bar.

**`setLyrics(fn)`**: `fn(track)` receives the current `MusicTrack` and returns a list of `{ time, text }` lines (`time` is the second the line starts at), or `nil` to fall back to the built-in lookup for that track. Called once per track, only while lyrics are enabled in the menu.

### Music HUD examples

```luau theme={null}
-- Show the playing song in a notification
api.feature.musichud.onTrackChanged:Connect(function(track)
    if track then
        api.ui.notify({ title = track.title, subtext = track.artist, duration = 3 })
    end
end)

-- Feed the HUD from your own player
api.feature.musichud.setSource({
    name = "My Player",
    interval = 2,
    poll = function()
        local state = getMyPlayerState()
        if not state then
            return nil
        end
        return {
            title = state.title,
            artist = state.artist,
            duration = state.duration,
            coverUrl = state.artUrl,
        }, {
            elapsed = state.position,
            paused = state.paused,
        }
    end,
})

-- Serve lyrics from your own files
api.feature.musichud.setLyrics(function(track)
    local lrc = findMyLyrics(track.title, track.artist)
    if not lrc then
        return nil
    end
    return lrc -- { { time = 12.4, text = "..." }, ... }
end)
```

## Auto Peek

`api.feature.autopeek` — **Bloxstrike, Rivals, Overkill, and Murderers vs Sheriffs Duels.** Drive the Auto Peek feature from your own conditions instead of the menu toggle. Save a spot, then return to it whenever you decide.

This runs alongside the menu toggle: your saved spot and the toggle's are the same one, so turning the menu toggle on still works normally. Only present where the feature exists, so guard with `if api.feature.autopeek then ... end`.

| Call             | Returns   | What it does                                                                                                      |
| ---------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `save()`         | `boolean` | Save your current position as the peek spot and show the marker. Returns `false` if you have no character.        |
| `retreat()`      |           | Return to the saved spot now, using the menu's retreat method (teleport or walk) and respecting its max distance. |
| `clear()`        |           | Drop the saved spot and hide the marker (unless the menu toggle is holding it).                                   |
| `isPeeking()`    | `boolean` | Whether a spot is currently saved.                                                                                |
| `isRetreating()` | `boolean` | Whether a walk-back is in progress.                                                                               |

### Auto Peek example

```luau theme={null}
-- Peek off your own key, retreat after a short delay
local savedKey = api.ui.tab("Peek", "target"):AddSection("Peek", 1):AddKey("peekKey", "Peek Key")
savedKey:OnCallback(function()
    api.feature.autopeek.save()
    task.delay(0.4, api.feature.autopeek.retreat)
end)
```

## Anti Aim

`api.feature.antiaim` — **Bloxstrike.** Set the direction other players see you facing, directly. Setting a yaw or pitch turns anti aim on even when the menu toggle is off, and it stays on until you clear both or your script unloads.

Your values win over everything: the menu Yaw / Pitch modes, freestanding, avoid backstab, and round end anti aim.

| Call              | Returns           | What it does                                                                                                      |
| ----------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------- |
| `setYaw(yaw)`     |                   | Sets the yaw others see, in world radians. Pass `nil` to go back to the menu behavior.                            |
| `setPitch(pitch)` |                   | Sets the pitch others see, `-1` (straight down) to `1` (straight up). Pass `nil` to go back to the menu behavior. |
| `getYaw()`        | `number?`         | The yaw you set, or `nil` if none.                                                                                |
| `getPitch()`      | `number?`         | The pitch you set, or `nil` if none.                                                                              |
| `getAngles()`     | `{ yaw, pitch }?` | The yaw and pitch anti aim is applying right now (after anything you set). `nil` while anti aim is off.           |
| `clear()`         |                   | Removes the yaw and pitch you set.                                                                                |
| `isEnabled()`     | `boolean`         | Whether the menu Anti Aim toggle is on.                                                                           |
| `isActive()`      | `boolean`         | Whether anti aim is applying right now (toggle, round end, or the values you set).                                |

Yaw uses the same convention as the camera: `select(2, workspace.CurrentCamera.CFrame:ToEulerAnglesYXZ())` is the yaw you are looking at. To face a world direction, use `math.atan2(-direction.X, -direction.Z)`.

You can set an axis on its own. With only a pitch set, your yaw follows your real view, and the other way around.

Anything you set clears automatically when your script unloads.

### Anti Aim examples

```luau theme={null}
-- Spin, dip the pitch, stop after 3 seconds
local aa = api.feature.antiaim
local spin = task.spawn(function()
    aa.setPitch(-1)
    while true do
        aa.setYaw(os.clock() * 8 % (math.pi * 2))
        task.wait()
    end
end)
task.delay(3, function()
    task.cancel(spin)
    aa.clear()
end)
```

```luau theme={null}
-- Always face the player closest to you
local aa = api.feature.antiaim
local RunService = game:GetService("RunService")
api.utility.connect(RunService.Heartbeat, function()
    local me = api.client.getPosition()
    if not me then
        return
    end
    local dir, best = nil, math.huge
    for _, player in api.players.getAll() do
        local handle = api.players.get(player)
        local pos = handle and handle:getPosition()
        if pos then
            local dist = (pos - me).Magnitude
            if dist < best then
                best, dir = dist, pos - me
            end
        end
    end
    if dir then
        aa.setYaw(math.atan2(-dir.X, -dir.Z))
    end
end)
```

<CardGroup cols={2}>
  <Card title="Types" icon="brackets-curly" href="/reference/types#autoloot-types">
    AutoLootItem, AutoLootAction, AutoLootHandle, MusicTrack, MusicPlayback, MusicLyric.
  </Card>
</CardGroup>