How to add addon peds to FiveM: stream files, peds.meta, spawn name

You have a ped pack, with files such as .ydd, .yft, .ytd and a peds.meta, and you want to spawn the ped or play as it. This guide shows where each file goes, what the manifest needs, how to spawn the ped and how to set it as the player model.

#What a ped pack contains

A ped is made of several files that share the ped's name:

• .yft: the main model of the ped.
• .ydd: the clothing and body parts (head, hair, torso, legs). Often placed in a subfolder with the ped's name.
• .ytd: the textures.
• .ymt: the "ped variation" file, which tells the game which components and textures the ped has.
• peds.meta: the data entry that defines the ped (name, type, animations and so on).

The model files go in stream. The peds.meta goes beside the manifest and is loaded as a data file.

#Folder structure

resources/[peds]/mycop/
  fxmanifest.lua
  peds.meta
  stream/
    mycop.yft
    mycop.ymt
    mycop.ytd
    mycop/
      head_000_r.ydd
      uppr_000_u.ydd
      lowr_000_u.ydd
      ...

The exact inner file names depend on the pack. Do not rename them: the .ymt refers to them. Keep the structure the author gave you.

#The fxmanifest.lua

fx_version 'cerulean'
game 'gta5'

files {
    'peds.meta',
}

data_file 'PED_METADATA_FILE' 'peds.meta'

The files entry makes the file available to the game client, and data_file 'PED_METADATA_FILE' tells the game it holds ped definitions. You need both. For several peds in one resource, you can use one peds.meta with several entries, or a pattern such as '**/peds.meta' in both lines.

The name of a ped is in the peds.meta:

<CPedModelInfo__InitDataList>
  <InitDatas>
    <Item>
      <Name>mycop</Name>
      <PropsName>NULL</PropsName>
      ...
    </Item>
  </InitDatas>
</CPedModelInfo__InitDataList>

Here the model name is mycop. It must match the file names of the .yft, .ymt and .ytd.

#Start it and spawn it

ensure mycop

To spawn the ped in a script, request the model first:

local model = joaat('mycop')

RequestModel(model)
while not HasModelLoaded(model) do
    Wait(0)
end

local ped = CreatePed(4, model, coords.x, coords.y, coords.z, heading, true, false)
SetModelAsNoLongerNeeded(model)

If your server uses ox_lib, lib.requestModel(model) does the request and the wait. If the model name does not exist, HasModelLoaded never becomes true and the loop above hangs, so a timeout is good practice for names that come from a config.

Many admin menus can spawn a ped by name too: type mycop and it appears.

#Set the ped as the player model

To play as the ped, change the model of the player:

local model = joaat('mycop')

RequestModel(model)
while not HasModelLoaded(model) do
    Wait(0)
end

SetPlayerModel(PlayerId(), model)
SetModelAsNoLongerNeeded(model)
SetPedDefaultComponentVariation(PlayerPedId())

Remember that changing the player model gives you a new ped. Weapons, health and some state are reset, so give them back after the change if your server needs them.

#ESX and QBCore skin menus

Skin and character scripts are the main trouble. They apply a freemode ped (mp_m_freemode_01 or mp_f_freemode_01) when you spawn, and your model is replaced a moment later. Options:

• Use the option in your skin script. Many appearance scripts have a way to set a custom ped or a list of allowed peds. Check the config of the script.
• Set the model after the skin loads. On ESX, wait for esx:playerLoaded and for the skin script to finish. On QBCore, wait for QBCore:Client:OnPlayerLoaded. Then call SetPlayerModel.
• Do not save the addon ped as the skin. Appearance data for a freemode ped does not fit another model, and a saved skin of the wrong type can make the character load wrong. Keep the ped choice in a separate field or script.

On QBox the same applies: the appearance script decides which model the player gets, so set the ped after it, or use its own custom ped option if there is one.

#Common problems

• The ped is invisible or a default model. The peds.meta is not loaded or the names differ. Check the data_file line and the name in <Name>.
• The ped has no face or white textures. The .ytd or the .ydd files are missing, in the wrong folder or renamed. The .ymt needs the original names.
• The resource starts but the ped cannot be spawned. A typo in the spawn name. It must equal the <Name> entry in peds.meta.
• The game crashes or streaming warns. Large files and many peds use streaming memory. See oversized assets.
• The resource does not start. A path in files does not exist. See couldn't start resource.

Cars follow the same data file idea: see how to add addon cars.

#Checklist