# Ambient NPC

Manage and spawn custom ambient NPCs (PNJ) for your RedM server, both client-side and server-side.

***

### ⚡ Getting Started

By default, everything is already set up in `config.lua`.\
If you want to customize the NPC system integration, you can remove lines 3–11 in your `config.lua` and use your own logic.

**Start the system:**

```lua
TriggerEvent("Botiv:startPNJSystem")
```

***

### 🟦 Client Side

#### Add an NPC (Event)

Create and spawn a new NPC using:

```lua
TriggerEvent("Botiv-publicnpc:insertNewNPC", "boss-1", {
    model = "a_m_m_sddockworkers_02",
    coords = { x = -803.6, y = -1292.98, z = 42.63 },
    heading = 60.62,
    anim = "WORLD_HUMAN_SIT_GROUND_READ_NEWSPAPER",
    distance = 50.0,
    dontreact = true,
    walking = false,
    walking_distance = 20.0,
    weapon = ""
})
```

#### Get an NPC Entity (Export)

Retrieve the entity number of a given NPC (from your config or dynamic event):

```lua
luaCopierModifierlocal npcEntity = exports.bt_publicnpc:getNPCEntity("paper-1")
```

* **Returns:** The entity ID for `"paper-1"` or `0` if not loaded (player too far).

**Example:**

```lua
Citizen.CreateThread(function()
    while true do
        Citizen.Wait(100)
        local botNPC = exports.bt_publicnpc:getNPCEntity("paper-1")
        if DoesEntityExist(botNPC) then
            if #(GetEntityCoords(PlayerPedId()) - GetEntityCoords(botNPC)) < 5.0 then
                SetPedScale(botNPC, 2.0)
            else
                SetPedScale(botNPC, 1.0)
            end
        end
    end
end)
```

***

### 🟧 Server Side

#### Insert NPC (Server Event)

To instruct a client to spawn a new NPC from the server:

```lua
TriggerClientEvent("Botiv-publicnpc:insertNewNPC", source, "boss-1", {
    model = "a_m_m_sddockworkers_02",
    coords = { x = -803.6, y = -1292.98, z = 42.63 },
    heading = 60.62,
    anim = "WORLD_HUMAN_SIT_GROUND_READ_NEWSPAPER",
    distance = 50.0,
    dontreact = true,
    walking = false,
    walking_distance = 20.0,
    weapon = ""
})
```

***

### ⚙️ NPC Configuration Example

Here’s a sample from your `config.lua`:

```lua
Config.PNJ = {
    ["paper-1"] = { -- PAPERBOY
        model = "S_M_Y_NewspaperBoy_01",
        coords = { x = -793.6 , y = -1292.98 , z = 42.63 },
        heading = 79.56,
        anim = "WORLD_HUMAN_SIT_GROUND_READ_NEWSPAPER",
        distance = 50.0,
        dontreact = true,
        walking = true,
        walking_distance = 10.0,
        weapon = ""
    },
    -- Add more NPC configs here...
}
```

**Key fields:**

* `model` : Model name of the NPC
* `coords` : Position (x, y, z)
* `heading` : Direction the NPC is facing
* `anim` : Animation or scenario
* `distance` : Distance from which NPC is loaded
* `dontreact` : NPC ignores world events
* `walking` : NPC will walk around (boolean)
* `walking_distance` : How far the NPC will walk
* `weapon` : Weapon (if any) to give to the NPC

***

### 📌 Notes

* If `getNPCEntity()` returns `0`, the NPC isn't loaded for the player (usually too far away).
* NPCs can be managed both through config and at runtime using events/exports.


---

# 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://botiv.gitbook.io/rdr2/ambient-npc.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.