Bidirektionaler Sync

Sync verbindet den Roblox Studio-Status mit lokalen Dateien, sodass die KI den vollständigen Projektkontext zuverlässig lesen und ändern kann.

Warum Sync wichtig ist

Ohne Sync sieht die KI nur Code-Fragmente, die in die Konversation eingefügt wurden. Mit aktiviertem Sync arbeitet die KI mit dem gesamten Projekt, was Folgendes erheblich erleichtert.

• Konsistentes Refactoring über mehrere Skripte hinweg anwenden
• Schnell nur riskante Änderungen basierend auf dem Änderungsverlauf überprüfen
• Eine klare Richtung beibehalten, welche Seite — Studio oder lokal — die Quelle der Wahrheit ist

Wie es funktioniert

1. Full Sync: Initialer Sync des Studio-Baums und der Instanzen in einen lokalen Spiegel
2. Incremental Sync: Nachfolgende Änderungen werden über die Änderungsüberwachung als Diffs angewendet
3. History/Status-Tracking: Sehen Sie, was sich wann und in welche Richtung geändert hat

Sync-Daten werden unter {projectRoot}/weppy-project-sync/place_{placeId}/explorer erstellt. WEPPY schreibt außerdem eine Per-Place-Sourcemap nach {projectRoot}/weppy-project-sync/place_{placeId}/sourcemap.json und führt eine kanonische Root-Level-Datei unter {projectRoot}/weppy-project-sync/sourcemap.json.

Projekt-Verzeichnisstruktur und Multi-Place

WEPPY Sync erstellt ein weppy-project-sync/-Verzeichnis unter dem Projektstamm und führt für jeden Place einen separaten gespiegelten Baum.

weppy-project-sync/
├── sourcemap.json             # Root-Level kanonische Sourcemap (empfohlener Pfad für luau-lsp)
├── .sync-config.json          # Globale Konfiguration (von allen Places gemeinsam genutzt)
├── place_123456/              # Per-Place-Verzeichnis
│   ├── explorer/              # Gespiegelter Workspace (v2 nested format)
│   │   ├── Workspace/
│   │   │   ├── _tree.json
│   │   │   ├── Part/
│   │   │   │   └── Part.props.json
│   │   │   └── MyScript/
│   │   │       └── MyScript.server.luau
│   │   └── ServerScriptService/
│   │       └── _tree.json
│   ├── sourcemap.json         # Per-Place-Sourcemap
│   ├── .sync-meta.json        # Place-Metadaten
│   └── .sync-index.json       # Hash-Index (version: 2)
└── place_789012/              # Ein weiterer Place
    └── ...

Jeder Place hat sein eigenes place_XXXXX/-Verzeichnis. Mit dem Pro-Tier können bis zu 3 Places gleichzeitig synchronisiert werden; die LRU-Richtlinie räumt selten genutzte Places aus dem Speicher (Festplattendaten bleiben erhalten). Diese Struktur stellt sicher, dass der Sync-Status isoliert bleibt, wenn Sie an mehreren Spielen aus demselben Projektstamm arbeiten.

Sync-Daten in VSCode durchsuchen

Mit der WEPPY Roblox Explorer-Erweiterung können Sie den synchronisierten Instanzbaum in derselben Form wie Roblox Studio direkt in VSCode navigieren. Der Explorer liest die hier generierten Sync-Dateien und spiegelt zusätzlich Echtzeit-Sync-Status- und Richtungsinformationen wider, wenn der lokale MCP-Server läuft.

• Zeigt Service- / Instanzbaum mit Roblox-Klassen-Icons
• Klicken Sie auf Skript-Dateien, um sie direkt zu öffnen und zu bearbeiten
• Sync-Status-Badges zeigen Änderungen und Konflikte

Basic vs Pro

Sync-Ziele und Standard-Ausschlussregeln

Standardmäßig synchronisierte Services:

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

Standard-Ausschlüsse:

• Klassen: Terrain, Camera
• Sicherheitsbeschränkte Pfade: CoreGui, CorePackages, RobloxScript, RobloxScriptSecurity

Direction und Apply Mode

Direction (Sync-Richtung pro Typ)

• forward: Studio → Lokal
• reverse: Lokal → Studio
• bidirectional: Beide Richtungen

Die Typen werden separat verwaltet: scripts, values, containers, data, services.

Apply Mode (Wie Reverse-Änderungen angewendet werden)

• manual: Der Benutzer überprüft und genehmigt Änderungen, bevor sie auf Studio angewendet werden
• auto: Erkannte Änderungen werden automatisch angewendet

Mit Pro können Sie unterschiedliche Direction/Apply Mode-Einstellungen pro Typ konfigurieren, um eine fein abgestimmte Workflow-Steuerung zu erreichen.

manage_sync Action-Referenz (Pro)

Empfohlene Workflows

1) Sicher beginnen

• Führen Sie zuerst einen Full Sync aus, um den aktuellen Zustand als Ihre Baseline festzulegen.
• Verwenden Sie zunächst den manual Apply-Modus, um das Risiko unerwarteter Änderungen zu reduzieren.

2) Änderungen mit KI vornehmen

• “Prüfe den Sync-Status und fasse nur die riskanten Änderungen basierend auf dem letzten Verlauf zusammen.”
• “Refaktoriere zuerst die Skripte in ServerScriptService und behalte einen Änderungsverlauf bei.”

3) Konflikte lösen

Während des bidirektionalen Sync erscheint ein Konfliktlösungsbildschirm, wenn Änderungen sowohl auf der Studio- als auch auf der lokalen Seite erkannt werden.

• Studio Priority: Überschreiben unter Verwendung von Studio als Quelle der Wahrheit
• Local Priority: Lokale Dateien auf Studio anwenden
• Per-File: Wählen Sie für jede Datei einzeln, welche Seite Vorrang hat

4) Wiederherstellung, wenn etwas schiefläuft

• Verwenden Sie history, um kürzliche Änderungen nachzuverfolgen
• Verwenden Sie read_file, um die benötigte Datei zu inspizieren
• Wenden Sie den wiederhergestellten Inhalt mit write_file an und überprüfen Sie den Studio-Status erneut

Dateiformat (v2 Nested Directory)

Jede Roblox-Instanz wird in einem eigenen Verzeichnis mit Meta-Dateien darin gespeichert:

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

Namenskonventionen:

• Eigenschaften: {Name}/{Name}.props.json
• Skripte: {Name}/{Name}.server.luau / .client.luau / .module.luau
• Values: {Name}/{Name}.value.json

Instanzen mit demselben Namen erhalten ein ~N-Suffix in ihrem Verzeichnis, um sie zu unterscheiden (z. B. Part~2/Part.props.json). Wenn ein Name ~ enthält, wird es als ~~ escaped (z. B. Part~2 → Part~~2/). Odd-Count Tilde Rule: ein nachgestelltes ~+N wird nur dann als Kollisionssuffix interpretiert, wenn die Anzahl der Tilden ungerade ist.

luau-lsp-Integration

WEPPY Sync kann automatisch die von luau-lsp benötigte Sourcemap-Datei generieren, sodass Sie Roblox-bewusste Editor-Funktionen erhalten, ohne ein separates Rojo-Projekt einrichten zu müssen.

Nach dem Abschluss eines Full Sync generiert WEPPY die folgenden Dateien:

• Place-Sourcemap: weppy-project-sync/place_<id>/sourcemap.json
• Root-kanonische Datei: weppy-project-sync/sourcemap.json

Wenn luau-lsp die WEPPY-Sourcemap liest, erhalten Sie Verbesserungen bei:

• game.*-Autovervollständigung
• Navigation basierend auf synchronisierten Skripten
• require-Auflösung über synchronisierte Skripte hinweg

Empfohlene Einrichtung

1. Führen Sie einmal einen Full Sync aus, damit WEPPY weppy-project-sync/sourcemap.json erstellt.
2. Verweisen Sie die luau-lsp-Sourcemap-Einstellung in Ihrem Editor auf weppy-project-sync/sourcemap.json.
3. Wenn Ihr Client das Deaktivieren der automatischen Rojo-Generierung erlaubt, setzen Sie luau-lsp.sourcemap.autogenerate auf false.

VSCode-Einstellungsbeispiel:

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

weppy-project-sync/sourcemap.json folgt dem aktuellen repräsentativen Place im Projekt. Um es an einen bestimmten Place anzuheften, konfigurieren Sie luau-lsp so, dass es direkt auf die weppy-project-sync/place_<id>/sourcemap.json dieses Place verweist.