Ped guide

How to Spawn a Custom Ped in FiveM (SetPlayerModel)

To spawn a custom ped in FiveM, turn its spawn name into a hash with joaat, call RequestModel, wait until HasModelLoaded is true, then call SetPlayerModel to become the ped or CreatePed to place it as an NPC. Finish with SetModelAsNoLongerNeeded. The ped resource must already be installed and started.

By FiveMRides. Updated November 1, 2026. Peds from the AI Ped Creator were tested in game on FiveM with GTA V Legacy. GTA V Enhanced has not been tested.

Spawn a custom ped, step by step

1. Find the spawn name. Read the README.txt in the ped resource, or open peds.meta and copy the Name value.
2. Check the resource runs. Make sure the ensure line for the resource is in server.cfg and the resource is started.
3. Create the client script. Add a client script to a resource, listed under client_scripts in its fxmanifest.lua.
4. Convert the name to a hash. Call joaat with the spawn name.
5. Request and wait. Call RequestModel and loop on HasModelLoaded until it is true.
6. Change the model. Call SetPlayerModel for yourself or CreatePed for an NPC, then SetModelAsNoLongerNeeded.

1. Find the spawn name

The spawn name of an add-on ped is the Name entry in its peds.meta. It is also the name of the model files in the stream folder, for example my_ped.yft. The README.txt in a ped exported by the AI Ped Creator gives the exact name. This guide does not cover installing the resource: see how to install an add-on ped first.

2. Hash the name with joaat

FiveM natives that take a model do not take the text name. They take a 32 bit hash of it. In FiveM Lua, joaat('my_ped') returns that hash (a Jenkins one-at-a-time hash). GetHashKey('my_ped') is the game native that computes the same kind of hash, through a slower native call. For a fixed name you can also write it in backticks, `my_ped`, which FiveM turns into the hash when the script is compiled. Type the spawn name in lower case, exactly as it is in peds.meta; the AI Ped Creator only allows lower case names.

3. The loader and a /ped command

A complete client script. It adds a /ped command that turns you into the ped you name. /ped my_ped spawns your ped, and /ped with no name uses the default shown at the top.

-- client.lua
local defaultPed = 'my_ped'

local function loadModel(model)
    if not IsModelInCdimage(model) or not IsModelValid(model) then
        return false
    end
    RequestModel(model)
    local timeout = GetGameTimer() + 10000
    while not HasModelLoaded(model) do
        if GetGameTimer() > timeout then
            return false
        end
        Wait(0)
    end
    return true
end

RegisterCommand('ped', function(source, args)
    local name = args[1] or defaultPed
    local model = joaat(name)

    if not loadModel(model) then
        print(('Ped model "%s" did not load. Check the name and that its resource is started.'):format(name))
        return
    end

    SetPlayerModel(PlayerId(), model)
    SetModelAsNoLongerNeeded(model)
end, false)

Add the file to the fxmanifest.lua of any resource you control:

fx_version 'cerulean'
game 'gta5'

client_script 'client.lua'

Notes on the code:

• IsModelInCdimage and IsModelValid are false when the game does not know the model, which is the usual sign of a wrong name or a resource that is not started. The FiveM native reference uses the same two checks before RequestModel.
• The timeout stops the loop from running forever if the model never streams.
• After SetPlayerModel your ped handle changes. Call PlayerPedId() again instead of reusing an old value.
• SetModelAsNoLongerNeeded releases the hold that RequestModel put on the model. Calling it right after SetPlayerModel is the pattern the native reference shows.
• A client command like this one works for every player who has the script. Keep it on a staging server, or remove it before your server goes live.
• If part of the body is missing right after the swap, try SetPedDefaultComponentVariation(PlayerPedId()).

Test this on a staging server first. The natives and their arguments match the FiveM native reference, but we have not run this exact script on our test server yet.

4. Change yourself or spawn an NPC

The first argument of CreatePed is the ped type, which the game does not use (any value such as 4 works). Pass true as the seventh argument so other players see the NPC. An NPC example, placed in front of you. It reuses the loadModel function and defaultPed from the script above:

RegisterCommand('pednpc', function(source, args)
    local model = joaat(args[1] or defaultPed)
    if not loadModel(model) then return end

    local me = PlayerPedId()
    local coords = GetOffsetFromEntityInWorldCoords(me, 0.0, 2.0, 0.0)
    local npc = CreatePed(4, model, coords.x, coords.y, coords.z, GetEntityHeading(me) + 180.0, true, false)
    SetModelAsNoLongerNeeded(model)
    SetEntityAsNoLongerNeeded(npc) -- let the game clean it up later
end, false)

5. Frameworks and ped menus

Spawning by name works the same everywhere because it is the plain game native. How a menu or framework lists peds differs.

• vMenu: it has an option to spawn a ped by model name. Its list for add-on peds is configured in its own files. Check the vMenu documentation for your version.
• ESX and QBCore: these frameworks often manage your appearance and may reapply a saved skin after you change model. If the ped turns back, check your framework docs for how to set a custom model or stop the skin reload.
• Other ped menus: most keep a list of names. Add the spawn name to it as the menu’s documentation says.

We have not tested every framework or menu.

6. About “fivem ped spawn codes”

Searches for ped spawn codes usually look for the names of the standard game peds. Those names work in the same script: put one in joaat. This guide is about custom peds that you install yourself.

Common mistakes

• The spawn name in the script differs from the Name in peds.meta or from the model file name.
• The resource is not started, or was started after the script ran. Check the server console.
• No wait loop: calling SetPlayerModel before HasModelLoaded is true.
• A loop without a timeout that hangs when the name is wrong.
• Reusing an old ped handle after SetPlayerModel.
• Testing a rebuilt ped under the same name. FiveM caches streamed files, so use a new spawn name for every test build.
• Running the code on the server side. These natives are client natives.

If the ped is invisible, crashes the game or stands in a T-pose, go to the fix guide.

What this guide does not cover

• Installing the resource, which is in the install guide.
• Replacement peds, which need no spawn code. See add-on vs replacement vs EUP.
• Your framework’s own skin and character systems.
• GTA V Enhanced. Our ped was tested in game on FiveM Legacy only.

Questions about spawning a custom ped

How do I spawn a custom ped in FiveM?

Hash the spawn name with joaat, call RequestModel, wait for HasModelLoaded, then call SetPlayerModel(PlayerId(), model) to become the ped or CreatePed to place it as an NPC. The resource that holds the ped must be started first.

What is the difference between joaat and GetHashKey?

Both give the Jenkins one-at-a-time hash that model natives take. GetHashKey is a game native, while joaat does the same work in FiveM Lua without a native call. A name written in backticks is hashed when the script is compiled.

Why does SetPlayerModel do nothing?

Usually the model is not loaded or not known. Check that the name matches the peds.meta Name, that the resource is started, and that you wait for HasModelLoaded before the call.

Do I need SetModelAsNoLongerNeeded?

Yes, once the model is in use. It releases the hold that RequestModel put on the model, so the game can free it from memory when nothing uses it any more.

Can I use a custom ped with vMenu, ESX or QBCore?

Usually yes, because they use the same natives, but each decides how peds are listed and how skins are saved and reapplied. Check the documentation of your framework, and test on a staging server.

Where is the spawn name of my ped?

It is the Name entry in peds.meta and the name of the model files in the stream folder. The README.txt in a ped from the AI Ped Creator states it too.