Guia CodeWalker: Download, Configuração e Edição de Mapas para FiveM

CodeWalker permite que você explore o mundo do GTA V, inspecione assets do jogo e edite dados de mapa para seus projetos FiveM. Criado por dexyfex, ele combina um visualizador de mundo 3D com navegação de arquivos e ferramentas de edição de mapa. Comece pela página de download do CodeWalker do autor, não um executável reempacotado de um site não relacionado. (Mods GTA5)

Para um primeiro projeto, mantenha o objetivo pequeno: coloque um objeto existente em um novo mapa, empacote-o como um recurso FiveM e confirme que ele aparece corretamente no jogo. Isso lhe dará um processo de trabalho antes de você lidar com construções personalizadas, interiores ou alterações no mapa original.

Este guia cobre o download do CodeWalker, sua configuração, a criação do seu primeiro YMAP e o teste do resultado.

Baixe o CodeWalker da fonte correta

Existem três pontos de partida úteis, com propósitos diferentes:

Fonte	Para que usá-lo
CodeWalker em mods do GTA5	Download publicado pelo autor e links para a comunidade do projeto
Repositório oficial do CodeWalker GitHub	Código-fonte, documentação e rastreamento de problemas
CodeWalker Discord oficial, vinculado à página do autor	Builds de desenvolvimento e instruções específicas de lançamento

O Guia oficial de ferramentas Cfx.re direciona os usuários para o CodeWalker Discord #releases canal. Siga o convite da página do autor ou a documentação Cfx.re em vez de uma mensagem não solicitada oferecendo um download. (Mods GTA5)

Uma fonte GitHub ZIP não é o mesmo que um aplicativo pronto para uso. O repositório é útil para desenvolvedores, mas baixar seu código-fonte não oferece a um iniciante o mesmo pacote de instalação que uma versão compilada. Use a compilação fornecida pelo autor para este tutorial. (GitHub)

Guarde o arquivo baixado e anote a compilação que você instalar. Quando a interface de um tutorial for diferente da sua, verifique a compilação antes de presumir que um recurso desapareceu.

Verifique os requisitos e a sua edição GTA alvo

O repositório do CodeWalker lista uma instalação para PC do GTA V, um ambiente Windows de 64 bits e gráficos compatíveis com DirectX 11/Shader Model 4.0 entre seus requisitos. (GitHub)

Preste atenção especial ao runtime. Descrições mais antigas mencionam versões anteriores do .NET Framework, enquanto o projeto fonte atual tem como alvo .NET Framework 4.8. Siga os requisitos fornecidos com a sua build baixada; a Microsoft fornece o runtime oficial do .NET Framework 4.8 para download. (GitHub)

Antes de trabalhar nos assets, decida também se o projeto tem como alvo GTA V Legacy ou GTA V Enhanced. Use uma versão do CodeWalker que suporte a instalação que você está abrindo e mantenha esse alvo consistente em todo o seu fluxo de trabalho.

Cfx.re fornece um guia de integração aprimorado e o Ferramenta de conversão Alchemist para ativos Legacy relevantes. Não assuma que um pacote Legacy se torna compatível com Enhanced apenas porque o CodeWalker pode exibi-lo. (Documentação Cfx)

Para projetos que suportam ambas as edições, mantenha pastas de saída separadas e teste cada pacote no servidor e cliente pretendidos.

Configure o CodeWalker e carregue GTA V

Extraia o arquivo completo da aplicação para uma pasta de ferramentas dedicada, por exemplo:

C:\Tools\CodeWalker\

Execute CodeWalker.exe da pasta extraída. Na primeira inicialização, selecione a raiz da sua instalação do GTA V quando solicitado — não a pasta do aplicativo FiveM ou um diretório de recursos do servidor. Permita que o processo inicial de carregamento termine antes de iniciar uma edição. Estas são as etapas de inicialização descritas nos tutoriais de assets do Cfx.re. (Documentação Cfx)

Quando o mundo aparecer, verifique as configurações de DLC no painel direito. O tutorial do Cfx.re ativa DLCs e seleciona o nível mais recente disponível para seu exemplo; para o seu projeto, considere o conteúdo do jogo disponível no servidor de destino em vez de copiar cegamente a configuração de patch de um tutorial antigo. (Documentação Cfx)

Mantenha seus arquivos de jogo originais fora do fluxo de trabalho de edição sempre que possível. Para o primeiro exercício abaixo, salve seu novo mapa em uma pasta de projeto separada.

Entenda os arquivos antes de editá-los

Um projeto de mapa geralmente é uma coleção de arquivos com trabalhos diferentes.

Arquivo	O que ele contém
.cwproj	Informações do projeto CodeWalker e referências aos arquivos de trabalho
.rpf	Um arquivo contendo GTA V assets e dados
.ymap	Dados do mapa, incluindo posicionamentos de entidades no mundo
.ytyp	Definições de arquétipos descrevendo objetos que podem ser posicionados
.ydr	Um drawable: um modelo e dados de renderização associados
.ytd	Um dicionário de texturas
.ybn	Dados de colisão e limites

Essas distinções são descritas na documentação e implementação do projeto do CodeWalker.GitHub)

A distinção a ser lembrada é definição versus posicionamento: um YTYP descreve um arquétipo, enquanto um YMAP pode posicionar uma instância dele.

Um MLO adiciona uma estrutura interior, incluindo informações de sala e portal; não é simplesmente outro nome para um YMAP. Um fluxo de trabalho interior pode usar ambos os tipos de arquivo. Nosso MLO vs YMAP guia explica a relação, enquanto a documentação de interiores do Sollumz mostra como essas definições são construídas.

Navegue pela Visão Geral do Mundo e inspecione objetos

Use WASD para se mover, clique com o botão esquerdo e arraste para olhar ao redor, e a roda do mouse para ajustar a velocidade de movimento. Expanda o painel do lado direito e pressione T para abrir a barra de ferramentas principal. (Documentação Cfx)

Ative a seleção de entidades e clique com o botão direito em um objeto para inspecioná-lo. Use os controles de mover, girar e dimensionar da barra de ferramentas ao editar; estes são mais fáceis de seguir inicialmente do que atalhos cujo comportamento muda com o modo de edição. (GitHub)

Antes de mover qualquer coisa, inspecione alguns objetos existentes. Copie o nome do arquétipo de um objeto e anote sua posição. Cfx.re's tutorial de exploração de assets também explica como encontrar o modelo correspondente no RPF Explorer. (Documentação Cfx)

Por enquanto, inspecione o objeto original sem alterá-lo. Você criará uma colocação separada em seu próprio YMAP.

Crie um projeto que você possa recuperar

Use um espaço de trabalho que mantenha os arquivos editáveis separados do pacote que você implanta. Por exemplo:

rpcrate_map_test/
├── source/
│   ├── rpcrate_map_test.cwproj
│   └── rpcrate_map_test.ymap
├── build/
│   └── rpcrate_map_test/
│       ├── fxmanifest.lua
│       └── stream/
└── backups/

Abra a Janela do Projeto, crie um projeto e salve-o em source/ antes de adicionar seus arquivos de mapa.

Faça backup de toda a pasta de origem, não apenas dos .cwproj. projetos do CodeWalker referenciam arquivos por caminho; o arquivo do projeto não é um arquivo autocontido contendo todos os ativos. (GitHub)

Use build/ para o recurso que você pretende testar. Copie as saídas salvas nele deliberadamente, em vez de usar o servidor ativo stream pasta como seu único diretório de trabalho.

Antes de uma edição substancial, crie um backup com data ou um ponto de verificação de controle de versão. Registre a versão do CodeWalker e a edição GTA de destino junto com o projeto.

Crie seu primeiro YMAP no CodeWalker

Escolha um objeto estático simples, como um banco ou um pequeno item de mobiliário urbano. Coloque-o em uma área aberta onde você possa encontrá-lo e inspecioná-lo facilmente.

Evite começar com a substituição de um prédio inteiro. O primeiro exercício deve responder a uma pergunta: você consegue levar uma colocação do CodeWalker para um recurso FiveM funcional?

1. Adicione um novo YMAP e entidade

Na Janela do Projeto, escolha Arquivo → Novo → Arquivo Ymap.

Selecione o novo YMAP, então escolha Ymap → Nova Entidade. Defina a entidade Archetype de Cfx.re map-placement tutorial. (Documentação Cfx)

Use um nome de mapa distintivo, como rpcrate_map_test, em vez de reutilizar o nome de um mapa de jogo existente.

2. Posicione o objeto

Mova e gire a nova entidade para o local. Para este exercício, deixe sua escala inalterada e registre as coordenadas.

Verifique se você está editando a entidade dentro do seu novo YMAP, não o objeto original que você inspecionou.

Mantenha o primeiro mapa em uma única colocação. Assim que funcionar no jogo, adicione o resto da sua cena em pequenos grupos.

3. Calcular e salvar

Selecione o YMAP e execute Calcular Extensões e Calcular Todas as Bandeiras. Salve o mapa como rpcrate_map_test.ymap, então salve o projeto.

Os fluxos de trabalho Cfx.re e Sollumz incluem o cálculo das flags e extensões do mapa antes da implantação. Repita essa etapa após alterações adicionais de posicionamento. (Documentação Cfx)

4. Gere o manifesto do mapa

Na Janela do Projeto, use Ferramentas → Gerador de Manifesto, gere o manifesto e salve o resultado _manifest.ymf usando o fluxo de exportação da sua compilação. Inclua-o com os arquivos transmitidos do mapa. Ambos os tutoriais oficiais incluem esta etapa de geração. (Documentação Cfx)

_manifest.ymf e fxmanifest.lua são arquivos diferentes. O arquivo gerado pertence ao fluxo de trabalho de ativos do mapa; fxmanifest.lua descreve o recurso FiveM. Você criará isso a seguir. (Documentação Cfx)

Empacote o mapa como um recurso FiveM

Para este exercício, organize o recurso exportado assim:

resources/
└── [maps]/
    └── rpcrate_map_test/
        ├── fxmanifest.lua
        └── stream/
            ├── rpcrate_map_test.ymap
            └── _manifest.ymf

Crie fxmanifest.lua com:

fx_version 'cerulean'
game 'gta5'

this_is_a_map 'yes'

Isso segue a estrutura básica de mapa-recurso documentada por Cfx.re. A this_is_a_map declaração identifica o recurso como um mapa e aciona o recarregamento do armazenamento de mapas quando ele é carregado. (Documentação Cfx)

Para um tutorial sobre a sintaxe do manifesto, veja nosso Guia fxmanifest.lua FiveM.

Adicione um YTYP apenas quando o projeto usar um

Para arquétipos personalizados, inclua seu YTYP exportado e os ativos personalizados necessários. Registre o YTYP explicitamente no manifesto, usando seu nome de arquivo real:

files {
    'stream/rpcrate_map_test.ytyp'
}

data_file 'DLC_ITYP_REQUEST' 'stream/rpcrate_map_test.ytyp'

O data_file declaração e DLC_ITYP_REQUEST tipo são cobertos pelas referências de recurso e arquivo de dados do Cfx.re. Não copie este exemplo inalterado quando seu arquivo tiver um nome diferente. (Documentação Cfx)

Uma colocação usando um arquétipo de jogo existente e disponível é diferente de introduzir um personalizado. Não crie um YTYP vazio apenas para corresponder a um exemplo de pasta.

Mantenha os arquivos de origem fora do pacote implantado

Retenha os .cwproj, projetos do Blender e backups em seu espaço de trabalho. Implante os arquivos necessários para o recurso, não a pasta de trabalho inteira.

Há uma distinção de formato útil: documentos Cfx.re suportam YMAP no formato XML e arquivos YTYP quando nomeados com o apropriado .ymap ou .ytyp extensão. Ele também alerta que o analisador do jogo pode se comportar de maneira diferente do analisador do CodeWalker. Esse é um caminho específico suportado — não uma regra geral de que renomear qualquer ativo XML o converte em um arquivo do jogo.Documentação Cfx)

Para o primeiro exercício, use a saída de mapa salva do CodeWalker de forma consistente, em vez de misturar métodos de exportação.

Carregue o recurso e teste-o em FiveM

Use um servidor de teste isolado, com mapas não relacionados afetando o mesmo local desativados.

Após copiar o recurso para o diretório de recursos do servidor, execute estes comandos no console do servidor:

refresh
ensure rpcrate_map_test

refresh escaneia o diretório de recursos. ensure inicia o recurso nomeado quando parado, ou o reinicia quando já está em execução. Estes são comandos do servidor, não instruções para colar no console F8 do jogador. (Documentação Cfx)

Para inícios de servidor subsequentes, adicione isto à configuração relevante:

ensure rpcrate_map_test

Para compilações de teste posteriores, copie os arquivos atualizados e reinicie o recurso pretendido. O referência oficial de comandos do servidor explica os comandos disponíveis de início, parada e reinício. (Documentação Cfx)

Verifique mais do que apenas se o objeto aparece

Use este teste de aceitação antes de expandir o mapa:

1. Colocação: Visite as coordenadas registradas. Verifique a posição, rotação e alinhamento de vários ângulos.
2. Colisão: Ande e entre no objeto onde for apropriado. Verifique se há barreiras inesperadas ou colisão ausente.
3. Transmissão: Saia da área e aproxime-se novamente. Repita de outra direção, depois reconecte.
4. Isolamento: Pare o recurso de teste, confirme a mudança esperada e, em seguida, ative-o novamente. Verifique os logs do cliente e do servidor em busca de erros.

Para uma cena maior, repita a mesma rota de direção ou caminhada com o recurso ativado e desativado. Mantenha o clima, a posição da câmera e outras condições o mais semelhantes possível.

Salve este primeiro pacote de trabalho como sua linha de base.

Edite um mapa existente sem perder o controle das alterações

Criar um posicionamento adicional e modificar o mundo original são tarefas diferentes.

Quando a Janela do Projeto está aberta, editar uma entidade de mundo existente pode adicionar seu YMAP proprietário ao projeto. Esse pode ser um arquivo muito maior do que o único objeto que você pretendia alterar. Inspecione a árvore do projeto antes de salvar. (GitHub)

Antes de editar um mapa existente, anote seu nome de arquivo, localização de origem e propósito pretendido. Trabalhe em uma cópia recuperável e revise quais arquivos seu recurso final substituirá ou dependerá.

Não presuma que a remoção de um objeto visível remove todos os componentes associados. A colisão do mundo pode residir em arquivos YBN separados, enquanto representações distantes podem pertencer a uma hierarquia LOD. Estes exigem sua própria inspeção e alterações.Documentação Cfx)

Para um primeiro projeto, evite modificar objetos não relacionados apenas porque eles aparecem no mesmo YMAP.

Use Blender e Sollumz para modelos personalizados e MLOs

Colocar assets existentes é um fluxo de trabalho. Criar um novo edifício ou remodelar um interior requer trabalho de modelagem e exportação também.

A série de assets da Cfx.re usa Blender com Sollumz ao lado do CodeWalker. Siga a documentação do Sollumz para uma instalação compatível e o fluxo de trabalho de exportação de assets apropriado. (docs.fivem.net)

Para um MLO, o modelo é apenas parte do trabalho. Você também precisa definir o arquétipo do interior, salas, conexões de portal e atribuições de entidade, e então posicionar o interior no mundo. Esses relacionamentos são descritos nos tutoriais de interior do Sollumz.

Comece com um cômodo pequeno e uma entrada. Teste o chão, as paredes e a entrada antes de adicionar detalhes decorativos. Em seguida, verifique a visibilidade ao entrar, sair e olhar pela entrada de ambos os lados.

Nosso guia de criação de MLO FiveM cobre o processo mais amplo de modelagem, colisão, empacotamento e validação.

Solucione problemas comuns do CodeWalker e de mapas

O CodeWalker não consegue encontrar GTA V ou o mundo permanece em branco

Verifique novamente a raiz de instalação selecionada, a edição de destino e a build baixada. Confirme que você extraiu o pacote completo do aplicativo.

Permita que o carregamento inicial termine e, em seguida, investigue qualquer mensagem de erro real. Para conteúdo de DLC ausente ou nomes de ativos não resolvidos, revise as etapas de DLC e tabela de nomes no guia de configuração do CodeWalker do Cfx.re. (Documentação Cfx)

A edição existe no CodeWalker, mas não no recurso exportado

Rastreie o arquivo através do fluxo de trabalho: o YMAP referenciado pelo projeto, seu local salvo, a cópia em build/, e a cópia no servidor de teste.

Compare nomes de arquivos, tempos de modificação e tamanhos de arquivos. Para uma comparação exata, compare os hashes dos arquivos. Não presuma que salvar o projeto copiou o mapa mais recente para o recurso do servidor.

O servidor ainda mostra a versão anterior

Confirme que os arquivos atualizados chegaram ao diretório de recursos correto e que você reiniciou o recurso pretendido. Verifique se há outro recurso habilitado contendo um mapa sobreposto.

Teste uma conexão nova após a reinicialização. Evite alterar arquivos, limpar caches e desabilitar vários recursos simultaneamente; você precisa saber qual ação muda o resultado.

Objetos desaparecem à distância

Revise a configuração de LOD relevante, a hierarquia do mapa e as informações de streaming antes de aumentar todos os valores de distância.

Cfx.re's Tutorial de LOD explica a relação entre modelos detalhados, versões simplificadas e sua hierarquia YMAP. Verifique essas relações em relação ao seu projeto em vez de tratar o desaparecimento como um problema de configuração única. (Documentação Cfx)

Uma parede invisível permanece, ou o jogador cai através de uma superfície

Inspecione a colisão separadamente da geometria visível. Cfx.re documenta arquivos de colisão do mundo e colisão incorporada em modelos. Verifique se a colisão necessária existe, carrega e se alinha com o ativo colocado. (Documentação Cfx)

Nosso Guia de solução de problemas de parede invisível FiveM fornece um fluxo de trabalho focado para barreiras inesperadas.

CodeWalker trava durante uma edição

O autor descreve o CodeWalker como um trabalho em andamento e adverte que travamentos podem ocorrer. (GitHub)

Reabra o último projeto funcional e repita a menor alteração que reproduz a falha. Registre a build, a edição de destino, o arquivo afetado e a mensagem de erro. Mantenha o trabalho de recuperação separado do backup original.

Termine o primeiro mapa antes de torná-lo maior

Seu primeiro marco é um projeto salvo e um pequeno recurso que carrega corretamente, sobrevive a uma reconexão e pode ser removido sem perturbar outros mapas.

Mantenha essa versão funcional. Adicione o próximo objeto, recurso personalizado ou interior, e repita o mesmo teste.

Um fluxo de trabalho confiável no CodeWalker significa saber qual arquivo você alterou, qual arquivo você implantou e como restaurar a versão anterior.