Sync es la función que conecta el estado de Roblox Studio con los archivos locales, permitiendo que la IA lea y modifique el contexto completo del proyecto de forma estable.

Por qué Sync es importante

Sin Sync, la IA solo puede juzgar a partir de una parte del código que pegues en la conversación. Con Sync activado, el trabajo se basa en todo el proyecto, lo que facilita lo siguiente:

Aplicar refactorizaciones de forma consistente en múltiples scripts
Revisar rápidamente solo los cambios riesgosos basándose en el historial de cambios
Mantener claro en qué dirección está la referencia: Studio o local

Funcionamiento básico

Flujo de Sync — El árbol de Studio sincronizado con los archivos locales

Full Sync: Sincronización inicial del árbol de Studio y las instancias con el espejo local
Incremental Sync: Solo refleja los cambios posteriores mediante monitoreo de cambios
Seguimiento de History/Status: Confirma qué cambio se reflejó, cuándo y en qué dirección

Los datos de Sync se generan bajo {projectRoot}/weppy-project-sync/place_{placeId}/explorer. WEPPY también registra el sourcemap por place en {projectRoot}/weppy-project-sync/place_{placeId}/sourcemap.json y mantiene el archivo raíz representativo en {projectRoot}/weppy-project-sync/sourcemap.json.

Estructura del directorio del proyecto y multi-Place

WEPPY Sync crea el directorio weppy-project-sync/ bajo la raíz del proyecto y mantiene árboles espejo separados por Place.

weppy-project-sync/
├── sourcemap.json             # Sourcemap raíz representativo (ruta recomendada para luau-lsp)
├── .sync-config.json          # Configuración global (compartida por todos los Places)
├── place_123456/              # Directorio por Place
│   ├── explorer/              # Espacio de trabajo espejo (formato anidado v2)
│   │   ├── Workspace/
│   │   │   ├── _tree.json
│   │   │   ├── Part/
│   │   │   │   └── Part.props.json
│   │   │   └── MyScript/
│   │   │       └── MyScript.server.luau
│   │   └── ServerScriptService/
│   │       └── _tree.json
│   ├── sourcemap.json         # Sourcemap por Place
│   ├── .sync-meta.json        # Metadatos del Place
│   └── .sync-index.json       # Índice de hashes (version: 2)
└── place_789012/              # Otro Place
    └── ...

Cada Place tiene su propio directorio place_XXXXX/. En el tier Pro se pueden sincronizar hasta 3 Places simultáneamente y, según la política LRU, los Places poco usados se expulsan de la memoria (los datos en disco se mantienen). Gracias a esta estructura, no se mezclan los estados de sincronización aunque trabajes con varios juegos bajo la misma raíz de proyecto.

Explorar los datos de Sync desde VSCode

Si instalas la extensión WEPPY Roblox Explorer, podrás navegar el árbol de instancias sincronizadas de la misma forma que en Roblox Studio, desde dentro de VSCode. Explorer lee los archivos de sync generados aquí y, si el servidor MCP local está en ejecución, muestra adicionalmente el estado de sync en tiempo real e información de dirección.

WEPPY Roblox Explorer — Navegando el árbol de instancias sincronizadas en VSCode

Muestra el árbol de servicios / instancias con iconos de clase de Roblox
Haz clic en un archivo de script para editarlo directamente
Verifica cambios / conflictos con los indicadores de estado de Sync

Guía de Explorer →

Basic vs Pro

Ítem	Basic	Pro
Dirección de sincronización	Studio → Local	Bidireccional
Direction por tipo	No soportado	Soportado (Scripts / Values / Containers / Data / Services)
Apply Mode por tipo	No soportado	Soportado (Auto / Manual)
API de estado/historial	No soportado	Soportado (`status_current_place`, `history`, `progress`)
Uso de la herramienta `manage_sync`	No soportado	Soportado
Sync multi-Place	No soportado	Soportado (hasta 3 Places)

Objetivos de sincronización y reglas de exclusión predeterminadas

Servicios sincronizados por defecto:

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

Elementos excluidos por defecto:

Clases: Terrain, Camera
Rutas prohibidas por seguridad: CoreGui, CorePackages, RobloxScript, RobloxScriptSecurity

Direction y Apply Mode

Direction (dirección de sincronización por tipo)

forward: Studio → Local
reverse: Local → Studio
bidirectional: Bidireccional

Los tipos se gestionan separados en scripts, values, containers, data y services.

Apply Mode (modo de aplicación de cambios reverse)

manual: El usuario confirma antes de reflejar en Studio
auto: Aplica automáticamente los cambios detectados

En Pro puedes configurar Direction/Apply Mode de forma diferente por tipo para controlar con detalle el flujo de trabajo.

Guía de acciones de `manage_sync` (Pro)

Acción	Descripción	Parámetros principales
`status_current_place`	Verificar el estado de sincronización del Place actualmente conectado	`-`
`history`	Consultar el historial de cambios	`placeId`, `query.limit`, `query.offset`
`directions`	Consultar el Direction por tipo	`placeId`
`read_file`	Leer un archivo sincronizado	`placeId`, `instancePath`
`write_file`	Escribir en un archivo sincronizado	`placeId`, `instancePath`, `content`
`progress`	Verificar el progreso/rendimiento en tiempo real	`placeId`

Flujo de trabajo recomendado

1) Empezar de forma segura

Primero completa un Full Sync para establecer el estado actual como punto de referencia.
Al principio, opera con aplicación manual para reducir el riesgo de cambios.

2) Hacer cambios junto con la IA

“Verifica el estado de Sync y resume solo los cambios riesgosos basándote en el historial reciente de cambios”
“Refactoriza primero los scripts de ServerScriptService y deja un historial de cambios”

3) Resolver conflictos cuando ocurren

Durante la sincronización bidireccional, si se detectan cambios tanto en Studio como localmente, aparece la siguiente pantalla de resolución de conflictos.

Local Changes Detected — Opciones de resolución de conflictos (Studio Priority / Local Priority / Per-File)

Studio Priority: Sobreescribe tomando como referencia el estado de Studio
Local Priority: Refleja en Studio tomando como referencia los archivos locales
Per-File: Selecciona individualmente qué lado tiene prioridad para cada archivo

4) Recuperar cuando hay problemas

Rastrea los cambios recientes con history
Verifica los archivos necesarios con read_file
Refleja el contenido a recuperar con write_file y vuelve a verificar el estado de Studio

Formato de archivo (v2 nested directory)

Cada instancia de Roblox se almacena como su propio directorio con los archivos de metadatos dentro:

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

Convenciones de nomenclatura de archivos:

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

Las instancias con el mismo nombre se distinguen añadiendo el sufijo ~N al directorio (por ejemplo: Part~2/Part.props.json). Si el nombre contiene ~, se escapa como ~~ (por ejemplo: Part~2 → Part~~2/). Regla Odd-Count Tilde: solo se interpreta como sufijo de colisión cuando el número de tildes al final de ~+N es impar.

Integración con luau-lsp

WEPPY Sync puede generar automáticamente los archivos de sourcemap que necesita luau-lsp, por lo que puedes usar las funciones del editor con reconocimiento de Roblox sin tener que configurar un proyecto de Rojo por separado.

Al terminar el Full Sync, WEPPY genera los siguientes archivos:

Sourcemap por Place: weppy-project-sync/place_<id>/sourcemap.json
Archivo raíz representativo: weppy-project-sync/sourcemap.json

Cuando luau-lsp lee el sourcemap de WEPPY, mejora lo siguiente:

Autocompletado de game.*
Navegación basada en scripts sincronizados
Resolución de require entre scripts sincronizados

Método de configuración recomendado

Ejecuta Full Sync una vez para que WEPPY genere weppy-project-sync/sourcemap.json.
Configura el sourcemap de luau-lsp en el editor para que apunte a weppy-project-sync/sourcemap.json.
Si puedes desactivar la generación automática de Rojo en tu cliente, configura luau-lsp.sourcemap.autogenerate en false.

Ejemplo de configuración en 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 sigue el place representativo actual del proyecto. Si quieres fijar un place específico, configura luau-lsp para que apunte directamente a weppy-project-sync/place_<id>/sourcemap.json de ese place.

Sync bidireccional