Roblox MCP
Conecte agentes de codificação de IA a uma sessão ativa do Roblox Studio.
Documentação
WEPPY Roblox AI Toolkit — Desenvolvimento de Jogos com IA para Roblox Studio
WEPPY Roblox AI Toolkit é um produto de desenvolvimento com IA para Roblox Studio. Ele inclui o WEPPY MCP Server para conexões de aplicativos de IA e o WEPPY Roblox Studio Plugin para controle ao vivo do Studio. Claude Code, Codex e Antigravity também podem instalar o WEPPY AI Agent Plugin opcional para configuração nativa do cliente e orientação de fluxo de trabalho.
Trabalho multi-Place no Studio · Assets gerados para Roblox · Sincronização bidirecional · Playtest automatizado · UI Studio
English | 한국어 | 日本語 | Español | Português | Bahasa Indonesia | Deutsch
Por que o WEPPY Roblox AI Toolkit?
Agentes de codificação com IA como Claude, Codex e Gemini são poderosos, mas não conseguem ver ou modificar nada dentro do Roblox Studio. O DataModel, scripts, terreno e iluminação são invisíveis para ferramentas externas. Sem uma ponte, a IA só pode gerar trechos de código que você precisa colar manualmente.
O WEPPY MCP Server conecta agentes de IA ao WEPPY Roblox Studio Plugin. A IA cria e modifica diretamente instâncias, scripts, propriedades, terreno e muito mais dentro do Studio, e as alterações são refletidas imediatamente no Studio e no painel para que você veja exatamente o que mudou.
O WEPPY também é feito para experiências Roblox divididas em vários Places. Abra até cinco janelas do Studio para Lobby, Game, Shop, Tutorial ou outros Places e diga ao agente qual Studio ID usar. Uma única solicitação pode atualizar vários Places sem reexplicar o contexto ou copiar alterações manualmente.
Para assets, um agente pode criar ou preparar uma imagem, salvá-la na Asset Library, enviá-la pelo Roblox Open Cloud e aplicar o URI do asset retornado a um Place. O resultado é um caminho mais curto entre "criar este ícone/decal" e "está visível no Studio".
Sem copiar e colar código ou IDs de assets. A IA faz o trabalho, você revisa os resultados.
Instalação Rápida
Comece pela página de instalação web. Ela mostra o script de uma linha recomendado para sua plataforma primeiro.
Instalação Recomendada de Uma Linha
Na página de instalação, copie o script de uma linha e execute-o no Terminal ou no PowerShell.
macOS / Linux
curl -fsSL https://raw.githubusercontent.com/hope1026/weppy-roblox-mcp/main/install.sh | bash
Windows (PowerShell)
irm https://raw.githubusercontent.com/hope1026/weppy-roblox-mcp/main/install.ps1 | iex
Depois, reabra seu aplicativo de IA e reinicie o Roblox Studio.
O registro automático do WEPPY MCP Server suporta Claude Code, Claude Desktop, Cursor, Codex CLI/App, Gemini CLI e Antigravity / Antigravity IDE / Antigravity CLI.
Para Claude Code, o instalador também instala o WEPPY AI Agent Plugin. Para Codex, ele adiciona o marketplace de plugins e depois pede que você instale o WEPPY AI Agent Plugin pelo Plugin Directory. Para Antigravity, o plugin de agente de IA é instalado somente quando o Antigravity CLI e o agy plugin estão disponíveis; caso contrário, o instalador preserva a conexão MCP direta.
Instalação Web pelo Navegador
Se o terminal ou o PowerShell for desconfortável, use o instalador web sem terminal na mesma página de instalação.
Instalação Manual
Se a instalação de uma linha ou o instalador web sem terminal não funcionar, registre o WEPPY MCP Server manualmente com seu aplicativo de IA.
Use este comando de servidor:
npx -y @weppy/roblox-mcp@latest
O registro automático suporta Claude Code, Claude Desktop, Cursor, Codex CLI, Codex App, Gemini CLI e Antigravity / Antigravity IDE / Antigravity CLI.
Qualquer cliente de IA compatível com MCP funciona. O comando do servidor é
npx -y @weppy/roblox-mcp@latest.
Dola Desktop conecta-se por meio de um Custom Connector STDIO local. Ele exige o modo Pro do Dola e o computador Local. Siga o guia de configuração manual do Dola; o instalador de uma linha e o plugin do marketplace do GitHub não configuram o Dola.
WEPPY AI Agent Plugin Opcional
O WEPPY Roblox AI Toolkit conecta-se a todos os aplicativos de IA suportados por meio do WEPPY MCP Server. Claude Code, Codex e Antigravity podem instalar adicionalmente o WEPPY AI Agent Plugin para configuração nativa do cliente e orientação de fluxo de trabalho para controle do Studio, sincronização e assets.
Claude Code
claude plugin marketplace add hope1026/weppy-roblox-mcp --scope user
claude plugin install weppy-roblox-ai-toolkit@hope1026-roblox-mcp --scope user
Codex
codex plugin marketplace add hope1026/weppy-roblox-mcp
Depois de adicionar o marketplace do Codex, reinicie o Codex, abra o Plugin Directory e instale o WEPPY AI Agent Plugin.
Antigravity
O Antigravity CLI é necessário para instalar o WEPPY AI Agent Plugin. O instalador de uma linha usa agy plugin install com a versão pública mais recente do GitHub, verifica com agy plugin list e publica o payload somente de skills verificado nas superfícies de IDE suportadas. As instalações existentes são substituídas a cada execução para que possam convergir para a versão mais recente.
O instalador reporta resultados como instalado, atualizado, reinstalado, reparado, fallback, falhou ou ignorado. Um CLI ausente mantém a conexão MCP compartilhada em ~/.gemini/config/mcp_config.json funcionando e reporta fallback; um plugin existente nunca é tratado como ignorado. Em um perfil somente CLI, o MCP de plugin nativo verificado substitui a entrada WEPPY direta compartilhada. Quando o Antigravity IDE e o CLI coexistem, ambas as visualizações de plugin permanecem somente skills e uma definição direta compartilhada de weppy-roblox-mcp atende a ambos. Fora da matriz verificada de SO e versão, a descoberta nativa usa o fallback MCP.
No Antigravity para Windows, a instalação do CLI foi verificada para expor skills e MCP. A descoberta de plugin do Antigravity IDE para Windows não foi verificada porque o ambiente verificado não tem UI de inspeção de plugins ou skills, então o fallback MCP compartilhado é preservado. URLs do GitHub não são passadas diretamente para agy plugin install; o instalador baixa a versão pública mais recente e instala a partir de um caminho local preparado.
Compatibilidade
| Claude Code | Claude Desktop | Cursor | Codex CLI | Gemini CLI | Antigravity / Antigravity IDE / Antigravity CLI | Dola Desktop |
|---|---|---|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | Configuração manual |
Requisitos: Node.js 22+, Roblox Studio, Windows 10+ ou macOS 12+
O Que Ele Faz
1) Ferramentas MCP: Execução direta no Studio a partir de linguagem natural
A IA pode lidar diretamente com scripts, instâncias, propriedades, terreno, iluminação, assets, áudio e animação dentro do Studio.
- "Adicione partículas + som + cooldown quando o jogador pular."
- "Construa uma arena de chefe no centro do mapa e coloque pontos de spawn seguros contra colisão."
- "Altere esta interface de módulo e atualize todos os scripts dependentes."
- "Gere terreno com montanhas e rios e coloque pontos de spawn em áreas planas."
- "Pesquise na Creator Store um modelo de espada e insira-o no StarterPack."
2) Trabalho multi-Place: Divida uma solicitação entre várias janelas do Studio
Muitas experiências Roblox não são um único Place. O WEPPY permite manter até cinco janelas do Studio conectadas a um servidor MCP e rotear o trabalho por Studio ID.
- Abra até cinco janelas do Roblox Studio, como Lobby, Game, Shop ou Tutorial
- Peça uma vez: "No studio-1, adicione o portal de evento ao Lobby. No studio-2, adicione o ponto de chegada e a UI de guia ao Game."
- Use o Dashboard Connection para ver cada agente de IA, Studio Target, Studio ID copiável e estado de roteamento
- Trabalhe com o fluxo multi-Studio também documentado pelo guia oficial de MCP do Studio da Roblox, com a visibilidade do painel do WEPPY por cima
3) Assets: Gere, envie e aplique imagens no Studio
Se seu aplicativo de IA pode criar arquivos PNG ou JPG, ele pode criar uma nova imagem para este fluxo de trabalho. Caso contrário, comece com uma imagem que você já tenha e registre-a na Asset Library antes de enviá-la.
O WEPPY Assets transforma uma solicitação de asset em linguagem natural em um resultado pronto para o Studio.
- "Crie um ícone de gema para o botão da loja, envie-o para o Roblox e aplique-o à imagem ShopButton no Place do Lobby."
- Salve imagens geradas, Decals e arquivos RBXM na Asset Library local
- Envie imagens pelo Roblox Open Cloud e reutilize assets específicos de Place ou compartilhados
- Aplique o URI do asset retornado a ImageLabel, Decal, Texture ou outras propriedades do Studio
4) Sincronização: Mantenha o contexto completo do projeto estável para a IA
A IA lê um espelho local do seu projeto do Studio. Revise as alterações locais pendentes antes de aplicá-las ao Studio.
- A sincronização começa Desligada no primeiro uso. Iniciar na conexão também é Desligado. As configurações salvas sempre têm precedência, incluindo um valor Desligado salvo. O fluxo de primeiro uso é Studio First, então a primeira sincronização trata o Studio como fonte.
- Escolha Studio First, Bidirectional Review, Local Code, Studio World ou Custom. O Custom agrupa alterações em quatro escopos semânticos: Script Source, Properties, Structure e Service Properties.
- Os modos de aplicação de Content Changes e Structure Changes são mostrados separadamente da direção do escopo. A exclusão de arquivo local não exclui uma instância do Studio por padrão; aplicar uma exclusão ao Studio exige aceitação adicional e é separado da limpeza do histórico da UI do Studio.
- Review Changes lista edições locais aguardando aplicação manual. Review Conflicts lista arquivos alterados de forma diferente no Studio e localmente; compare ambas as versões antes de escolher uma.
- O Basic usa sincronização Studio para local. O Pro adiciona as direções de fluxo de trabalho mais ricas, histórico e suporte para até cinco Places.
- O WEPPY MCP Server e o WEPPY Roblox Studio Plugin devem vir da mesma versão. Atualize ambos juntos e reinicie o Roblox Studio antes de reconectar se as versões não corresponderem.
5) Validação de Sintaxe Luau: Detecte scripts quebrados antes do Playtest
A IA pode verificar o código-fonte Luau bruto ou um Script existente para erros de sintaxe sem iniciar o jogo. A validação independente está disponível no Basic e no Pro.
- Peça à IA para validar o código-fonte ou um caminho de Script para receber todos os diagnósticos de sintaxe em uma resposta
- Ative Controls → Luau Syntax Validation para verificar o código-fonte salvo real após gravações de script suportadas; o padrão é Desligado
- A configuração do Dashboard é aplicada. Se uma chamada de ferramenta solicitar um valor diferente de
validate, a gravação segue a política do Dashboard e retorna um aviso com o caminho da configuração - Verificações válidas automáticas mantêm a resposta de gravação normal inalterada. Verificações inválidas ou indisponíveis adicionam detalhes, enquanto um
validate=truecorrespondente explícito também retorna detalhes válidos completos - Um erro de sintaxe ou parser indisponível nunca reverte uma gravação de script bem-sucedida
A primeira validação que precisa do parser complementar baixa a versão WASM exata de luau-parser-v1.0.0 e a armazena em cache localmente. Um luau-compile local compatível pode ser usado como fallback. O código-fonte do script é analisado no seu computador e não é enviado a um serviço de validação remoto; a solicitação de download busca apenas o artefato do parser. Scripts muito grandes podem adicionar algum tempo de leitura e análise.
6) Playtest: Deixe a IA executar e verificar testes automaticamente
Verificações de runtime comuns usam uma sessão de Play estruturada. A IA pode esperar pela UI do jogo, inspecionar sua estrutura semântica e geometria, fornecer entrada virtual, observar a resposta da UI e verificar o estado do servidor resultante em etapas de evidência separadas. O Dashboard local agrupa o resultado salvo por servidor, UI do cliente, interação e evidência visual para que você possa revisar o que passou e por quê.
A mesma página de Playtest também inclui um espaço de trabalho Test Values para valores somente de desenvolvimento. Crie vários perfis com escopo de Place para diferentes configurações de teste; o Dashboard lembra o último perfil selecionado para cada Place. Enquanto Play ou Run permanece ativo, você pode alternar, criar, editar ou excluir perfis sem reiniciar o jogo. Alternar mantém os valores atuais do jogo e altera os controles, Watch Values e Actions mostrados para a mesma sessão. Controles e observações somente leitura aparecem em uma lista pesquisável e paginada, para que perfis grandes permaneçam fáceis de examinar. Use Manage values para adicionar entradas descobertas dos Project Test Adapters, ou use um caminho de runtime e a seleção atual do Studio para valores diretos. Uma observação desatualizada ou desconectada é mostrada como o último valor observado, em vez de ser apresentada como atual. No Pro, as Actions do perfil podem executar uma operação de jogo preparada durante o Play, como alterar um valor ou chamar um Test Adapter revisado. As Actions relatam seu resultado separadamente das alterações de valor. Reset all restaura alterações reversíveis de valor; ele não pode desfazer dados de jogo salvos, mortes, recompensas ou solicitações externas causadas por uma Action.
O Basic inclui criação de perfil e observação de runtime ao vivo. O Pro adiciona alterações de valor tipadas durante o Play, rollback, Reset all e Automated Test Results salvos de verdade. A página Playtest explica as adições do Pro e fornece links diretos para os planos e opções de compra disponíveis.
O Studio Stop descarta alterações do Play/Run Instance. Enquanto o runtime permanece ativo, Reset all restaura todo valor reversível alterado por qualquer perfil nessa sessão, e uma transação parcialmente falha é revertida. Jogos que armazenam valores em cache na inicialização ou precisam de operações de domínio podem expor métodos revisados do Project Test Adapter por meio de metadados opcionais do Dashboard. O Dashboard valida os metadados, mostra a fonte de registro e vincula um observador somente leitura a cada controle do adapter. Remover uma referência de perfil deixa a fonte do adapter intacta.
Abra Before publishing no cabeçalho da página Playtest para uma referência em linguagem simples sobre o que retorna ao valor original após um teste no Studio, o que o WEPPY mantém apenas no seu computador e o que verificar antes e depois de publicar. Verificações comuns são separadas de itens que se aplicam apenas quando um jogo tem recursos somente de teste ou salva dados do jogador. O código de conexão de teste criado pelo WEPPY com configurações padrão não é executado no jogo público. Se o WEPPY tiver um registro local de que a proteção somente Studio foi explicitamente removida, o Dashboard mostra uma nota adicional para esse Place. O Rojo permanece opcional quando você deseja omitir o código-fonte de teste de um projeto de produção. Moeda ou progresso salvos pelo código do jogo podem permanecer após um teste, e Places na mesma Experience podem compartilhar esses dados. A referência está disponível no Basic e no Pro; ela não inspeciona arquivos, remove código de teste, cria arquivos de implantação nem certifica uma versão como segura.
- "Inicie um Playtest, pressione o botão Start e verifique se a rodada começa no servidor."
- "Verifique se o HUD aparece e se o card selecionado ativa após a entrada."
- "Valide se o script que acabei de alterar é executado sem erros no Playtest."
O modo Run é reservado para uma verificação somente servidor explicitamente solicitada. O Raw Luau permanece disponível como uma opção avançada explícita para diagnósticos que não se encaixam nas etapas estruturadas. A captura de tela em modo Play não é suportada; estrutura de UI, geometria, entrega de entrada, ativação e observações de servidor são registradas em vez disso. Os relatórios permanecem locais, os relatórios Raw Luau existentes permanecem legíveis e nenhuma alteração de configuração é necessária.
7) UI Studio: Crie e inspecione UI no jogo
O UI Studio permite que agentes de IA criem UI no jogo que combine com o estilo do seu jogo, ou analisem a UI que você já tem e sugiram melhorias.
As revisões de UI distinguem sobreposição observada, orientação do Roblox e sugestões de IA. A geometria de controles indisponíveis permanece não verificada. As recomendações respeitam o design escolhido; as alterações seguem o escopo que você solicitou.
Para UI criada por LocalScripts, o UI Studio distingue Editar StarterGui de uma observação estruturada de Play Client PlayerGui. Se a UI em runtime não foi revisada, ele relata essa evidência ausente em vez de assumir que o jogo não tem UI. Capturas de tela em modo Play permanecem sem suporte, então verificações semânticas de runtime e revisão visual de capturas permanecem separadas.
- Esclareça o objetivo da UI com perguntas guiadas sobre propósito, tela, dispositivos alvo e direção visual
- Crie ou refine menus, HUDs, botões, rótulos, painéis de imagem e outros elementos de UI do Roblox diretamente no Studio
- Capture o resultado, compare alterações antes/depois e siga as sugestões do dashboard para layout, legibilidade, alvos de toque e áreas seguras
8) WEPPY Dashboard: Monitore o trabalho da IA em tempo real
O servidor MCP fornece um dashboard web onde você pode verificar o status da conexão, o histórico de execução de ferramentas, o estado de sincronização, o histórico do UI Studio e os logs de alterações do jogo em tempo real.
- Topologia de conexão para agentes de IA, o servidor MCP e janelas conectadas do Roblox Studio
- Studio Targets com IDs de Studio copiáveis, selos de Prioridade/Fixado e um link para controles de roteamento
- Nomes de Places publicados e links rápidos para configurações do Place, gerenciamento da Experience e a página do Roblox
- Pastas de Place disponíveis em Tools, Playtest, Changelog e Assets antes da primeira Sync; pastas duplicadas são identificadas para revisão
- Fluxos de trabalho multi-agente e multi-Studio: mantenha vários agentes e até cinco janelas do Studio visíveis e diga ao agente qual ID de Studio usar
- Página Assets para itens da biblioteca local, assets compartilhados e status de upload no Roblox
- Página Controls para aplicar validação de sintaxe Luau pós-escrita, incluindo comportamento claro de On e Off
- Compare cada alteração feita pela IA via Before & After no Changelog
- Analise o fluxo de trabalho com histórico de execução de ferramentas, capturas do UI Studio e estatísticas
9) WEPPY Roblox Explorer: Navegue pela hierarquia do Studio no VSCode
Veja a árvore completa de instâncias do seu place do Roblox Studio diretamente no VSCode. Navegue por serviços, abra scripts sincronizados e arquivos de propriedade e acompanhe o status da sincronização — tudo sem alternar para o Studio. O WEPPY Roblox Explorer é uma extensão complementar do VSCode para dados de sincronização gerados pelo WEPPY. A navegação em árvore funciona a partir de arquivos sincronizados, e o estado de sincronização ao vivo ou indicadores de direção são aprimorados quando o servidor MCP local está em execução. Instale pelo VS Code Marketplace ou Open VSX.
- Ícones de classe correspondentes ao Studio para reconhecimento instantâneo
- Clique para abrir scripts sincronizados e arquivos de propriedade
- Suporte a múltiplos places com indicadores de status de sincronização para até cinco Places
Casos de Uso
- Prototipagem rápida: Descreva uma mecânica de jogo em linguagem natural e veja a IA construí-la no Studio
- Produção multi-Place: Mantenha Lobby e Game em janelas separadas do Studio e atualize ambos com uma única solicitação
- Refatoração em massa: Renomeie uma interface de módulo e atualize todos os scripts dependentes em uma única solicitação
- Terreno e ambiente: Gere terreno procedural, configure iluminação/atmosfera, posicione assets — tudo a partir de um único prompt
- Design de UI: Gere UI no jogo, capture prévias e itere nas sugestões do Design Check
- Consistência multi-arquivo: A IA lê o projeto completo via Sync e aplica alterações em scripts relacionados juntos
- Integração de assets gerados: Crie um ícone ou decal, envie-o para o Roblox, aplique-o a uma propriedade de UI ou Decal e mantenha o asset para reutilização
Por Que Isso Importa
- Comprima trabalho repetitivo: transforme muitas edições manuais em uma única solicitação
- Trabalhe em até cinco Places sem reexplicar o contexto ou copiar alterações entre janelas do Studio
- Transforme imagens geradas em assets aplicados do Roblox sem mover arquivos e IDs de asset manualmente
- Altere arquivos relacionados juntos: não apenas um único arquivo alvo
- Menor risco: confie no estado de sincronização e no histórico antes de aplicar alterações
- Melhor eficiência de tokens (Pro): reduza idas e voltas com ações em massa
Documentação
Guias detalhados e configurações específicas de aplicativos agora estão na web.
Para detalhes de configuração de aplicativos, abra o hub de documentação web e escolha o guia relevante do cliente de IA.
Privacidade e Telemetria
O WEPPY usa telemetria do Google Analytics 4 Measurement Protocol e uma observação anônima de operações de dispositivo com melhor esforço para entender o uso do produto, confiabilidade, cobertura de plataforma e adoção de recursos. A telemetria pode ser desativada definindo ENABLE_TELEMETRY=false ou ENABLE_TELEMETRY=0 no ambiente do servidor MCP.
O WEPPY não coleta seu nome, endereço de e-mail, chave de licença bruta, caminhos de arquivos locais, código-fonte de scripts ou conteúdo de projetos do Roblox por meio de telemetria.
Consulte PRIVACY.md para o aviso completo de telemetria.
FAQ
Como conecto o Claude Code ao Roblox Studio?
Instale pela página de instalação web para registrar o WEPPY MCP Server e instalar o WEPPY Roblox Studio Plugin. Você também pode adicionar o WEPPY AI Agent Plugin para Claude Code com os comandos acima. Seu comando MCP permanece npx -y @weppy/roblox-mcp@latest.
Como uso o Codex CLI com o Roblox Studio?
Instale o WEPPY Roblox Studio Plugin e adicione a configuração do WEPPY MCP Server ao Codex CLI. Você também pode adicionar o marketplace de plugins do Codex e instalar o WEPPY AI Agent Plugin pelo Plugin Directory.
O Roblox MCP funciona com o Cursor?
Sim. Qualquer cliente de IA compatível com MCP funciona.
A IA pode criar jogos Roblox com isso?
Sim. A IA pode criar instâncias, escrever scripts, gerar terreno, configurar iluminação, inserir assets, configurar física e muito mais — tudo dentro de uma sessão ativa do Roblox Studio. Vai além da geração de código para ações executáveis.
Qual é a diferença entre Basic e Pro?
Basic (Grátis) inclui execução de ferramentas MCP e sincronização unidirecional (Studio -> Local). O Pro adiciona trabalho multi-Place em até cinco Places, Asset Library com upload para o Roblox, sincronização bidirecional, UI Studio, operações em massa, geração de terreno, análise espacial e controle de áudio/animação. Consulte a página de upgrade do Pro.
Como o Weppy é diferente de outros servidores MCP do Roblox?
O Weppy usa despacho baseado em ações em vez de ferramentas separadas para cada função. Isso reduz significativamente o consumo de tokens de IA. Ele também combina trabalho multi-Place baseado em ID do Studio, upload/aplicação de assets gerados, sincronização bidirecional de projetos e controle de Playtest.
É seguro? A IA pode quebrar meu jogo?
O servidor roda apenas em localhost (127.0.0.1:3002). Caminhos proibidos (CoreGui, CorePackages) são bloqueados. Limite de taxa (450 req/min) e timeouts de 30 segundos evitam operações descontroladas. Todas as alterações são rastreáveis pelo histórico de sincronização.
Pro Upgrade
Trabalho multi-Place, assets gerados para o Roblox, Sync bidirecional, UI Studio, controle de Playtest e eficiência de tokens de IA — tudo em um único upgrade.
Licença
Este repositório está licenciado sob AGPL-3.0.
Licenciamento comercial está disponível separadamente. Consulte COMMERCIAL-LICENSE.md.
O uso do nome e logotipos Weppy é regido por TRADEMARKS.md.
