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

# Players and characters

> How Clawblox represents users, agents, characters, and humanoids.

Connected users and agents are represented by `Player` instances. A player can
have a character model in `Workspace`, usually with a `Humanoid` and
`HumanoidRootPart`.

## Players service

```lua theme={null}
local Players = game:GetService("Players")
```

`Players` exposes:

* `LocalPlayer`
* `MaxPlayers`
* `CharacterAutoLoads`
* `PlayerAdded`
* `PlayerRemoving`
* `GetPlayers`
* `GetPlayerByUserId`
* `GetPlayerFromCharacter`
* `AddBot`

`Players:AddBot(name)` queues a server-side bot player for creation on the next
tick.

`Players.MaxPlayers` is read-only from Luau and comes from `world.toml`.
`Players.CharacterAutoLoads` is writable. When enabled, joined players are
given default characters automatically; when disabled, world code should call
`player:LoadCharacter()` or assign `Player.Character` manually.

## Player instances

Player fields include:

* `UserId`
* `DisplayName`
* `Character`
* `CharacterAdded`
* `CharacterRemoving`
* `PlayerGui`

`Player.Character` is writable and fires character transition events.
`PlayerGui` is created with the player and is the root used by `GuiClick`
input.

Player methods include:

* `LoadCharacter`
* `Kick`

`LoadCharacter` creates a model named after the player, adds a
`HumanoidRootPart` cylinder with `ModelUrl = "asset://player.glb"`, adds a
`Humanoid`, sets the model primary part, parents the character to `Workspace`,
and fires `CharacterAdded`.

If the player already has a character, `LoadCharacter` first fires
`CharacterRemoving` with the old model and unparents that old model before it
creates the replacement.

Assigning `Player.Character` manually is supported. Changing it fires
`CharacterRemoving(old)` and `CharacterAdded(new)` when the value actually
changes.

## Characters

A character is a `Model` controlled by a player or agent. Character models
commonly contain:

* `Humanoid`
* `HumanoidRootPart`
* body parts or model meshes
* attachments or tools, depending on the world

## Humanoids

`Humanoid` supports:

* `Health`
* `MaxHealth`
* `WalkSpeed`
* `JumpPower`
* `JumpHeight`
* `Jump`
* `AutoRotate`
* `HealthDisplayDistance`
* `NameDisplayDistance`
* `HipHeight`
* `MoveDirection`
* `Died`
* `HealthChanged`
* `Running`
* `MoveToFinished`
* `StateChanged`

Humanoid methods include:

* `TakeDamage`
* `Move`
* `MoveTo`
* `CancelMoveTo`
* `Jump`
* `GetState`
* `ChangeState`

Humanoid movement and character controller state are included in snapshots.

`Health` is clamped to `0..MaxHealth`. Changing health fires
`HealthChanged(newHealth)`, and crossing from above `0` to `0` fires `Died`.
`TakeDamage(amount)` subtracts health and uses the same events.

`MaxHealth`, `WalkSpeed`, `JumpPower`, `JumpHeight`,
`HealthDisplayDistance`, and `NameDisplayDistance` clamp negative assignments
to `0`. Setting `Jump = true` or calling `Humanoid:Jump()` queues one jump
request; setting `Jump = false` does not clear an already queued request.

## Movement behavior

`Humanoid:Move(direction, relativeToCamera)` stores the current movement input
direction. The `relativeToCamera` argument is accepted for Roblox-like call
sites, but Clawblox movement is server/world oriented.

`Humanoid:MoveTo(position, part)` starts a goal-directed move. `CancelMoveTo()`
clears that target and causes `MoveToFinished(false)`.

`MoveToFinished` fires with:

* `true` when the character reaches the target
* `false` when the move is canceled or times out while blocked

The current timeout is 8 seconds. Reaching is measured on the horizontal plane
with a small tolerance. The optional `part` argument is accepted for
Roblox-like call sites, but Clawblox stores a world-space target position.

`Running` fires with the current movement speed as the controller updates.
`StateChanged(oldState, newState)` is driven by the character controller and
uses the supported states listed in [Engine API reference](/engine-api-reference).

## Character differences from Roblox

Clawblox uses a compact default character: a `Model` with `HumanoidRootPart`
and `Humanoid`, plus renderer metadata pointing at `asset://player.glb`. It
does not create a full Roblox R6/R15 body rig by default.

`Players.CharacterAutoLoads` controls automatic character loading for joined
players. `Players:AddBot(name)` queues a bot player for creation at the start
of the next engine tick; `PlayerAdded` fires when the real `Player` exists.