Skip to content

Installation

1. Dependencies

Make sure these are installed and started before the ped spawner:

  • vns-core - separate free download from your Keymaster/cfx Portal. It is not included in the script's zip.
  • ox_lib
  • Your framework: qb-core, qbx_core or es_extended
  • A target system (ox_target, qb-target or qtarget) if you want target actions on your peds

The UI is pre-built and shipped in html/build. You do not need to run npm or build anything. There is no database.

2. Resource

Copy vns-pedspawner into your resources and add it to server.cfg after vns-core:

ensure ox_lib
ensure oxmysql
# your framework and target system

ensure vns-core
ensure vns-pedspawner

Ensure order

  • vns-core must be ensured after ox_lib, oxmysql (database), your framework, inventory, target system and your other server scripts such as housing, garages and phone.
  • vns-pedspawner must be ensured after vns-core.

If vns-core starts too early, VNS scripts can't use your database, items, money or other systems. See Installing vns-core.

Folder name

Keep the folder named vns-pedspawner. The UI calls its NUI endpoints under that resource name and will not work if you rename it.

3. Permissions

The UI opens with the /pedspawner command (change it via Config.Command). Permissions are enabled by default:

Config.Permission = {
    enabled = true,
    allowedIdentifiers = {
        'steam:110000112345678',
        'license:0123456789abcdef',
    },
}

With enabled = true, a player is allowed if either of these is true:

  • Admin ace - IsPlayerAceAllowed passes for vns-core's Config.AdminAce (command by default, which FiveM's standard server.cfg already grants to group.admin). See vns-core admin permissions:

    add_ace group.admin command allow
add_principal identifier.license:xxxxxxxx group.admin

  • Identifier - one of their identifiers (steam:, license:, discord:, fivem:, ...) or their framework character identifier (citizenid on QBCore/QBox, identifier on ESX) is listed in allowedIdentifiers.

Replace the two example identifiers with your own, or clear the list if you only use the ace.

The same check runs on the server when the UI is opened and whenever peds are saved, edited or deleted, so a player without access can't change peds by triggering the events directly. Players without access who run the command get a message in their F8 console.

Warning

Setting enabled = false lets every player open the ped spawner and place or delete peds.

To change the logic, edit HasPedSpawnerPermission(src) in server/server_open.lua (editable in both versions).

4. Target system

Config.Target = 'auto' -- 'auto' or 'none'

With 'auto', target actions are registered through vns-core on whichever target resource your server runs. With 'none', peds still spawn and animate, but no interactions are registered.

5. First start

  1. Start the server, join, and run /pedspawner.
  2. Add a test ped with Use My Position and save. It should appear instantly.
  3. Restart the resource and confirm the ped comes back (it is stored in peds.json inside the resource folder).

Back up peds.json

All placed peds live in peds.json in the resource folder. Include it in your backups, and keep it when updating the script.

Updating from the previous version

  • vns-core is now required. Download it separately from your portal and start it before vns-pedspawner.
  • Keep your peds.json. Copy it into the new resource folder before starting it. The file format is unchanged.
  • Permissions are now on by default (Config.Permission.enabled = true). Make sure your staff have the admin ace or are listed in allowedIdentifiers, or nobody can open the UI.
  • allowedGroups was removed. Framework groups and jobs no longer grant access. Use the vns-core admin ace or allowedIdentifiers instead. allowedIdentifiers now also accepts the framework character identifier.
  • Saving and deleting are checked server-side. Previously only opening the UI was checked.
  • Config.Target values changed. 'qb-target' / 'ox_target' are replaced by 'auto' (vns-core picks the running target system, including qtarget) or 'none'.
  • Action events now get the same arguments on every target system: (entity, distance, data). See Configuration.
  • New file layout: client.lua / server.lua were replaced by client/client_open.lua, client/client_locked.lua, server/server_open.lua and server/server_locked.lua. If you edited the old files, redo your changes in the open files.