# Add-on ped not loading in FiveM: invisible peds, missing textures and resets

> Add-on ped invisible, untextured or resetting after respawn in FiveM? Check IsModelInCdimage, the pedname^ drawable prefix and ClipDictionaryName in peds.meta

Source: https://fam-tools.com/guides/fivem-addon-ped-troubleshooting · FAM Tools · published 2026-09-19 · updated 2026-09-19 · about 8 min

**Short answer.** Check the model first: `IsModelInCdimage(hash)` false means the game never received the files, which is a naming or resource-start problem. If the model exists but is invisible, the drawable files are not named with the `pedname^` prefix or are missing. Wrong animations point to `ClipDictionaryName` or `Pedtype` in `peds.meta`, which must be loaded with `data_file 'PED_METADATA_FILE'`. Resets after respawn come from framework skin systems reloading a freemode model.

## Key points

- Start with `IsModelInCdimage`: it separates "not streamed" from "streamed but broken".
- The `.yft` filename is the model name; `peds.meta` `<Name>` must match it.
- Component drawables and textures use the `pedname^file` prefix in a FiveM stream folder.
- After `SetPlayerModel`, re-read `PlayerPedId()`; the old handle is gone.
- Frameworks restore freemode peds on spawn and skin load; hook their events.
- Wrong movement or T-poses are metadata problems, not model problems.

Add-on peds fail in more ways than almost any other streamed asset. The model can be missing entirely, present but invisible, visible but untextured, animated wrongly, visible only to the player who spawned it, or perfectly fine until the player dies and the framework puts them back into a freemode body. Each failure has a specific cause, and most of them can be identified in a minute with the right check. This guide is the troubleshooting companion to [adding custom peds](https://fam-tools.com/guides/fivem-custom-peds): start with the symptom, find the cause, fix it once.

## First check: does the game know the model?

Before touching any file, ask the client whether the model exists. Paste this into a client script, restart it and run the command with the ped's name.

*client.lua — /pedcheck*

```lua
RegisterCommand('pedcheck', function(_, args)
    local name = args[1]
    if not name then return print('usage: /pedcheck <model>') end
    local hash = GetHashKey(name)

    print(('%s -> hash %d'):format(name, hash))
    print('in cdimage:', IsModelInCdimage(hash))
    print('valid:', IsModelValid(hash))
    print('is ped:', IsModelAPed(hash))

    RequestModel(hash)
    local timeout = GetGameTimer() + 10000
    while not HasModelLoaded(hash) and GetGameTimer() < timeout do Wait(50) end
    print('loaded:', HasModelLoaded(hash))
    SetModelAsNoLongerNeeded(hash)
end, false)
```

| Result | Meaning | Look at |
| --- | --- | --- |
| in cdimage false | The model file never reached the client | Resource start, .yft name, stream folder |
| in cdimage true, is ped false | The name belongs to a non-ped model | Model name collision or wrong file type |
| loaded false after 10 s | Model found but dependencies missing or broken | Drawables, textures, oversize warnings |
| all true, still invisible | Model loads but has nothing to draw | Drawable naming, component setup |

## What an add-on ped is made of

A ped is not one file. Understanding the parts makes the naming rules obvious.

| File | Purpose | Naming in stream/ |
| --- | --- | --- |
| `mypedname.yft` | Skeleton and fragment; defines the model name | Exactly the model name |
| `mypedname.ymt` | Component metadata: which drawables and textures exist | Exactly the model name |
| `head_000_r.ydd`, `uppr_000_u.ydd`… | Drawables (meshes) per component | `mypedname^head_000_r.ydd` |
| `head_diff_000_a_whi.ytd`… | Textures per drawable | `mypedname^head_diff_000_a_whi.ytd` |
| `peds.meta` | Behaviour: animations, type, capsule, personality | Declared in fxmanifest |

In the game's own archives, component files sit in a folder named after the ped. A FiveM `stream` folder has no such namespacing, so the folder is encoded into the filename with a caret: `mypedname^uppr_000_u.ydd` means "the file `uppr_000_u.ydd` belonging to `mypedname`". Without the prefix, the engine has no idea which ped a generic name like `uppr_000_u.ydd` belongs to, and the ped loads with nothing to draw. That is the single most common cause of invisible add-on peds.

Some peds are single-mesh models packed differently, with the textures in `mypedname.ytd` and no component files at all. Follow what the original download ships; do not rename files that are already prefixed, and never strip the caret when "tidying" file names.

## Manifest and peds.meta

*fxmanifest.lua*

```lua
fx_version 'cerulean'
game 'gta5'

files {
    'peds.meta',
}

data_file 'PED_METADATA_FILE' 'peds.meta'
```

*peds.meta (one entry, trimmed)*

```xml
<?xml version="1.0" encoding="UTF-8"?>
<CPedModelInfo__InitDataList>
  <InitDatas>
    <Item>
      <Name>mypedname</Name>
      <ClipDictionaryName>move_m@generic</ClipDictionaryName>
      <ExpressionSetName>expr_set_ambient_male</ExpressionSetName>
      <Pedtype>CIVMALE</Pedtype>
      <MovementClipSet>move_m@business@c</MovementClipSet>
      <StrafeClipSet>move_ped_strafing</StrafeClipSet>
      <PedCapsuleName>STANDARD_MALE</PedCapsuleName>
      <Personality>SERVICEMALES</Personality>
      <IsStreamedGfx value="false" />
    </Item>
  </InitDatas>
</CPedModelInfo__InitDataList>
```

A real entry has many more fields; keep the full entry that shipped with the model and only change what you understand. The rules that matter:

- `<Name>` must equal the `.yft` filename without extension.
- One `<Item>` per ped. Several peds can share one `peds.meta`.
- Only one resource should define a given `<Name>`. Duplicates across resources produce whichever loaded last.
- Animal peds need animal values for `Pedtype`, clip sets and capsule; copying a human entry onto a dog gives a T-posing dog.
- Leave `IsStreamedGfx` at the value the model author shipped.

Replacing a vanilla ped (streaming files with an existing name such as `a_m_y_business_01`) needs no `peds.meta` at all, because the game already has metadata for that name. That is the fastest way to tell a metadata problem from a model problem: if the model works as a replacement but not as an add-on, the meta is at fault.

## Symptom by symptom

| Symptom | Most likely cause | Fix |
| --- | --- | --- |
| Player becomes the default freemode or stays unchanged | Model not in cdimage; resource not started or .yft misnamed | Check `ensure` order and the .yft filename |
| Invisible player, shadow and weapon still visible | Drawables not prefixed with `pedname^` or missing | Rename component files with the caret prefix |
| Grey or white untextured body | Texture .ytd names do not match the drawables | Match `pedname^uppr_diff_000_a_uni.ytd` to `pedname^uppr_000_u.ydd` |
| T-pose, sliding or wrong walk | Wrong `ClipDictionaryName`, `MovementClipSet` or `Pedtype` | Use the shipped meta; animals need animal clip sets |
| Only the spawning player sees the ped | Model switched with a local-only trainer on a non-OneSync setup, or others lack the files | Switch with `SetPlayerModel` on OneSync; confirm the resource streams to everyone |
| Game crashes when the ped loads | Broken or oversized drawable, wrong game build for its assets | Test the model alone; check oversize warnings |
| Works, then reverts after death or relog | Framework skin system loads freemode | Re-apply after the framework's skin events |

## Switching to the ped correctly

Half of the "ped not working" reports are the switch code, not the ped. `SetPlayerModel` replaces the player's ped entity, so the handle you had before the call is dead afterwards.

*client.lua*

```lua
local function becomePed(name)
    local hash = GetHashKey(name)
    if not IsModelInCdimage(hash) or not IsModelAPed(hash) then
        print(('model %s not available'):format(name))
        return false
    end

    RequestModel(hash)
    local timeout = GetGameTimer() + 10000
    while not HasModelLoaded(hash) do
        if GetGameTimer() > timeout then return false end
        Wait(0)
    end

    SetPlayerModel(PlayerId(), hash)
    local ped = PlayerPedId()
    SetPedDefaultComponentVariation(ped)
    SetModelAsNoLongerNeeded(hash)
    return true
end
```

- Always re-read `PlayerPedId()` after `SetPlayerModel`; code that keeps using a cached ped handle acts on an entity that no longer exists.
- `SetPedDefaultComponentVariation` gives the ped its default drawables. Skipping it can leave components unset, which looks like missing body parts.
- Weapons and armour are cleared by a model change. Re-give them from your inventory if needed.
- Health resets to the new model's default. Save and restore it if the switch happens mid-play.

## Frameworks that switch you back

ESX, QBCore and most appearance resources store a freemode character and re-apply it on spawn, revive and relog. Any add-on ped set before those events is overwritten. There is no universal fix, but the pattern is the same everywhere: keep the player's chosen ped in your own storage (a database column, a resource KVP or a state bag) and re-apply it after the framework finishes loading the skin.

Also remember that clothing menus only work on the two freemode models, `mp_m_freemode_01` and `mp_f_freemode_01`. An add-on ped with its own components can have its variations changed with `SetPedComponentVariation`, but it will not behave like a freemode character in shops or outfit systems, and saving its "skin" through a freemode-based appearance resource will corrupt the stored outfit. Keep add-on peds out of the regular skin save path.

## A clean test workflow

1. Put the ped alone in a fresh resource with only its stream files and `peds.meta`, and `ensure` it last.
2. Join, run `/pedcheck <name>` and confirm the model is in the cdimage and loads.
3. Switch to it with the function above, walk, sprint, crouch, aim and enter a vehicle. Animation problems show within a minute.
4. Ask a second player to look at you. If they see a different model, the switch happened only locally.
5. Die and respawn with your framework running. If the ped reverts, the framework hook is missing.
6. Only then move the ped into your main ped pack resource.

Testing each ped alone first saves the most time on servers with large ped packs, because a single badly named file in a pack of forty peds otherwise looks like "the whole pack is broken".

## Cache, size and game build

- After renaming files, clear the client cache once so the old names are not served from cache. See [clearing the FiveM cache](https://fam-tools.com/guides/fivem-clear-cache).
- High-poly peds with 4K textures trigger oversize warnings and can fail to stream on busy servers. See [the oversized assets warning](https://fam-tools.com/guides/fivem-oversized-assets-warning).
- Peds that reference newer DLC animations or expressions need a matching enforced build. See [game builds and DLC](https://fam-tools.com/guides/fivem-game-build-dlc).
- Keep each ped pack in its own resource so a broken ped can be disabled without losing the rest.

For deep checks, open the files in CodeWalker: a drawable that will not open there will not render in game either, and the `.ymt` shows which drawable and texture numbers the ped expects, which makes missing files easy to spot. General streaming rules are covered in [streaming assets](https://fam-tools.com/guides/fivem-streaming-assets).

## Questions

### Why is my FiveM add-on ped invisible?

Usually the component drawables in the stream folder are missing the `pedname^` prefix, so the engine cannot attach them to the model. Rename them as `pedname^uppr_000_u.ydd` and so on.

### How do I check if a ped model is streamed?

Run `IsModelInCdimage(GetHashKey('modelname'))` on the client. False means the files never reached the game.

### Why does my ped T-pose?

The animation fields in `peds.meta`, mainly `ClipDictionaryName`, `MovementClipSet` and `Pedtype`, do not suit the skeleton. Use the entry that shipped with the model.

### Why does my ped reset after I die?

Your framework re-applies the stored freemode skin on spawn. Re-apply the add-on ped after its skin-loaded or spawn events.

### Do replacement peds need peds.meta?

No. Replacements reuse a vanilla name, and the game already has metadata for it.

### Can I use clothing menus on add-on peds?

Not properly. Clothing and appearance menus are built for the freemode models only.

## Related

- https://fam-tools.com/guides/fivem-custom-peds
- https://fam-tools.com/guides/fivem-streaming-assets
- https://fam-tools.com/guides/fivem-oversized-assets-warning
- https://fam-tools.com/guides/fivem-clear-cache
- https://fam-tools.com/guides/fivem-eup-addon-clothing