# Adding a custom ped model to FiveM

> Add a custom ped to FiveM: the .yft, .ydd and .ytd files it needs, the peds.meta data_file line, SetPlayerModel, and why add-on peds cannot be dressed.

Source: https://fam-tools.com/guides/fivem-custom-peds · FAM Tools · published 2026-09-11 · updated 2026-09-11 · about 9 min

**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.

## Key points

- Model files in `stream/`, `peds.meta` as `PED_METADATA_FILE`.
- `RequestModel` → `SetPlayerModel(PlayerId(), model)`.
- Clothing menus only work for `mp_m_freemode_01` / `mp_f_freemode_01`.
- Framework character data expects freemode peds — switch back after events.
- Heavy ped models can trip oversized-asset warnings.

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.

## The resource

*fxmanifest.lua*

```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*

```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](https://fam-tools.com/guides/fivem-eup-addon-clothing).

## 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](https://fam-tools.com/guides/fivem-ace-permissions).

## 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.

## Related

- https://fam-tools.com/guides/fivem-addon-ped-troubleshooting
- https://fam-tools.com/guides/fivem-eup-addon-clothing
- https://fam-tools.com/guides/fivem-oversized-assets-warning
- https://fam-tools.com/guides/fivem-custom-sounds
- https://fam-tools.com/guides/fivem-ace-permissions
- https://fam-tools.com/guides/fivem-add-addon-cars