# Player

Provides utility functions for retrieving player information, directional logic, entity targeting, animations, and more.

***

## Accessing the Module

```lua
local PLAYER <const> = exports.boii_utils:get("modules.player")
```

***

## Shared

### get\_cardinal\_direction(player\_ped)

Returns the cardinal direction the player is facing.

#### Parameters

| Name        | Type     | Description                                                    |
| ----------- | -------- | -------------------------------------------------------------- |
| player\_ped | `number` | The player ped (use `PlayerPedId()` or `GetPlayerPed(source)`) |

#### Example

```lua
local dir = PLAYER.get_cardinal_direction(PlayerPedId())
```

***

### get\_distance\_to\_entity(player, entity)

Calculates the distance between a player and another entity.

#### Parameters

| Name   | Type     | Description                   |
| ------ | -------- | ----------------------------- |
| player | `number` | The player entity             |
| entity | `number` | The target entity (or net ID) |

#### Example

```lua
local dist = PLAYER.get_distance_to_entity(PlayerPedId(), entity)
```

***

## Client

### get\_street\_name(player\_ped)

Gets the current street and area the player is in.

#### Parameters

| Name        | Type     | Description    |
| ----------- | -------- | -------------- |
| player\_ped | `number` | The player ped |

#### Example

```lua
local location = PLAYER.get_street_name(PlayerPedId())
```

***

### get\_region(player\_ped)

Returns the name of the region the player is located in.

#### Parameters

| Name        | Type     | Description    |
| ----------- | -------- | -------------- |
| player\_ped | `number` | The player ped |

#### Example

```lua
local region = PLAYER.get_region(PlayerPedId())
```

***

### get\_player\_details(player\_ped)

Returns a table with extended player stats and data.

#### Parameters

| Name        | Type     | Description    |
| ----------- | -------- | -------------- |
| player\_ped | `number` | The player ped |

#### Example

```lua
local details = PLAYER.get_player_details(PlayerPedId())
```

***

### get\_target\_entity(player\_ped)

Returns the entity a player is currently aiming at.

#### Parameters

| Name        | Type     | Description    |
| ----------- | -------- | -------------- |
| player\_ped | `number` | The player ped |

#### Example

```lua
local target = PLAYER.get_target_entity(PlayerPedId())
```

***

### play\_animation(player\_ped, options, callback)

Plays an animation with optional props and visual progress.

#### Parameters

| Name        | Type       | Description                     |
| ----------- | ---------- | ------------------------------- |
| player\_ped | `number`   | The player ped                  |
| options     | `table`    | Animation and prop options      |
| callback    | `function` | Function called after animation |

#### Example

```lua
PLAYER.play_animation(PlayerPedId(), {
    dict = 'anim@heists@ornate_bank@grab_cash',
    anim = 'grab',
    flags = 49,
    duration = 3000,
    freeze = true,
    props = {
        {
            model = 'prop_cs_burger_01',
            bone = 57005,
            coords = vector3(0.1, 0.0, 0.0),
            rotation = vector3(0.0, 0.0, 0.0),
            is_ped = true
        }
    }
}, function()
    print('Animation completed.')
end)
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.boii.dev/old-docs/boii_utils/api/player.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.