Como instalar e usar o Universal Modder

Requisitos

Instale os requisitos de uma vez

winget install Git.Git Python.Python.3.12 astral-sh.uv Gyan.FFmpeg
winget install BlenderFoundation.Blender   # opcional, para 3D → sprites

brew install git python ffmpeg uv
brew install --cask blender                 # opcional

sudo apt install git python3 python3-venv ffmpeg
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows, macOS e Linux: o que funciona onde

Quase todo o kit é multiplataforma. A parte que controla um jogo rodando (iniciar, capturar tela, enviar comandos, gravar a janela só com o áudio do jogo) é focada em Windows, porque é lá que os jogos estão. Os agentes controlam jogos de Windows nativamente ou pelo WSL2.

No macOS e Linux o agente ainda consegue testar no jogo com as ferramentas de captura do sistema (screencapture, ffmpeg, xdotool), mas nada vem pronto. Notas de campo como rodar o xEdit no Linux ou o HL2 pelo Wine no macOS mostram que é possível.

Instalar por agente: lado a lado

Toda opção instala as mesmas skills (formato Agent Skills), o servidor MCP do fal e a CLI um.

Claude Code

Rode dentro de uma sessão do Claude Code (não no seu terminal):

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

Escolha o escopo user para ter o plugin em qualquer pasta e rode /reload-plugins se pedir. O passo a passo completo, incluindo o Claude Desktop e como chamar cada skill, está na página Universal Modder + Claude Code.

OpenAI Codex

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

O Codex lê as skills de .agents/skills e a configuração MCP de .codex/config.toml.

Gemini CLI

gemini extensions install https://github.com/rehan-remade/universal-modder

O manifesto da extensão é o gemini-extension.json; as instruções vêm do GEMINI.md, que aponta para o AGENTS.md.

VS Code com GitHub Copilot

1. Abra as configurações e ative chat.plugins.enabled.
2. Abra a paleta de comandos e rode Chat: Install Plugin From Source.
3. Cole https://github.com/rehan-remade/universal-modder.

A configuração MCP fica em .vscode/mcp.json.

Cursor

Instale pelo Cursor Marketplace, ou clone o repositório e abra: o Cursor lê AGENTS.md e .cursor/mcp.json automaticamente.

OpenCode

git clone https://github.com/rehan-remade/universal-modder
cd universal-modder
opencode

O opencode.json adiciona as skills e o servidor MCP do fal.

Qualquer outro agente

# só as skills, na pasta de skills do seu agente
npx skills add https://github.com/rehan-remade/universal-modder

# ou tudo: inicie seu agente dentro do clone
git clone https://github.com/rehan-remade/universal-modder

Instalar só a CLI um

Instalar o plugin ou clonar o repositório já coloca o um no PATH. Se você usa as skills em outro lugar, ou quer o um num terminal comum, instale como ferramenta. A instalação é pelo GitHub; ele não está no PyPI, então pip install universal-modder não funciona.

uv tool install git+https://github.com/rehan-remade/universal-modder
# ou
pipx install git+https://github.com/rehan-remade/universal-modder

Cada grupo de comandos tem --help com exemplos. Veja a referência da CLI um.

Configure sua chave do fal

Pegue uma chave em fal.ai/dashboard/keys (é preciso adicionar créditos; ela aparece uma única vez, então guarde). Ela alimenta tanto o servidor MCP do fal quanto o um fal.

export FAL_KEY="your-key"
# deixar permanente
echo 'export FAL_KEY="your-key"' >> ~/.zshrc   # ou ~/.bashrc

setx FAL_KEY "your-key"
# depois abra um terminal novo e reinicie o agente

Sem chave? O um comfy gera imagens com um servidor ComfyUI local. Áudio, 3D e vídeo continuam precisando do fal. Os preços estão na página de custos.

Confira a instalação

um --help
um kb search "terraria"       # notas de campo anteriores (funciona fora do repo)
um scan --list                # jogos encontrados nesta máquina
um fal price fal-ai/trellis-2 # confirma que a FAL_KEY funciona

Sua primeira sessão: uma mudança pequena e reversível

1. Escolha um jogo fácilJogos com um loader popular são o começo mais tranquilo: Terraria (tModLoader), Stardew Valley (SMAPI), Minecraft (Fabric/Forge), jogos Unity com BepInEx e Unreal com UE4SS. Veja a biblioteca de jogos.
2. Peça um reconhecimento primeiro
   promptCopiar

   Qual é a engine da minha cópia do Terraria, alguém já fez mod nele (pesquise na base de conhecimento) e qual rota você seguiria? Não mude nada ainda.

3. Deixe ele fazer backup e montar um laboratórioO agente tira um snapshot dos saves com um backup create, usa um perfil ou mundo separado e pergunta antes de instalar um loader.
4. Construa uma parte
   promptCopiar

   Adicione um bumerangue que ricocheteia entre inimigos quatro vezes antes de voltar. Primeiro com um sprite provisório; quando funcionar no jogo, um sprite do fal.

5. Verifique e depois expandaAbra o jogo, veja com seus olhos e só então peça mais. Projetos longos ficam no MODLOG.md; numa sessão nova, diga “leia o MODLOG.md e continue”.

Solução de problemas

Adicionar o marketplace falha com erro de Git / SSH

Os marketplaces de plugins são clonados com Git. Se sua máquina não tem chave SSH do GitHub, diga ao Git para usar HTTPS no GitHub:

git config --global url."https://github.com/".insteadOf git@github.com:

As skills não aparecem depois de instalar

Rode /reload-plugins (Claude Code) ou reinicie o agente. Confira em /plugin se o plugin está ativado.

um: command not found

Abra um terminal novo depois de instalar o plugin, ou instale a CLI com uv tool install como acima e garanta que ~/.local/bin está no PATH (uv tool update-shell).

um fal diz que falta a chave

A FAL_KEY precisa estar no ambiente em que o agente foi iniciado. Reinicie o agente depois do setx ou de editar o perfil do shell.

um win não roda

Ele só controla jogos de Windows, pelo Windows ou WSL2. No macOS/Linux, teste no jogo manualmente.