> ## 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.

# Shared

> PlayerHandle methods and player signals that work in every game.

Get a handle from [api.players.get(player)](/players/overview), then call its methods with `:` syntax. Every call reads the latest value. These are there in every game that has `api.players`.

## Handle methods

| Method                                                   | Returns                  | What it tells you                                                                                                                                                                                                                               |
| -------------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getPlayer()`                                            | `Player`                 | The `Player` instance this handle is for.                                                                                                                                                                                                       |
| `getCharacter()`                                         | `Model?`                 | Their character model. `nil` while dead or respawning.                                                                                                                                                                                          |
| `getHumanoid()`                                          | `Humanoid?`              | Their Humanoid. `nil` while dead.                                                                                                                                                                                                               |
| `getRootPart()`                                          | `BasePart?`              | Their `HumanoidRootPart`. `nil` while dead.                                                                                                                                                                                                     |
| `getParts()`                                             | `{ [string]: Instance }` | Name → part table of their character.                                                                                                                                                                                                           |
| `isAlive()`                                              | `boolean`                | Whether they're currently alive.                                                                                                                                                                                                                |
| `getTeam()`                                              | `string?`                | Their team (game-specific string format).                                                                                                                                                                                                       |
| `getHealth()` / `getMaxHealth()` / `getHealthFraction()` | `number`                 | Their HP, max HP, and `0..1` fraction.                                                                                                                                                                                                          |
| `getPosition()`                                          | `Vector3?`               | Where they are in the world.                                                                                                                                                                                                                    |
| `getCFrame()`                                            | `CFrame?`                | Their root part's CFrame.                                                                                                                                                                                                                       |
| `getWeapon()`                                            | `any?`                   | What they're holding right now.                                                                                                                                                                                                                 |
| `getItemName()`                                          | `string?`                | The name of what they're holding.                                                                                                                                                                                                               |
| `isReloading()`                                          | `boolean`                | `true` while reloading.                                                                                                                                                                                                                         |
| `isBlind()`                                              | `boolean`                | `true` while blinded.                                                                                                                                                                                                                           |
| `isScoped()`                                             | `boolean`                | `true` while scoped in.                                                                                                                                                                                                                         |
| `getState()`                                             | `string?`                | The state assigned to them: `"friendly"`, `"priority"`, or `nil`. Aim assists skip `friendly` and prefer `priority`.                                                                                                                            |
| `setState(state?)`                                       |                          | Assign a state to them (`"friendly"`, `"priority"`, or any state id from `api.players.getStates()`). Pass `nil` to clear. Same effect as assigning it in the record menu: aim assists and ESP react immediately. Errors on an unknown state id. |

## State helpers

These live on `api.players` itself, not on a handle.

| Call             | Returns             | What it does                                                                                                                                    |
| ---------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `getStates()`    | `{ { id, label } }` | The available states.                                                                                                                           |
| `onStateChanged` | Signal              | `(player, state)`: a player's state was assigned or cleared (`state` is the new id, or `nil`). Fires for menu assignments and `setState` alike. |

## Signals

Call `:Connect(callback)` on these. Your callback always gets `player` first, so one callback can handle everyone; filter inside if you only care about one. They get cleaned up when your script unloads.

| Signal                | Your callback receives                           |
| --------------------- | ------------------------------------------------ |
| `onPlayerAdded`       | `(player)`: someone joined the match             |
| `onPlayerRemoving`    | `(player)`: someone left                         |
| `onCharacterAdded`    | `(player, character)`: they spawned in           |
| `onCharacterRemoving` | `(player, character)`: right before they despawn |
| `onSpawn`             | `(player)`: they came alive                      |
| `onDeath`             | `(player)`: they died                            |
| `onTeamChanged`       | `(player, team)`                                 |
| `onHealthChanged`     | `(player, health, maxHealth)`                    |
| `onWeaponChanged`     | `(player, weapon)`                               |
| `onReloadingChanged`  | `(player, reloading)`                            |
| `onBlindChanged`      | `(player, blind)`                                |
| `onScopedChanged`     | `(player, scoped)`                               |

## Example

```luau theme={null}
api.players.onReloadingChanged:Connect(function(player, reloading)
    if reloading then
        print(player.Name, "is reloading")
    end
end)
```