Ped guide

How to Install an Add-On Ped on a FiveM Server

To install a FiveM add-on ped, copy its resource folder into your server’s resources folder, check that fxmanifest.lua registers peds.meta as PED_METADATA_FILE, add an ensure line to server.cfg, restart, and spawn the model with SetPlayerModel. The steps below use the resource the FiveMRides AI Ped Creator exports.

By FiveMRides. Updated November 1, 2026. Peds from the AI Ped Creator were tested in game on FiveM with GTA V Legacy. GTA V Enhanced has not been tested.

How do I install an add-on ped on a FiveM server?

1. Unzip the resource. Unzip the ped resource so you have one folder with an fxmanifest.lua and a stream folder.
2. Copy it to resources. Copy the folder into your server’s resources folder and keep the folder name simple, without spaces.
3. Check the manifest. Open fxmanifest.lua and confirm it lists peds.meta in files and registers it with data_file ‘PED_METADATA_FILE’.
4. Add the ensure line. Add ensure followed by the folder name to server.cfg.
5. Restart and reconnect. Start the server, then join with a client that has no old cached copy of the ped.
6. Spawn the ped. Request the model with joaat and call SetPlayerModel with it, or add the spawn name to your ped menu.

1. Folder layout

The ZIP holds one resource folder. Inside it you should see this:

my_ped/
  fxmanifest.lua
  peds.meta
  README.txt
  stream/
    my_ped.yft
    my_ped.ymt
    (the ydd and ytd files of the ped)

Copy the folder, not just the stream folder, into resources. Keep the folder name simple, with no spaces, because it is the name you put in ensure.

2. The manifest

A ped resource registers its metadata like this. The exported fxmanifest.lua already has these lines, so this is what to look for:

fx_version 'cerulean'
game 'gta5'

files { 'peds.meta' }
data_file 'PED_METADATA_FILE' 'peds.meta'

The Name entry inside peds.meta must be the same as the spawn name and the model file name. If you rename the folder only, nothing breaks, but if you rename the model files you must change the name in the meta file too.

3. server.cfg

Add one line with the folder name, after the lines that start your framework:

ensure my_ped

4. Spawn the ped for a first test

A minimal client script that turns you into the ped once, when its resource starts. The code runs inside CreateThread so its wait loop does not hold up the rest of the script:

CreateThread(function()
  local model = joaat('my_ped')
  if not IsModelInCdimage(model) or not IsModelValid(model) then
    print('my_ped is not known: check the name and that the resource is started')
    return
  end
  RequestModel(model)
  while not HasModelLoaded(model) do Wait(0) end
  SetPlayerModel(PlayerId(), model)
  SetModelAsNoLongerNeeded(model)
end)

If part of the body is missing right after the swap, add SetPedDefaultComponentVariation(PlayerPedId()) after SetPlayerModel.

5. Spawn it again with a command

To switch to the ped whenever you want, for example with /ped my_ped, use the ready command script in how to spawn a custom ped in FiveM. That guide also covers CreatePed for an NPC and what to check when nothing happens.

6. Use a new name for every test build

FiveM keeps streamed files in a cache on each client. A rebuild with the same name can show the old files, which looks like a bug in the new build. The README in the exported ZIP says the same: use a new spawn name for each test build, and clear the cache if you must keep one. The fix guide shows how.

7. Ped menus

The quickest test needs no script if you run vMenu: its player appearance menu has an option to spawn a ped by its model name, where you type the spawn name. The exact place and wording can differ by vMenu version.

Ped menus keep a list of add-on ped names. Add the spawn name to that list and the ped shows up in the menu. For example, vMenu reads the peds list in its addons.json. Other menus and frameworks have their own place for it, so read the documentation of yours. We have not tested every menu.

Add-on ped or replacement ped?

These steps are for an add-on ped: a model with its own spawn name, registered with a peds.meta, that sits next to the standard peds. A replacement ped overwrites an existing model and needs no meta file, and freemode clothing is a third thing that dresses the two standard multiplayer characters. The AI Ped Creator exports add-on peds. The add-on vs replacement vs EUP guide compares the three in a table.

A safe way to test

• Test on a staging server with only your framework and the ped, not on the live server.
• Spawn the ped alone first, with the plain script above, and only then through your menu or framework.
• Check the ped in the walk, run and a seated position, and from the side of a vehicle door.
• Test on a GTA V Legacy client. Our own test was on Legacy, and GTA V Enhanced has not been tested.
• Join with a second client that has never seen the ped, to be sure the download works.

What this guide does not cover

• GTA V Enhanced: not tested. Our in-game test was on a FiveM Legacy test server.
• Single player GTA V: the ped is a FiveM resource, and we have not tested it for single player mods.
• Every framework and ped menu: we have not tested them all, so the vMenu line above and the framework behaviour are general guidance.

Questions about installing an add-on ped

Does an add-on ped need a peds.meta?

Yes. A replacement ped swaps an existing model and needs no meta file, but an add-on ped has its own name and the game learns about it through a peds.meta registered in the fxmanifest.lua with PED_METADATA_FILE.

How do I spawn the ped?

Request its model with joaat(‘spawn_name’), wait until it is loaded, then call SetPlayerModel(PlayerId(), model). The README in the ZIP has the exact name, and the spawn guide has a ready /ped command.

Why must I use a new name for every test build?

FiveM caches streamed files by resource and file name. If you rebuild with the same name, your client can keep showing the old files. A new name for each test build avoids that.

Can I add the ped to a ped menu?

Usually yes. Menus keep a list of add-on ped names, and you add the spawn name to it. For vMenu that is the peds list in addons.json. Other menus differ, so read the menu’s own documentation.

Do I restart the server after adding the ped?

Add the ensure line, then start or restart the resource, and reconnect your client. If the ped does not appear, restart the server and clear the client cache before you look for other causes.

Where do the files go?

Put the whole folder from the ZIP in your server’s resources folder, keep the stream folder inside it, and add one ensure line with the folder name to server.cfg.

Do these steps work for a replacement ped?

No. A replacement ped overwrites an existing model and needs no peds.meta or spawn name. These steps are for an add-on ped, which has its own spawn name and is registered with a peds.meta.