Props personalizados no FiveM: do modelo 3D ao objeto no jogo

Props personalizados são os detalhes que deixam um servidor de FiveM com cara própria: um copo de café com a marca da cafeteria, uma mesa de laboratório de drogas, um troféu para os vencedores de evento, uma placa com a logo do seu server. O GTA V vem com milhares de props, mas uma hora você vai precisar de um que não existe.

Este guia cobre o caminho todo, do modelo 3D até um objeto que os players conseguem ver, tocar e pegar: quais arquivos um prop precisa, os dois jeitos de fazer, como dar stream e como spawnar, posicionar e usar pelos scripts. Se você procurava como adicionar props no FiveM, está tudo aqui.

Resumindo: um prop de FiveM é um modelo .ydr, um dicionário de texturas .ytd e um arquivo de archetypes .ytyp, opcionalmente com uma collision .ybn. Coloque tudo na pasta stream/ de um resource, declare o .ytyp com data_file 'DLC_ITYP_REQUEST' no fxmanifest.lua e depois spawne o prop com RequestModel e CreateObject ou deixe ele fixo no mapa com um .ymap.

Do que um prop de FiveM é feito

Um prop não é um arquivo só. O GTA V divide um objeto em algumas partes, cada uma com sua função:

Para ver em detalhe esses e os outros formatos da RAGE, confira Formatos de arquivo do GTA V e FiveM.

Por que o .ytyp importa

O .ydr é só geometria. O jogo não sabe que existe um objeto chamado myrp_coffee_cup até um archetype dizer isso. O archetype dentro de um .ytyp registra, entre outras coisas:

• o nome do modelo, que vira o hash dele;
• o dicionário de texturas de onde ele deve carregar as texturas;
• a bounding box e a bounding sphere, que a engine usa para decidir quando o objeto está na tela;
• a distância de LOD, a distância em que o objeto para de ser desenhado;
• flags que controlam física e renderização.

Sem um archetype carregado, o CreateObject não tem o que criar e os arquivos de mapa não conseguem posicionar o objeto. Por isso um .ytyp faltando ou não declarado é o motivo mais comum de um prop personalizado "não funcionar".

Pipeline 1: o jeito tradicional (Blender + Sollumz)

As ferramentas padrão da comunidade são gratuitas:

• Blender com o add-on Sollumz. O Sollumz importa e exporta formatos do GTA V direto no Blender, incluindo .ydr, .ybn, .ytyp e, nas versões mais recentes, dicionários de texturas .ytd. Ele exige Blender 4.0 ou mais novo; no Blender 4.2+ você instala como extensão pelo https://repo.sollumz.org/.
• CodeWalker para navegar pelos arquivos do jogo, ver modelos no mundo e criar arquivos .ymap para posicionar objetos no mapa.
• O OpenIV ainda é muito usado para navegar e extrair arquivos do jogo, mas você não precisa dele para montar um prop.

O fluxo, por alto:

1. Modele o objeto no Blender ou importe um modelo existente. Mantenha a escala real: uma unidade do Blender é um metro no jogo.
2. Aplique os shaders do Sollumz nos materiais e converta a malha em um drawable.
3. Crie uma collision para ele, com primitivas simples (caixas, cilindros) ou com uma malha low-poly.
4. Crie o archetype nas ferramentas de .ytyp do Sollumz: defina o nome, o dicionário de texturas, a distância de LOD e o tipo de asset.
5. Exporte o .ydr, .ytd, .ybn e .ytyp.

Esse caminho dá controle total e é o ideal para props detalhados e de destaque. O custo é tempo: modelagem, UV unwrap, texturização e aprender o fluxo do Sollumz somam horas para um único prop, e bem mais na primeira vez.

Pipeline 2: gerar com o BLDR

A ferramenta 3D do BLDR pula a maior parte desse trabalho:

1. Abra o 3D e gere um modelo a partir de um prompt de texto ou de uma imagem de referência, ou importe seu próprio GLB.
2. Edite o modelo e faça a pintura de textura até ficar do jeito certo.
3. Exporte. O download é um zip que já é um resource de FiveM, com o nome do seu projeto:

O manifest já declara o arquivo de archetypes, e o cl_spawn.lua opcional registra um comando /spawn_<model> que coloca o prop na sua frente para testar. Exportar exige um plano pago.

Seja qual for o pipeline, o resultado é o mesmo conjunto de arquivos, e tudo daqui para baixo vale para os dois.

Dando stream no prop por um resource

Coloque os arquivos na pasta de um resource e avise o FXServer sobre o .ytyp:

fx_version 'cerulean'
game 'gta5'

data_file 'DLC_ITYP_REQUEST' 'stream/myrp_coffee_cup.ytyp'

Tudo dentro de stream/ é enviado aos players automaticamente. A linha data_file é o que faz o jogo registrar de verdade os archetypes do .ytyp; só dar stream no arquivo não basta.

Depois inicie o resource no server.cfg:

ensure myrp_coffee_cup

Se você tem muitos props, coloque todos em um resource só com um único .ytyp contendo todos os archetypes, ou liste várias linhas data_file. Poucos resources bem organizados são mais fáceis de manter do que cinquenta pequenininhos. Começando agora com resources? Como criar um servidor de FiveM explica a estrutura de pastas.

Spawnando um prop por script

Para criar um prop em tempo de execução, carregue o modelo, crie o objeto e depois libere o modelo:

local function spawnProp(modelName, coords)
    local model = joaat(modelName)

    if not IsModelInCdimage(model) then
        print(('Model %s does not exist'):format(modelName))
        return
    end

    RequestModel(model)
    while not HasModelLoaded(model) do
        Wait(0)
    end

    local obj = CreateObject(model, coords.x, coords.y, coords.z, true, true, false)
    PlaceObjectOnGroundProperly(obj)
    FreezeEntityPosition(obj, true)
    SetModelAsNoLongerNeeded(model)

    return obj
end

RegisterCommand('coffeecup', function()
    local coords = GetOffsetFromEntityInWorldCoords(PlayerPedId(), 0.0, 1.5, 0.0)
    spawnProp('myrp_coffee_cup', coords)
end, false)

O que cada parte faz:

• RequestModel / HasModelLoaded – o CreateObject espera que o modelo já esteja carregado. Se pular isso, a criação falha.
• CreateObject(model, x, y, z, isNetwork, netMissionEntity, doorFlag) – o quarto argumento decide se os outros players veem o objeto. false cria um objeto só no client.
• PlaceObjectOnGroundProperly – encaixa o objeto no chão logo abaixo dele.
• FreezeEntityPosition – impede que o objeto seja empurrado ou caia. Use em móveis e decoração.
• SetModelAsNoLongerNeeded – libera o modelo do seu script depois que o objeto já existe.

Apague os objetos que não precisa mais com DeleteEntity, senão eles ficam no mundo até o resource parar. Quando o objeto precisa ser do servidor, CreateObject e CreateObjectNoOffset também estão disponíveis em scripts server-side.

Deixando props fixos no mapa com um .ymap

Para props que fazem parte do mapa, como uma placa num prédio ou os móveis de uma loja, script não é a ferramenta certa. Use um .ymap, o arquivo que o GTA V usa para posicionar entidades no mundo.

1. Abra o CodeWalker e crie um projeto novo.
2. Adicione os arquivos do seu prop ao projeto para o CodeWalker conhecer seu archetype.
3. Crie um .ymap novo no projeto, adicione entidades com o nome do seu modelo e mova para o lugar certo na visão do mundo.
4. Salve o .ymap e jogue na pasta stream/ do seu resource, junto do prop.

Props de mapa posicionados assim carregam e descarregam junto com o mundo, não gastam tempo de script e sobrevivem a restarts sem nenhum código. O mesmo método escala para interiores inteiros; veja MLOs no FiveM para montar prédios completos.

Deixando props interativos

Usando ox_target em um prop

Com o ox_target, você pode adicionar opções de interação a todas as instâncias do seu modelo, seja spawnado por script ou posicionado por um .ymap:

exports.ox_target:addModel('myrp_coffee_cup', {
    {
        name = 'myrp_drink_coffee',
        icon = 'fa-solid fa-mug-hot',
        label = 'Drink coffee',
        distance = 2.0,
        onSelect = function(data)
            print(('Drinking from entity %s'):format(data.entity))
        end,
    },
})

Para um único objeto spawnado em vez de todas as cópias do modelo, use exports.ox_target:addLocalEntity(entity, options). Atenção: o repositório original da overextended está arquivado; o fork mantido fica na CommunityOx.

Segurando um prop na mão

Props também funcionam como itens na mão: um celular, um copo, uma prancheta. Prenda o objeto em um osso do ped com AttachEntityToEntity:

local function holdProp(modelName)
    local ped = PlayerPedId()
    local model = joaat(modelName)

    RequestModel(model)
    while not HasModelLoaded(model) do
        Wait(0)
    end

    local coords = GetEntityCoords(ped)
    local obj = CreateObject(model, coords.x, coords.y, coords.z, true, true, false)
    local boneIndex = GetPedBoneIndex(ped, 57005) -- SKEL_R_Hand (mão direita)

    AttachEntityToEntity(obj, ped, boneIndex,
        0.12, 0.0, -0.03,   -- offset de posição
        -80.0, 0.0, 0.0,    -- rotação
        true, true, false, true, 1, true)

    SetModelAsNoLongerNeeded(model)
    return obj
end

Repare que o GetPedBoneIndex transforma o ID do osso (57005 é a mão direita) no índice do osso que o native de attach espera. Os valores de offset e rotação dependem de onde fica a origem do seu modelo, então conte com ajustes dentro do jogo. Junte o prop com uma animação para a pose ficar natural; Emotes personalizados no FiveM mostra como fazer os seus. Para transformar o prop em um item usável no inventário, veja Itens personalizados no ox_inventory.

Contagem de polígonos e orçamento de texturas

Cada prop com stream custa memória e tempo de download para os players. Algumas regras práticas:

• Ajuste o detalhe ao tamanho. Um copo em cima da mesa não precisa da mesma contagem de polígonos de um carro. Se ninguém vai ver de perto, simplifique.
• Use LODs e uma distância de LOD sensata. Um prop pequeno não precisa renderizar a centenas de metros. Distâncias de LOD menores significam menos objetos desenhados ao mesmo tempo.
• Mantenha as texturas pequenas. 512×512 ou 1024×1024 dá conta da maioria dos props. Uma textura 4K num objeto pequeno desperdiça memória sem ganho visível.
• Use tamanhos em potência de dois e formatos comprimidos (DXT/BC) para o jogo gerar mipmaps e fazer stream com eficiência.
• Compartilhe dicionários de texturas entre props relacionados em vez de duplicar a mesma textura de madeira ou metal em cada .ytd.
• Mantenha a collision simples. Algumas caixas costumam colidir melhor e mais barato do que uma cópia da malha visual.

O FiveM avisa no console do client quando um asset está pesado demais. Trate esses avisos como bugs para corrigir, não como ruído. Otimizando assets no FiveM aprofunda os orçamentos.

Problemas comuns

O prop está invisível ou o CreateObject retorna 0. O archetype não está carregado. Confira se o .ytyp está em stream/, se o caminho do data_file 'DLC_ITYP_REQUEST' bate exatamente com o nome do arquivo e se o resource está iniciado. Se o objeto existe (você esbarra nele) mas não aparece, confira se o .ytd está com stream e se o nome do dicionário de texturas do archetype bate com ele.

O prop cai pelo chão ou os players atravessam ele. Está sem collision. Adicione um .ybn (ou bounds embutidos) e exporte de novo. Em props spawnados, o FreezeEntityPosition também impede que afundem ou tombem.

HasModelLoaded nunca retorna true. Quase sempre é erro de digitação no hash do modelo. O hash vem do nome do archetype, não do nome do resource. joaat('myrp_coffee_cup') e `myrp_coffee_cup` funcionam, mas só se a grafia bater exatamente com o .ytyp. Use IsModelInCdimage para conferir se o jogo conhece o modelo.

O prop some e aparece à distância. A distância de LOD no .ytyp está baixa demais, ou a bounding box não bate com o modelo. Exporte de novo com os valores certos.

O prop substituiu outro objeto. O nome do seu modelo conflita com um do jogo base ou com outro modelo personalizado. Coloque o nome do seu servidor como prefixo em todos os modelos.

Perguntas frequentes

Os players precisam baixar alguma coisa para ver os props personalizados?

Não. Os arquivos na pasta stream/ de um resource são enviados aos players automaticamente quando eles entram, igual a carros e roupas personalizados.

Dá para spawnar props do GTA V original do mesmo jeito?

Sim. Props nativos do jogo, como o prop_weed_01, já têm archetypes, então você pula os arquivos e a linha data_file e vai direto para RequestModel e CreateObject.

Preciso de um arquivo de collision .ybn?

Não para o prop aparecer, mas sem collision players e veículos atravessam ele, e objetos sem freeze caem pelo chão. Para qualquer coisa em que os players possam esbarrar, inclua um.

É melhor spawnar props por script ou posicionar num .ymap?

Use um .ymap para tudo que faz parte fixa do mapa. Use scripts para props que aparecem e somem: itens na mão, móveis posicionáveis, equipamentos de trabalho e objetos de evento.

Dá para fazer props sem aprender Blender?

Sim. A ferramenta 3D do BLDR gera um modelo a partir de um prompt ou imagem de referência e exporta um resource pronto para stream com o .ydr, o .ytd e o .ytyp já configurados.