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

> Local-player getters and signals that work in every game.

These are there in every game Limerence supports. Anything that needs a living character comes back as `nil` or `0` while you're dead or respawning.

One exception: in Phantom Forces and Overkill, `api.client` exposes only the `onHit` / `onKill` signals below — none of the getters or other signals.

## Getters

| Call                  | Returns                  | What it tells you                                                                                                       |
| --------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `getPlayer()`         | `Player`                 | Your `Players.LocalPlayer`. Always the same value.                                                                      |
| `getCharacter()`      | `Model?`                 | Your character model. `nil` while dead or respawning.                                                                   |
| `getHumanoid()`       | `Humanoid?`              | Your Humanoid. `nil` while dead.                                                                                        |
| `getRootPart()`       | `BasePart?`              | Your `HumanoidRootPart`. `nil` while dead.                                                                              |
| `getParts()`          | `{ [string]: Instance }` | A name → part table of every child of your character (e.g. `Head`, `LeftArm`).                                          |
| `isAlive()`           | `boolean`                | Whether you're currently alive.                                                                                         |
| `isSpectating()`      | `boolean`                | Whether you're in spectator mode.                                                                                       |
| `getTeam()`           | `string?`                | Your team. The string format is game-specific (Bloxstrike: `"Terrorists"` / `"Counter-Terrorists"`; Rivals: a team id). |
| `getHealth()`         | `number`                 | Current HP. `0` if dead.                                                                                                |
| `getMaxHealth()`      | `number`                 | Maximum HP. `100` if you don't have a humanoid.                                                                         |
| `getHealthFraction()` | `number`                 | HP as a fraction from `0` to `1`.                                                                                       |
| `getPosition()`       | `Vector3?`               | Where your root part is in the world.                                                                                   |
| `getCFrame()`         | `CFrame?`                | Your root part's CFrame (position + rotation).                                                                          |
| `getVelocity()`       | `Vector3`                | Your current velocity. Zero while dead.                                                                                 |
| `getItemName()`       | `string?`                | Name of what you're holding (weapon, melee, consumable). `nil` when empty-handed.                                       |

## Signals

Call `:Connect(callback)` on these. They get cleaned up when your script unloads.

| Signal                | Your callback receives                  |
| --------------------- | --------------------------------------- |
| `onCharacterAdded`    | `(character)`: when you spawn in        |
| `onCharacterRemoving` | `(character)`: right before you despawn |
| `onSpawn`             | `()`: when you come alive               |
| `onDeath`             | `()`: when you die                      |
| `onTeamChanged`       | `(team)`: when you change teams         |
| `onHealthChanged`     | `(health, maxHealth)`: any HP change    |

## Your hits and kills

Fire when you damage or eliminate another player. These two signals also exist in Phantom Forces and Overkill, where they are the only things on `api.client`.

| Signal   | Games          | Your callback receives            |
| -------- | -------------- | --------------------------------- |
| `onHit`  | All            | `(hit)`: you damaged someone.     |
| `onKill` | All except AR2 | `(kill)`: you eliminated someone. |

The `hit` table (fields are `nil` where the game doesn't report them):

```luau theme={null}
{
    player = victim,       -- always set
    part = somePart,       -- Bloxstrike, AR2, Phantom Forces
    partName = "Head",     -- everywhere except Rivals
    position = Vector3,    -- AR2, Phantom Forces, Overkill
    damage = 34,           -- AR2, Phantom Forces, Overkill
    headshot = true,       -- always set
}
```

The `kill` table: `{ player, position?, headshot? }` (`position` in Bloxstrike and Phantom Forces, `headshot` in Overkill).

```luau theme={null}
-- Kill feed pill
api.client.onKill:Connect(function(kill)
    api.ui.toast(`Eliminated {kill.player.Name}`)
end)

-- Headshot damage tracker
api.client.onHit:Connect(function(hit)
    if hit.headshot then
        print("headshot on", hit.player.Name, hit.damage)
    end
end)
```

## Example

```luau theme={null}
api.client.onDeath:Connect(function()
    print("died at", api.client.getPosition())
end)

-- Heartbeat is a Roblox signal, so use api.utility.connect for auto-cleanup
api.utility.connect(game:GetService("RunService").Heartbeat, function()
    if not api.client.isAlive() then return end
    local hp = api.client.getHealthFraction()
    -- update HUD...
end)
```