Formatos de arquivo do GTA V e FiveM: o que cada asset faz

Você baixou um carro, um pack de roupas ou um mapa, abriu o zip e deu de cara com um monte de arquivos .yft, .ytd, .ytyp e .meta. O GTA V roda na engine RAGE da Rockstar, e a RAGE divide cada asset em vários arquivos especializados: um para o mesh, um para as texturas, um para a collision e um para os dados que dizem ao jogo como usar tudo isso. Depois que você entende o que cada extensão faz, quase qualquer asset de FiveM fica fácil de ler, corrigir e instalar.

Esta página é uma referência dos formatos de arquivo do GTA V e do FiveM, e responde de vez o que é arquivo ydr, ytd, yft e companhia. Use a tabela para identificar um arquivo rapidinho e depois pule para a seção do tipo de asset.

Resumindo: .ydr, .ydd e .yft são modelos 3D, .ytd guarda texturas, .ytyp e .ymap definem e posicionam objetos de mapa, .ybn é collision, .ycd é animação, e os .meta são dados em texto puro (handling, cores, status de armas). No FiveM, arquivos de modelo, textura, mapa e animação vão soltos na pasta stream/ de um resource, e os .meta são carregados com linhas data_file no fxmanifest.lua.

Tabela de referência rápida

Um resumo rápido das ferramentas:

• CodeWalker é um visualizador de mapas e explorador de arquivos gratuito para GTA V. Ele navega pelos arquivos do jogo, mostra preview de modelos, edita mapas e converte arquivos binários para XML e de volta.
• Sollumz é um add-on gratuito para Blender que importa e exporta modelos, collisions, mapas e animações do GTA V. Ele trabalha tanto com arquivos binários nativos (.ydr) quanto com o XML do CodeWalker (.ydr.xml).
• OpenIV é o velho conhecido navegador e editor de arquivos, hoje usado principalmente para olhar dentro de .rpf e trocar texturas.

Modelos: .ydr, .ydd e .yft

Os três são modelos 3D compilados. Eles têm meshes, níveis de LOD (versões com menos detalhe mostradas de longe), configurações de shader e referências a texturas. A diferença é quantos modelos cada um guarda e como eles se comportam.

.ydr – drawable

Um .ydr é um único modelo estático. A maioria dos props é .ydr: uma cadeira, uma placa, uma máquina de venda. Modelos de arma também são .ydr (por exemplo w_pi_pistol.ydr). Um .ydr pode ter a própria collision embutida, e é assim que props pequenos ficam sólidos sem precisar de um .ybn separado.

Se você quer props custom sem modelar na mão, o gerador 3D da BLDR transforma um prompt, uma imagem ou um GLB em arquivos .ydr, .ytd e .ytyp empacotados como resource de FiveM. Para o fluxo completo, veja props custom no FiveM.

.ydd – drawable dictionary

Um .ydd junta vários drawables em um arquivo só. Você encontra eles principalmente em peds: cada peça de roupa (uma jaqueta, um par de tênis, um corte de cabelo) é um .ydd que forma par com um .ytd de mesmo nome base. Packs de roupa trazem dezenas ou centenas deles. Packs de roupas para FiveM explica como eles são nomeados e como fazer o stream.

.yft – fragment

Um .yft é um modelo com hierarquia de física: partes que podem se mexer, se soltar ou amassar. Veículos são sempre .yft, porque as portas abrem, os para-choques caem e os vidros estouram. Objetos quebráveis do mundo, como grades e postes, também usam .yft.

Veículos geralmente vêm em dupla: mycar.yft para o modelo normal e mycar_hi.yft para a versão de alto detalhe mostrada de perto.

Texturas: .ytd

Um .ytd (texture dictionary) é um contêiner de imagens, normalmente comprimidas em DDS: cores diffuse, normal maps, specular maps e por aí vai. Os modelos referenciam as texturas pelo nome, e o jogo procura elas no dicionário correspondente.

Padrões comuns:

• mycar.ytd e mycar+hi.ytd para as texturas normais e de alto detalhe de um veículo.
• Um .ytd por peça de roupa, com o mesmo nome do .ydd.
• Um .ytd compartilhado para um conjunto de props, referenciado pelo .ytyp.

As texturas também são a origem da maioria dos problemas de streaming. Uma textura 4K num prop pequeno custa memória e tempo de download para todo player. Otimizando assets de FiveM explica como deixar no tamanho certo.

Mapas: .ytyp, .ymap e .ynv

.ytyp – definições de archetypes

Um .ytyp descreve o que um objeto é, não onde ele está. Cada entrada (um archetype) nomeia um modelo e lista o texture dictionary, a distância de LOD, a bounding box e as flags. Sem um archetype, o jogo não sabe direito como carregar e desenhar um modelo custom.

Nos interiores, o .ytyp também guarda a definição do MLO: rooms, portals entre as rooms e entity sets que os scripts podem ligar e desligar. É por isso que todo MLO vem com um. Veja o que é MLO no FiveM para os detalhes.

.ymap – posicionamentos no mapa

Um .ymap diz onde as coisas ficam. Ele lista entidades pelo nome do archetype com posição e rotação, e também pode ter car generators, occluders, LOD lights e modificadores de timecycle. Um mapa custom normalmente é um .ymap que posiciona objetos definidos em um .ytyp. Edições de mapa que removem ou movem objetos do jogo base também ficam em arquivos .ymap.

.ynv – navmesh

Um .ynv é uma malha de navegação: as superfícies andáveis que os peds da IA usam para se locomover. Você quase nunca mexe nisso, a não ser que faça mapas externos grandes e queira que os NPCs andem por eles.

Collision: .ybn

Um .ybn guarda a collision estática (bounds): formas e meshes simplificados que a engine de física usa para decidir onde você pode pisar, onde dá para bater e o que dá para atravessar com tiro. A geometria de collision também carrega dados de material, que controlam som de passos, impacto de bala e aderência dos pneus.

Mapas e MLOs geralmente têm um ou mais .ybn junto dos modelos. Se você atravessa uma parede ou cai pelo chão, o .ybn está faltando, não está fazendo stream ou não bate com o modelo.

Animações: .ycd

Um .ycd é um clip dictionary: um conjunto de clips de animação guardados sob um mesmo nome de dicionário. Os scripts carregam o dicionário com RequestAnimDict e depois tocam um clip dele pelo nome. Menus de emote, idles custom e danças são todos distribuídos como arquivos .ycd em stream.

A ferramenta /mocap da BLDR transforma um vídeo de 1 a 30 segundos em uma animação .ycd com um clip chamado anim. Emotes custom no FiveM mostra passo a passo como adicionar um ao menu de emotes.

Áudio: .awc

Um .awc (audio wave container) guarda dados de som. Sons de motor custom e outros mods de áudio vêm com um ou mais arquivos .awc, geralmente junto com configuração de áudio baseada em .rel. No FiveM, uma pasta de wave packs é carregada com o tipo de data file AUDIO_WAVEPACK. Modding de áudio é um assunto profundo à parte; se um asset vier com isso, siga à risca as instruções do criador.

Dados e metadata: .meta, .ymt e .rpf

Arquivos .meta

Os .meta são XML puro que você abre em qualquer editor de texto. É neles que ficam os dados de gameplay:

Os nomes dentro desses arquivos precisam bater entre si. O handlingId do vehicles.meta tem que bater com um handlingName do handling.meta, e o modelName tem que bater com o nome do arquivo .yft. A maioria dos problemas de "o veículo spawna mas anda errado" ou "o veículo não spawna" é uma divergência aqui.

.ymt

Um .ymt é um arquivo de metadata binária. Em packs de roupa, o .ymt guarda os dados de variação do ped: quais drawables e texturas existem para cada slot de roupa. Ele geralmente tem o nome do modelo do ped e do pack, por exemplo mp_m_freemode_01_mypack.ymt, e faz stream junto com os .ydd e .ytd. O CodeWalker consegue converter ele para XML para você inspecionar.

.rpf – arquivos compactados

Um .rpf é o formato de arquivo compactado da RAGE, parecido com um zip. O jogo base vem com tudo dentro de RPFs, e mods de single player normalmente são instalados editando esses arquivos com o OpenIV.

O FiveM funciona diferente: os resources fazem stream de arquivos soltos. Se um download só traz um .rpf (muitas vezes um dlc.rpf feito para single player), abra no OpenIV ou no CodeWalker, extraia os modelos, texturas e arquivos meta, e monte tudo de novo como um resource de FiveM.

Exportações .xml

O CodeWalker consegue exportar a maioria dos formatos binários para XML legível (mycar.yft.xml, prop.ydr.xml, map.ymap.xml) e importar de volta. O Sollumz exporta no mesmo formato XML. Você pode encontrar esses arquivos em fontes de assets ou tutoriais. Eles são um formato de edição: converta de volta para binário antes de fazer stream no FiveM.

Como tudo se junta em um resource

Todo asset de FiveM é um resource: uma pasta com um fxmanifest.lua. Modelos, texturas, mapas e animações vão em stream/ e carregam automaticamente. Os arquivos meta ficam em outro lugar (normalmente data/) e são registrados com uma entrada em files mais uma linha data_file. Se você está começando com resources, como criar um servidor de FiveM cobre o básico.

Exemplo: um veículo add-on

fx_version 'cerulean'
game 'gta5'

files {
  'data/vehicles.meta',
  'data/handling.meta',
  'data/carvariations.meta',
  'data/carcols.meta',
}

data_file 'HANDLING_FILE' 'data/handling.meta'
data_file 'VEHICLE_METADATA_FILE' 'data/vehicles.meta'
data_file 'CARCOLS_FILE' 'data/carcols.meta'
data_file 'VEHICLE_VARIATION_FILE' 'data/carvariations.meta'

O nome de spawn é o modelName do vehicles.meta, que deve bater com mycar.yft.

Exemplo: um prop custom com posicionamento

fx_version 'cerulean'
game 'gta5'

this_is_a_map 'yes'

data_file 'DLC_ITYP_REQUEST' 'stream/my_props.ytyp'

O .ydr é o modelo, o .ytd são as texturas dele, o .ytyp registra my_bench como archetype e o .ymap posiciona ele no mundo. O this_is_a_map avisa o FiveM que o resource tem dados de mapa. Se você só quer spawnar o prop por script, pode tirar o .ymap e o this_is_a_map.

Perguntas frequentes

Posso só arrastar arquivos .yft ou .ydr para o meu servidor?

Só dentro de um resource. Coloque eles na pasta stream/ de um resource, adicione um fxmanifest.lua e dê ensure no resource pelo server.cfg. Veículos também precisam dos arquivos meta registrados com data_file, senão não spawnam.

Qual a diferença entre .ydr, .ydd e .yft?

Um .ydr é um único modelo estático, um .ydd é um dicionário com vários modelos (principalmente roupas e partes de ped), e um .yft é um modelo com partes quebráveis ou móveis (veículos e objetos destrutíveis).

Por que minhas texturas somem ou ficam roxas?

O modelo não está achando o texture dictionary dele. Confira se o .ytd está em stream/, se o nome bate com o que o modelo ou o .ytyp espera, e se ele não está tão pesado a ponto de falhar no stream.

Preciso do OpenIV para FiveM?

Geralmente não. Resources de FiveM usam arquivos soltos, então você só precisa de uma ferramenta de arquivos para extrair conteúdo de um .rpf. O CodeWalker resolve isso, além de mapas e conversão para XML, e o Sollumz cuida da edição no Blender.

Para que serve um .ytyp se eu já tenho o .ydr?

O .ydr é o modelo em si. O .ytyp diz ao jogo como tratar ele: quais texturas usar, até que distância ele continua visível e qual o tamanho dele. Mapas e MLOs dependem dele, e props custom ficam muito mais confiáveis com um.