> For the complete documentation index, see [llms.txt](https://botiv.gitbook.io/rdr2/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://botiv.gitbook.io/rdr2/ambient-npc.md).

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