Streaming assetsintermediate9 min readupdated 11 Sept 2026

Adding a custom ped model to FiveM

Q: How do I add a custom ped to FiveM?

Stream its model files, declare peds.meta with data_file 'PED_METADATA_FILE', and switch to it with SetPlayerModel.

The short answer

An add-on ped is a resource with the model files (.yft, .ydd, .ytd, and often a .ymt) in stream/ and a peds.meta declared with data_file 'PED_METADATA_FILE'. Players switch to it with SetPlayerModel after RequestModel. Add-on peds do not use the freemode clothing system, so appearance menus cannot dress them. Restrict ped menus with ACE and keep file sizes reasonable.

A custom ped in FiveM is a resource: the model files in stream/, a peds.meta declared in the manifest, and SetPlayerModel to put a player into it. Add-on peds — characters, animals, mascots, staff models — stream like any other asset, but they behave differently from the freemode character players normally use: no clothing slots, no face customisation. Knowing that difference prevents most of the complaints.

Adding a custom ped model to FiveM — illustrated with a FiveM-compatible minimap render

#The resource

fxmanifest.lua

fx_version 'cerulean'
game 'gta5'

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

-- stream/ holds the ped's .yft, .ydd, .ytd (and .ymt if supplied)

#Switching to the ped

client.lua

local function setPed(name)
    local model = joaat(name)
    if not IsModelInCdimage(model) then return print('model not found: ' .. name) end
    RequestModel(model)
    while not HasModelLoaded(model) do Wait(0) end
    SetPlayerModel(PlayerId(), model)
    SetPedDefaultComponentVariation(PlayerPedId())
    SetModelAsNoLongerNeeded(model)
end

RegisterCommand('ped', function(_, args) setPed(args[1]) end, true) -- restricted

SetPlayerModel replaces the player’s ped, so PlayerPedId() returns a new handle afterwards. Re-apply weapons, health and armour if your scripts expect them.

#Freemode vs add-on peds

	Freemode ped	Add-on ped
Clothing slots	Yes (and add-on clothing)	Only what the model defines
Face/hair customisation	Yes	No
Appearance menus	Work	Mostly do not
Typical use	Every normal character	Events, staff, animals, special roles

For uniforms and outfits, use add-on clothing on freemode peds instead — see add-on clothing and EUP.

#Ped menus and permissions

Ped menus are fun and easily abused (tiny peds, invisible animals in PvP). Restrict the command with ACE — add_ace group.admin command.ped allow — or allow specific peds per player through your ped menu’s config. See ACE permissions.

Share this guideX Reddit Facebook

Questions

How do I add a custom ped to FiveM?

Stream its model files, declare peds.meta with data_file 'PED_METADATA_FILE', and switch to it with SetPlayerModel.

Why can I not change clothes on my custom ped?

Only freemode peds use the clothing system. Add-on peds have only the variations built into the model.

Why does my ped not load?

The model name is wrong, the resource is not started, or the files failed to stream (check for oversized-asset warnings).

Can I restrict peds to certain players?

Yes, with ACE permissions on the command or per-player allow lists in your ped menu.

Ready to pick a map?

Twelve themes on three base map styles, $8 each, instant download.

Browse minimaps Brand your own

Relevant to what you just read

Custom FiveM-compatible minimaps

Look it up while you work

The reference tables this guide leans on, free and without an account.

All 860 ped model namesEvery model GetHashKey resolves, with its hash and how many clothing components and props it carries.
The map modding glossary38 terms — file formats, radar parts, framework words — each with a one-line answer first.
The same tables as JSON and CSVFree downloads, CORS open, no account and no API key — ship the list inside your own resource instead of scraping a page.