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

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

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)

#What an add-on ped is made of

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

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

fx_version 'cerulean'
game 'gta5'

files {
    'peds.meta',
}

data_file 'PED_METADATA_FILE' 'peds.meta'

<?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

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

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.
• High-poly peds with 4K textures trigger oversize warnings and can fail to stream on busy servers. See the oversized assets warning.
• Peds that reference newer DLC animations or expressions need a matching enforced build. See game builds and 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.