O Sync é um recurso que conecta o estado do Roblox Studio com os arquivos locais, permitindo que a IA leia e modifique de forma estável o contexto completo do projeto.

Por que o Sync é Importante

Sem o Sync, a IA só consegue julgar com base em parte do código colado na conversa. Com o Sync ativado, o trabalho é baseado no projeto completo, facilitando:

Aplicar refatorações consistentes em vários scripts
Revisar rapidamente apenas as modificações arriscadas com base no histórico de alterações
Manter claro qual lado — Studio ou local — é a referência

Como Funciona Basicamente

Fluxo de Sync — Árvore do Studio sincronizada com arquivos locais

Full Sync: Sincronização inicial da árvore e instâncias do Studio para o espelho local
Incremental Sync: Reflete apenas as alterações subsequentes via monitoramento de mudanças
Rastreamento de History/Status: Verifica quais alterações foram aplicadas, quando e em qual direção

Os dados de Sync são gerados em {projectRoot}/weppy-project-sync/place_{placeId}/explorer. Além disso, o WEPPY registra o sourcemap por place em {projectRoot}/weppy-project-sync/place_{placeId}/sourcemap.json e mantém o arquivo representativo raiz recomendado em {projectRoot}/weppy-project-sync/sourcemap.json.

Estrutura de Diretórios do Projeto e Múltiplos Places

O WEPPY Sync cria um diretório weppy-project-sync/ abaixo da raiz do projeto e mantém árvores espelho separadas por Place.

weppy-project-sync/
├── sourcemap.json             # Sourcemap representativo raiz (caminho recomendado para luau-lsp)
├── .sync-config.json          # Configuração global (compartilhada por todos os Places)
├── place_123456/              # Diretório por Place
│   ├── explorer/              # Workspace espelho (formato aninhado v2)
│   │   ├── Workspace/
│   │   │   ├── _tree.json
│   │   │   ├── Part/
│   │   │   │   └── Part.props.json
│   │   │   └── MyScript/
│   │   │       └── MyScript.server.luau
│   │   └── ServerScriptService/
│   │       └── _tree.json
│   ├── sourcemap.json         # Sourcemap por Place
│   ├── .sync-meta.json        # Metadados do Place
│   └── .sync-index.json       # Índice de hash (version: 2)
└── place_789012/              # Outro Place
    └── ...

Cada Place tem seu próprio diretório place_XXXXX/. No tier Pro, você pode sincronizar até 3 Places simultaneamente, e Places pouco utilizados são removidos da memória pela política LRU (os dados em disco são mantidos). Graças a essa estrutura, você pode alternar entre vários jogos na mesma raiz de projeto sem misturar os estados de sync.

Navegar pelos Dados de Sync no VSCode

Se você instalar a extensão WEPPY Roblox Explorer, poderá navegar pela árvore de instâncias sincronizadas no VSCode da mesma forma que no Roblox Studio. O Explorer lê os arquivos de sync gerados aqui e, se o servidor MCP local estiver em execução, exibe adicionalmente informações de status de sync e direction em tempo real.

WEPPY Roblox Explorer — Navegando pela árvore de instâncias sincronizadas no VSCode

Exibe a árvore de serviços/instâncias com ícones de classe Roblox
Clique em um arquivo de script para editar imediatamente
Verifique alterações/conflitos com badges de status de Sync

Guia do Explorer →

Basic vs Pro

Item	Basic	Pro
Direção de sincronização	Studio → Local	Bidirecional
Direction por tipo	Não suportado	Suportado (Scripts / Values / Containers / Data / Services)
Apply Mode por tipo	Não suportado	Suportado (Auto / Manual)
API de status/histórico	Não suportado	Suportado (`status_current_place`, `history`, `progress`)
Uso da ferramenta `manage_sync`	Não suportado	Suportado
Sync de múltiplos Places	Não suportado	Suportado (até 3 Places)

Alvos de Sincronização e Regras de Exclusão Padrão

Serviços sincronizados por padrão:

Workspace
Lighting
ReplicatedStorage
ServerStorage
ServerScriptService
StarterGui
StarterPlayer
StarterPack
ReplicatedFirst
SoundService
Chat
LocalizationService

Itens excluídos por padrão:

Classes: Terrain, Camera
Caminhos proibidos por segurança: CoreGui, CorePackages, RobloxScript, RobloxScriptSecurity

Direction e Apply Mode

Direction (Direção de Sincronização por Tipo)

forward: Studio → Local
reverse: Local → Studio
bidirectional: Bidirecional

Os tipos são gerenciados separadamente: scripts, values, containers, data, services.

Apply Mode (Modo de Aplicação para Alterações Reverse)

manual: O usuário confirma antes de refletir no Studio
auto: Aplica automaticamente as alterações detectadas

No Pro, você pode definir Direction/Apply Mode diferente por tipo para um controle mais preciso do fluxo de trabalho.

Guia de Ações `manage_sync` (Pro)

Ação	Descrição	Principais Parâmetros
`status_current_place`	Verificar o status de sincronização do Place atualmente conectado	`-`
`history`	Consultar histórico de alterações	`placeId`, `query.limit`, `query.offset`
`directions`	Consultar Direction por tipo	`placeId`
`read_file`	Ler arquivo sincronizado	`placeId`, `instancePath`
`write_file`	Escrever arquivo sincronizado	`placeId`, `instancePath`, `content`
`progress`	Verificar progresso/throughput em tempo real	`placeId`

Fluxo de Trabalho Recomendado

1) Começar com Segurança

Primeiro, complete um Full Sync para criar um ponto de referência do estado atual.
No início, opere com aplicação manual para reduzir o risco de alterações.

2) Fazer Alterações com a IA

“Verifique o status do Sync e resuma apenas as alterações arriscadas com base no histórico recente”
“Refatore primeiro apenas os scripts do ServerScriptService e mantenha um histórico das alterações”

3) Resolver Conflitos Quando Ocorrem

Quando alterações são detectadas em ambos os lados — Studio e local — durante a sincronização bidirecional, aparece a tela de resolução de conflitos mostrada abaixo.

Local Changes Detected — Opções de resolução de conflitos (Studio Priority / Local Priority / Per-File)

Studio Priority: Sobrescrever com o estado do lado do Studio como referência
Local Priority: Refletir o arquivo local no Studio como referência
Per-File: Escolher individualmente qual lado priorizar para cada arquivo

4) Recuperar Quando Ocorrem Problemas

Rastrear alterações recentes com history
Verificar os arquivos necessários com read_file
Refletir o conteúdo a recuperar com write_file e reconfirmar o estado do Studio

Formato de Arquivo (v2 diretório aninhado)

Cada instância do Roblox é armazenada em seu próprio diretório, com os arquivos de metadados localizados dentro desse diretório:

explorer/
├── Workspace/
│   ├── _tree.json
│   ├── Part/
│   │   └── Part.props.json
│   ├── MyScript/
│   │   └── MyScript.server.luau
│   └── Coins/
│       └── Coins.value.json

Convenções de nomenclatura de arquivo:

Propriedades: {Name}/{Name}.props.json
Scripts: {Name}/{Name}.server.luau / .client.luau / .module.luau
Valores: {Name}/{Name}.value.json

Instâncias com o mesmo nome são diferenciadas adicionando o sufixo ~N ao diretório (ex.: Part~2/Part.props.json). Se o nome contiver ~, ele é escapado como ~~ (ex.: Part~2 → Part~~2/). Regra Odd-Count Tilde: ~+N no final é interpretado como sufixo de colisão apenas quando o número de tildes é ímpar.

Integração com luau-lsp

O WEPPY Sync pode gerar automaticamente os arquivos de sourcemap necessários para o luau-lsp, portanto você pode usar recursos de editor com reconhecimento do Roblox sem precisar configurar um projeto Rojo separado.

Após o Full Sync, o WEPPY gera os seguintes arquivos:

Sourcemap por Place: weppy-project-sync/place_<id>/sourcemap.json
Arquivo representativo raiz: weppy-project-sync/sourcemap.json

Quando o luau-lsp lê o sourcemap do WEPPY, os seguintes recursos são aprimorados:

Autocompletar para game.*
Navegação baseada em scripts sincronizados
Resolução de require entre scripts sincronizados

Método de Configuração Recomendado

Execute um Full Sync uma vez para que o WEPPY crie weppy-project-sync/sourcemap.json.
Configure o sourcemap do luau-lsp no seu editor para apontar para weppy-project-sync/sourcemap.json.
Se puder desativar a geração automática de Rojo no cliente que você usa, defina luau-lsp.sourcemap.autogenerate como false.

Exemplo de configuração VSCode:

{
  "luau-lsp.sourcemap.enabled": true,
  "luau-lsp.sourcemap.autogenerate": false,
  "luau-lsp.sourcemap.sourcemapFile": "weppy-project-sync/sourcemap.json"
}

weppy-project-sync/sourcemap.json acompanha o place representativo atual do projeto. Se você quiser fixar em um place específico, configure o luau-lsp para apontar diretamente para weppy-project-sync/place_<id>/sourcemap.json daquele place.

Sync Bidirecional