Adding custom ped models to FiveM

Custom peds — characters, animals, mascots, staff models — are popular on roleplay and event servers. They stream like any other asset, but behave differently from the freemode character players normally use: no clothing slots, no face customisation. Knowing that difference prevents most complaints.

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.

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)

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

Questions