Livery Mapper

Aplicativo local para preparar veículos do GTA V/FiveM para receber liveries. Ele lê um ZIP com arquivos YFT e YTD, remapeia a carroceria na segunda camada UV e devolve uma resource FiveM pronta para personalização.

O que funciona

• aceita um ZIP de até 500 MB com um modelo YFT base, o YFT _hi opcional e um YTD;
• identifica geometrias compatíveis de pintura veicular e projeta a carroceria em seis vistas;
• aplica o shader de livery e a segunda UV aos modelos base e _hi encontrados;
• preserva o YTD original e acrescenta uma textura transparente <modelo>_sign_1;
• gera livery_template.png em 2048 × 2048, com wireframe e vistas identificadas;
• preserva arquivos .meta e .lua existentes, adicionando FLAG_HAS_LIVERY ao vehicles.meta quando necessário;
• cria os metadados mínimos quando eles não existem e entrega tudo em <modelo>_livery.zip;
• roda em localhost; o ZIP enviado é processado em uma pasta temporária e o original não é alterado;
• possui interface web local e aplicativo desktop para Windows.

Limitações atuais

• o processamento de YFT/YTD depende do CodeWalker, que precisa ser obtido separadamente;
• somente geometrias com shader de pintura veicular compatível podem ser remapeadas;
• modelos protegidos, corrompidos ou com estrutura fora do padrão podem falhar;
• a projeção automática é um ponto de partida: acabamentos profissionais podem exigir ajustes manuais no modelo ou na arte;
• o empacotamento desktop está configurado para Windows x64;
• o projeto não inclui arquivos de veículos, conteúdo do GTA V nem executáveis prontos no repositório.

Requisitos para desenvolvimento

• Windows 10/11 x64;
• Node.js 22.13 ou mais recente;
• .NET SDK 8;
• Git.

Preparação

Clone este projeto e instale as dependências:

git clone https://github.com/YgorLeal/livery-mapper.git
cd livery-mapper
npm install

Baixe o CodeWalker no caminho esperado pelo projeto:

git clone https://github.com/dexyfex/CodeWalker.git .vendor/CodeWalker
npm run engine:build

O CodeWalker não faz parte deste repositório nem é coberto pela licença MIT do Livery Mapper. Consulte THIRD_PARTY_NOTICES.md antes de usar ou distribuir builds.

Executar a interface web local

npm run dev

Abra http://localhost:3000. O servidor de processamento usa http://127.0.0.1:3100.

Executar ou empacotar o desktop

# abre o aplicativo em modo de desenvolvimento
npm run desktop:dev

# gera a versão portátil para Windows
npm run desktop:portable

Os artefatos são criados em release/ e não são versionados.

Como usar

1. Coloque o YFT base, o YFT _hi (se existir), o YTD e os metadados do veículo em um ZIP.
2. Selecione ou arraste o ZIP para a interface.
3. Clique em Mapear e baixar resource.
4. Edite livery_template.png sem alterar suas dimensões.
5. Importe a arte como <modelo>_sign_1 no YTD gerado e instale a pasta do modelo como uma resource FiveM.

O ZIP final inclui instruções específicas em README_LIVERY.txt.

Estrutura

• app/: interface React/Next;
• electron/ e electron-renderer/: shell desktop;
• server.mjs: API local, validação, montagem da resource e geração do template;
• engine/: utilitário .NET responsável por ler e escrever YFT/YTD;
• meta-templates.mjs: metadados FiveM gerados quando o ZIP não os fornece.

Privacidade e segurança

O serviço escuta apenas em 127.0.0.1, limita o upload a 500 MB, ignora caminhos inseguros dentro do ZIP e remove os arquivos temporários ao fim do processamento. Ainda assim, trate arquivos de terceiros como não confiáveis e mantenha as dependências atualizadas.

Licença e marcas

O código original deste projeto é distribuído sob a Licença MIT. Dependências e materiais de terceiros permanecem sujeitos aos termos de seus respectivos autores; veja THIRD_PARTY_NOTICES.md.

Este é um projeto independente, não afiliado nem endossado pela Rockstar Games, Take-Two Interactive, Cfx.re ou pelos autores do CodeWalker. GTA V, FiveM e marcas relacionadas pertencem aos seus respectivos titulares.