Guia do Universal Modder

Universal Modder é um conjunto de ferramentas de código aberto que ajuda agentes de programação com IA a pesquisar, criar e testar mods para jogos de PC. Ele reúne habilidades, uma CLI em Python chamada um, registros sobre jogos específicos e integração com fal para gerar recursos. O projeto original é rehan-remade/universal-modder no GitHub (em inglês).

Comece com uma pequena alteração em um jogo que você possui: identifique o motor e o carregador de mods, proteja um save de teste, implemente a função com arte provisória e confira o resultado dentro do jogo. “Universal” descreve a variedade de abordagens, não uma garantia para todos os jogos e versões.

Fontes verificadas em 9 de outubro de 2026, no commit 8370faa e na versão 0.2.0 do pacote. Este guia se baseia na documentação e no código-fonte. Não executamos os mods de exemplo nem testamos um fluxo completo com a OmniaKey. As fontes externas estão em inglês.

O que vem no kit

O README do projeto diferencia estes componentes:

O repositório apresenta caminhos para Claude Code, Codex, Cursor, Gemini CLI, Copilot e OpenCode. São integrações com agentes, não promessas de que todas as operações funcionem em qualquer sistema operacional. As ferramentas de controle de jogos Windows usam Windows diretamente ou por meio do WSL.

Como instalar no Claude Code

O README lista Git, Python 3.10 ou superior e ffmpeg como pré-requisitos, além de recomendar uv. Blender é necessário para renderizar modelos 3D em sprites. Prepare os recursos exigidos pelo seu projeto.

Digite os dois comandos dentro do Claude Code:

/plugin marketplace add rehan-remade/universal-modder
/plugin install universal-modder@universal-modder

São comandos de plugins do Claude Code, não do shell do sistema. Confira o código e as permissões solicitadas antes de ativar. Para outro agente, siga a seção correspondente no README original.

O projeto fornece um iniciador da CLI para plugins e repositórios clonados. Se um terminal separado não encontrar um, a instalação independente documentada é:

uv tool install git+https://github.com/rehan-remade/universal-modder
um --help

Isso instala a CLI a partir do repositório. Não configura, por si só, o agente de programação nem a conta fal. Conferimos os comandos nas fontes, mas não os executamos para este artigo.

Examine o jogo antes de alterar arquivos

Troque Terraria pelo nome do jogo ou pela pasta de instalação:

um scan --list
um kb search "Terraria"
um scan "Terraria" --json

Segundo o guia de reconhecimento, o scanner lê arquivos e informa indícios do motor, carregadores instalados, locais de saves e possíveis abordagens. Se o jogo não aparecer na biblioteca, informe a pasta diretamente.

A análise ajuda a planejar, mas não comprova segurança ou compatibilidade. Proteções podem estar fora da pasta do jogo e launchers podem confundir a identificação do motor. Consulte também a documentação atual do carregador da comunidade e a política de mods do jogo.

Peça ao agente para registrar em MODDING_PLAN.md as versões exatas do jogo e do carregador, os caminhos dos saves e logs, as alterações e a forma de restaurar. Guarde o progresso em MODLOG.md. Prefira um carregador conhecido ou uma interface oficial de mods quando eles atenderem à ideia.

Um primeiro pedido com critérios de conclusão

Escolha uma função pequena e visível. Este é um modelo de pedido criado para o guia, não um mod testado:

No meu ambiente local de testes do Terraria, planeje um novo item decorativo para a versão instalada do tModLoader. Examine primeiro o jogo e o carregador. Use arte provisória e um mundo descartável. Antes de alterar arquivos, liste os caminhos afetados e os passos de backup e restauração. Explique como obter o item, conferir o efeito no jogo e remover o mod. Pergunte antes de gerar recursos pagos ou publicar qualquer coisa.

O fluxo do projeto recomenda concluir uma pequena função com recursos provisórios antes de ampliar o trabalho. Isso pode virar cinco verificações:

1. Carregamento: o jogo inicia com o carregador previsto e o log identifica o mod.
2. Aparência: o item ou a alteração aparece na cena escolhida.
3. Comportamento: o resultado atende ao pedido; compilar sem erros não basta.
4. Persistência: salvar e recarregar o mundo de teste funciona como esperado.
5. Restauração: desativar o mod e restaurar o backup devolve o ambiente ao estado previsto.

Só então invista nos sprites finais, no áudio e no vídeo de apresentação. Uma imagem gerada ou um build concluído não comprova, sozinho, a compatibilidade durante o jogo.

Quais jogos têm exemplos?

Os exemplos são pontos de partida vinculados a versões. Os testes relatados pelos autores não substituem a verificação no seu computador.

• Terraria / tModLoader: Fal Arsenal tem origem em um projeto para um jogador com Terraria 1.4.4 e tModLoader 2026.07. O README declara que o multiplayer não foi testado. Use um mundo separado.
• Age of Empires II DE: o exemplo de civilização inclui arte gerada e conversão de sprites. Ele ocupa um espaço de civilização existente, sem demonstrar a possibilidade de adicionar novos espaços livremente.
• Minecraft × GTA V: combina dois jogos em execução no modo história de GTA V. O teste documentado usa GTA V Legacy no Steam, build 3889. Não extrapole para GTA Online ou outras edições.

Avalie a compatibilidade nesta ordem: guia do motor → exemplo com jogo e versão → seu teste dentro do jogo. Um guia de Unity ou Unreal não certifica todos os títulos que usam aquele motor.

É gratuito? Precisa de fal?

O código do kit usa a licença MIT. Um projeto completo ainda pode ter três grupos de custos: acesso ao modelo de programação, geração de recursos e hardware ou ferramentas locais para compilar e testar.

fal tem seus próprios preços por modelo, que variam conforme o modelo e os ajustes. A documentação de autenticação usa FAL_KEY. Configure a chave real de forma privada no ambiente que inicia o agente. Os valores abaixo são apenas exemplos para substituição.

Em Bash ou Zsh:

export FAL_KEY="YOUR_FAL_API_KEY"

Em Windows PowerShell:

$env:FAL_KEY = "YOUR_FAL_API_KEY"

Uma credencial do modelo de programação, incluindo uma chave OmniaKey, não é uma chave fal. Instalar o plugin não unifica as cobranças. Antes de aprovar um lote, confira o modelo de geração e a quantidade solicitada. Não coloque chaves em arquivos do mod ou em pacotes publicados.

Você pode começar com arte provisória ou feita por você. O guia de recursos também documenta um comfy para criar imagens em um servidor ComfyUI local sem chave fal. As receitas de imagem incluídas não substituem todo o fluxo de áudio, 3D e vídeo de fal; o hardware e os modelos locais precisam ser preparados à parte.

O que conferir quando falha

Altere uma camada por vez:

• um não encontrado: confira o PATH do terminal e a instalação independente da CLI antes de investigar o carregador.
• Jogo não detectado: informe a pasta e compare a análise com a documentação atual da comunidade.
• Falha na autenticação fal: verifique se o processo do agente recebeu FAL_KEY da conta correta. O login do agente não valida a conexão com fal.
• Compila, mas o mod não carrega: confira versões, caminho de instalação e log do carregador antes de gerar recursos novamente.
• Arte incorreta no jogo: examine dimensões, transparência, organização dos quadros e orientação antes de mudar o prompt de imagem.

Guarde o log e o menor caso que reproduz a falha. Isso dá ao próximo diagnóstico algo concreto para verificar.

Uso online e publicação

Siga os limites do projeto: use jogos que possui, priorize testes offline ou ambientes permitidos sob seu controle, sem contornar anticheat, DRM ou verificação de propriedade. O projeto rejeita injeção em clientes online protegidos. Um servidor privado não elimina as proteções do cliente nem as restrições da distribuidora.

Antes de compartilhar, confira os termos do jogo e as licenças dos recursos e ferramentas. A licença MIT do kit não concede direito de redistribuir arquivos do jogo, recursos extraídos ou código descompilado. Publique seu trabalho com instruções de instalação, versões testadas e remoção.

Para conectar o modelo, consulte o guia de conexão do Claude Code e os preços atuais da OmniaKey. Configure essa conexão separadamente de fal e valide o fluxo real do mod no seu ambiente.