> For the complete documentation index, see [llms.txt](https://fivezone.gitbook.io/fivezone-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fivezone.gitbook.io/fivezone-docs/paid-products/script-npc-manager.md).
# \[SCRIPT] NPC MANAGER
#### INFORMATIONS
*Place, pose and dress NPCs from an in-game menu - with a live ped preview, free-cam placement and one-click cloning of your own character. Runs on ESX, Qbox, QBCore and standalone, detected automatically.*
***
#### COMPATIBILITY
| | |
| ---------------- | --------------------------------------- |
| **Version** | 2.0.0 |
| **Frameworks** | ESX Legacy · Qbox · QBCore · standalone |
| **Detection** | Automatic - nothing to configure |
| **Requirements** | `oxmysql` + MySQL / MariaDB |
| **Optional** | `ox_lib` for nicer notifications |
| **Languages** | English & Czech, easy to add more |
| **Open files** | `config.lua`, `locales/*.lua`, `html/*` |
***
#### FEATURES
* **Live ped preview** - a real ped spawns next to the menu with the exact model, outfit and animation you are editing
* **Clone your own character** - model, all clothing, props, hair, face and eye colour in one click
* **Free-cam placement** - fly with WASD and drop the NPC exactly where you look (raycast based, works on stairs and rooftops)
* **Scenarios & animations with instant playback** - click ▶ and the preview ped plays it right away
* **Categories & bulk actions** - your own folders, right-click menu, multi-select move and delete
* **Full appearance editing** - 10 clothing components including decals / rank insignia, 5 props, head blend, hair, beard, eyebrows
* **Distance culling** - NPCs spawn and despawn by distance, spread over several frames so busy areas do not hitch
* **Import & export** - full JSON backup and restore
* **Server-side permission checks** - ACE permission + framework groups
* **Automatic database migrations** - upgrading never needs a manual `ALTER TABLE`
***
#### INSTALLATION
1. Extract the downloaded file into your `resources` folder and rename it from **\[PedSpawner\_fvz 2.0.0]** -> **\[PedSpawner\_fvz]**
2. Import `sql/npc_manager.sql` into your database
3. Go in `config.lua` and change it to your liking
4. Go in `server.cfg` and add the lines from the code block below
5. Save everything and restart the server. You are done! **Enjoy** :)
```cfg
ensure oxmysql
ensure PedSpawner_fvz
add_ace group.admin npc.admin allow
```
Make sure `PedSpawner_fvz` starts **after** `oxmysql` and after your framework. On start the console tells you what was detected:
```
[NPC Manager] Framework: qbox
[NPC Manager] Server started successfully!
```
Open the menu with **F6** or `/npcmenu`.
{% hint style="warning" %}
Do not rename the resource folder to anything else - the interface and the export both reference it by name.
{% endhint %}
{% hint style="success" %}
Upgrading from an older version? Nothing to run by hand. The script checks its own table on start and adds any missing columns automatically.
{% endhint %}
***
#### CONFIGURATION
Everything below is in `config.lua`, which stays open and editable even under escrow.
| Parameter | Description |
| -------------------------------------- | --------------------------------------------------------------- |
| `Locale` | Interface language - `'en'` or `'cs'` |
| `Framework` | `'auto'`, or force `'esx'` / `'qbox'` / `'qb'` / `'standalone'` |
| `NotifySystem` | `'auto'` / `'ox'` / `'esx'` / `'qb'` / `'native'` |
| `AdminPermission` | ACE permission needed to open the menu (default `npc.admin`) |
| `UseFrameworkGroups` | Also allow ESX / Qbox / QBCore groups |
| `AllowedGroups` | Which groups those are (default `admin`, `superadmin`, `god`) |
| `MenuKey` / `MenuCommand` | Keybind and chat command (default `F6` / `npcmenu`) |
| `UnstuckCommand` | Emergency command that returns mouse control (default `npcfix`) |
| `RenderDistance` | NPCs within this distance are spawned (default `150.0`) |
| `DeleteDistance` | NPCs beyond this distance are removed (default `200.0`) |
| `MaxSpawnsPerTick` | How many NPCs may spawn per batch - anti-lag (default `3`) |
| `Preview` | The ped next to the menu - distance, transparency, camera FOV |
| `Placement` | Free-cam speed, rotation step, height step, raycast distance |
| `Highlight` | Marker ring shown while placing |
| `PedModels` | The model list in the menu - add your own addon peds here |
| `Scenarios` / `Animations` / `Weapons` | The lists shown in the editor |
| `Notify` | Hook to route notifications through your own system |
**Performance tuning**
On a busy server, lower the spawn budget instead of only the render distance:
```lua
Config.RenderDistance = 100.0
Config.DeleteDistance = 150.0
Config.MaxSpawnsPerTick = 2
Config.CullingInterval = 2000
```
{% hint style="info" %}
Always keep a gap between `RenderDistance` and `DeleteDistance`. Without it, an NPC sitting exactly on the boundary would spawn and despawn on every check.
{% endhint %}
**Adding your own peds**
```lua
Config.PedModels = {
{ label = "My addon ped", value = "my_custom_ped", category = "Custom" },
}
```
Every model is validated against the game when the menu opens. Anything the client does not have is hidden from the list and logged to the console instead of failing at spawn time - so listing addon peds is always safe.
You can also type any model name or hash straight into **Custom model** in the menu, without touching the config at all.
***
#### HOW TO USE
Press **F6**. The list of saved NPCs is on the left, the editor in the middle, and the live preview ped on the right.
Click **New NPC** and work through the four tabs:
**BASICS**
Name, identifier, category, ped model and position. **My position** takes your current coordinates, **Place in world** opens placement mode.
**APPEARANCE**
**Copy my character** clones your model, all 12 clothing components, 5 props, head blend, hair, beard, eyebrows and eye colour in one click. Then switch to **Manual editing** to fine-tune - your cloned character loads into the fields, so you can change just the rank insignia (component 10) or add a bag (component 5).
{% hint style="info" %}
Detailed customisation only works on `mp_m_freemode_01` and `mp_f_freemode_01`. Story-mode peds have their look baked in - the tab tells you instead of showing fields that would do nothing.
{% endhint %}
**ANIMATION**
Pick a scenario or an animation, or type your own dictionary and clip. Every entry has a **▶** button that plays it on the preview ped immediately - no saving, no restarting.
**BEHAVIOUR**
| Option | Default | Effect |
| ---------------- | ------- | -------------------------------- |
| **Invincible** | on | the NPC cannot be killed or hurt |
| **Frozen** | on | stays exactly where you put it |
| **Block events** | on | ignores gunfire, cars and panic |
| **Armed** | off | gives the NPC a weapon in hand |
| **Hostile** | off | attacks nearby players |
***
**PLACEMENT MODE**
| Key | Action |
| -------------------- | ------------------- |
| **W A S D** | fly |
| **Space** / **Ctrl** | up / down |
| **Shift** | fly faster |
| **Mouse wheel** | rotate the NPC |
| **PgUp** / **PgDn** | fine-tune height |
| **G** | reset height offset |
| **ENTER** | confirm |
| **BACKSPACE** | cancel |
The position comes from a raycast, so it works on stairs, rooftops and props - not just flat ground. Your character is locked while you place, so nothing fights your input.
***
**CATEGORIES & BULK ACTIONS**
Type a name into the **Category** field and it exists - no separate step. The list groups into collapsible sections and remembers what you had open.
**Right-click any NPC** for Edit · Teleport · Duplicate · Select · Move to · Delete. Right-click a **category header** to apply the same to every NPC in it.
| Shortcut | Action |
| ---------------- | -------------------------------------- |
| **Ctrl + click** | add / remove from selection |
| **Ctrl + A** | select everything matching your search |
| **Esc** | clear the selection |
{% hint style="danger" %}
Bulk delete is permanent - there is no undo. Hit **Export** first, it takes two clicks and gives you a file you can restore from.
{% endhint %}
***
#### LANGUAGES
The script ships with **English** and **Czech**. Switching is one line:
```lua
Config.Locale = 'en' -- 'en' | 'cs'
```
Adding your own language is copying one file:
1. Copy `locales/en.lua` to `locales/de.lua`
2. Change `Locales['en']` to `Locales['de']` at the top
3. Translate the values - leave the keys alone
4. Set `Config.Locale = 'de'` and restart
{% hint style="success" %}
No manifest editing. The manifest loads `locales/*.lua` with a glob, so a new file is picked up on its own. Missing keys fall back to English instead of breaking, so a half-finished translation is still usable.
{% endhint %}
***
#### API (EXPORT)
Server-side. Returns the full database row for an NPC, or `nil`.
```lua
local npc = exports['PedSpawner_fvz']:getNPCDetails(4)
if npc then
print(npc.name, npc.ped_model, npc.coords_x, npc.coords_y, npc.coords_z)
end
```
Useful for tying your own script to an NPC - a shop at the clerk, a job point at the foreman, a mission trigger at a guard.
***
#### TROUBLESHOOTING
My mouse is stuck / I cannot move
Type `/npcfix`. Control comes back instantly.
There are three independent safety nets against this - a watchdog that releases focus if the interface stops responding, a release on resource stop, and this command. You should never need it, but it is there.
The menu does not open
1. **Permissions** - the most common cause. Check that `add_ace group.admin npc.admin allow` is in `server.cfg`.
2. **Is the resource started?** Look for errors in the console on start.
3. **The keybind** - `F6` is a keymapping, another resource may have taken it. Try `/npcmenu`; if the command works and the key does not, it is a binding conflict.
Table 'npc_manager' does not exist
The SQL file was not imported. Import `sql/npc_manager.sql` and restart.
Framework is detected as standalone
Your framework either starts **after** NPC Manager, or the resource has a non-standard name. Fix the order in `server.cfg`, or force it:
```lua
Config.Framework = 'esx'
```
Standalone still works fully - you just get ACE permissions only.
NPCs do not appear
* Are you within `Config.RenderDistance` (default 150 units)?
* Does the client have the model? Models the game does not know are listed in the console when the menu opens.
* Does the header show a total above 0? If it shows 0, nothing is saved yet.
A custom animation does nothing
Almost always a wrong dictionary name. Dictionary names are **lowercase**, and the clip has to belong to that dictionary. Use the **▶** button to test before saving - a typo shows up in seconds instead of after a restart.
A sitting NPC floats or sinks into the ground
Scenarios like `PROP_HUMAN_SEAT_BENCH` position the ped relative to where the seat would be, not relative to the ground. Place the NPC where the seat actually is and use **PgUp** / **PgDn** to fine-tune the height.
Busy areas stutter
Lower the spawn budget - see **Performance tuning** above. NPCs will appear slightly later, but smoothly.
{% hint style="info" %}
Still stuck? Set `Config.Debug = true` and restart the resource. Every spawn, cull, appearance step and framework call is printed to the client console (F8). Most problems name themselves in the first few lines. Turn it back off afterwards - it is deliberately loud.
{% endhint %}
***
#### LINKS
{% embed url="" %}
{% embed url="" %}
{% embed url="" %}
