goldsync 0.1.16 → 0.1.31

package/README.md

@@ -1,85 +1,52 @@
 # GoldSync
 
-<p align="center"><img src="https://unpkg.com/goldsync@latest/media/icon.png" alt="GoldSync" width="128"></p>
+<p align="center"><img src="https://unpkg.com/goldsync@0.1.31/media/icon.png" alt="GoldSync" width="128"></p>
 
-GoldSync synchronizes configured, code-free Roblox Studio hierarchies with native `.rbxm` files. Rojo continues to own scripts.
-
-This is the standalone GoldSync source and build folder. It stays separate from game projects. Each game project contains its own `goldsync.project.json`, one Rojo session-marker mapping, and its synced RBXM files.
+GoldSync synchronizes Roblox Studio assets with native `.rbxm` files. It saves complete models, UI, effects, and embedded scripts so your team can track them in Git. Rojo handles the separate source directories mapped in your project.
 
 ## Install
 
-Run this once from the game repository terminal in Cursor, VS Code, or Zed:
-
-```powershell
-npx goldsync install
-```
-
-It installs the background service, Roblox Studio plugin, project registration, and Windows startup entry. Cursor and Zed use the same editor-independent service; neither needs an editor extension.
-
-If `npx` is unavailable, install Node.js and GoldSync together with:
-
-```powershell
-winget install --id OpenJS.NodeJS.LTS --exact --accept-package-agreements --accept-source-agreements; $env:Path="$env:ProgramFiles\nodejs;$env:Path"; npx --yes goldsync install
-```
-
-Restart Studio once after the first installation. Studio may ask for permission to access `127.0.0.1`.
-
-For offline distribution, build the companion package from this folder:
-
-```powershell
-npm run package:companion
-```
-
-Send the ZIP from `dist` to the programmer and extract it anywhere. From the game repository terminal, run its installer as one command:
+GoldSync runs on Windows with Node.js 20 or newer. From your game repository, run:
 
 ```powershell
-& "C:\path\to\GoldSync-Companion\install.cmd"
+npx --yes goldsync@latest install
 ```
 
-Running the installer from another game registers that game too. Registering another clone with the same `projectId` replaces the old clone, preventing two copies of one project from claiming the same Rojo session. Cursor's extension and the companion can run together; they share one broker automatically.
+The installer sets up the background service, Studio plugin, project registration, and Windows startup entry. Save and restart Studio after installation or an update. Allow localhost access if Studio asks.
 
-For a local development build, run:
+Open the repository, run `rojo serve`, and connect Studio through Rojo. GoldSync selects the matching project automatically. Cursor, VS Code, and Zed use the same service; an editor extension is not required.
 
-```powershell
-.\install.ps1
-```
-
-That installs dependencies, builds the Studio plugin and VS Code extension, creates the latest VSIX under `extension`, and installs it locally.
+## Configure your roots
 
-## Configure a game
-
-Place `goldsync.project.json` at the game repository root:
+Create `goldsync.project.json` in the game repository:
 
 ```json
 {
-  "version": 1,
+  "version": 2,
   "name": "My Game",
   "projectId": "my-game",
   "roots": [
     {
-      "id": "effects",
-      "studioPath": ["ReplicatedStorage", "Assets", "Effects"],
-      "file": "assets/ReplicatedStorage/Assets/Effects.rbxm"
+      "id": "assets",
+      "mode": "tree",
+      "studioPath": ["ReplicatedStorage", "Assets"],
+      "directory": "assets/ReplicatedStorage/Assets"
     },
     {
-      "id": "main-pages",
-      "studioPath": ["StarterGui", "Main", "Pages"],
-      "directory": "assets/StarterGui/Main/Pages",
-      "splitDepth": 1
+      "id": "main",
+      "mode": "tree",
+      "studioPath": ["StarterGui", "Main"],
+      "directory": "assets/StarterGui/Main"
     }
   ]
 }
 ```
 
-A `file` root becomes one RBXM. A `directory` root creates separate files for descendants at `splitDepth`. Split at complete models, effects, or UI components—not individual parts or attachments. Never map the same hierarchy in Rojo, and do not include scripts inside a GoldSync root.
-
-Directory roots can contain more specific roots. Discovery skips branches owned by those roots, including existing files on disk. For example, split `ReplicatedStorage.Assets` at depth 1 and add another depth-1 directory root for `ReplicatedStorage.Assets.Effects`. New asset categories and individual effects are discovered automatically, without creating an overlapping `Effects.rbxm`. Existing explicit file roots can stay in place to preserve their sync history. File roots cannot contain other roots because their snapshots include the entire subtree.
+List only the top roots. Do not map the same hierarchy through both Rojo and GoldSync.
 
-When upgrading an existing project, put the new parent directory roots in the optional top-level `discoveryRoots` array, using the same fields as directory roots. Older GoldSync versions ignore that array, so they cannot create overlapping snapshots before the service is restarted with nested-root support. Existing roots and files remain unchanged.
+GoldSync reads the Rojo project name and port from `default.project.json` and detects active port overrides. Set `rojo.projectFile` if you use a different project filename.
 
-GoldSync reads the Rojo project name and fallback `servePort` from `default.project.json`. It automatically detects `rojo serve --port` overrides and verifies the listener's project name before connecting. That active Rojo session selects the GoldSync workspace, so Studio place IDs and names do not need configuration. Set `rojo.projectFile` only when the repository uses another project file.
-
-Map GoldSync's generated live-session marker in the Rojo project tree:
+Include the generated session marker in your Rojo project tree:
 
 ```json
 "ServerStorage": {
@@ -89,45 +56,59 @@ Map GoldSync's generated live-session marker in the Rojo project tree:
 }
 ```
 
-The extension generates that ignored file from Rojo's current session ID. Only Studio windows that receive the current marker from Rojo can access the matching GoldSync workspace. A disconnected or different place is rejected.
+The service generates the marker. Keep `.goldsync/` ignored by Git. The marker binds the Studio window to its active Rojo session and repository.
+
+## How files are grouped
+
+Below a configured root, each **Folder** becomes a directory. The **first descendant that is not a Folder becomes one file with its entire subtree**. Folders inside that asset remain inside its file.
+
+![Folders organize directories; the first asset is saved whole](https://unpkg.com/goldsync@0.1.31/media/file-boundaries.png)
+
+For example, if `Effects` is a Folder and `DeathEffect` is a Model, edits anywhere inside DeathEffect change `Effects/DeathEffect.rbxm`. If DeathEffect is a Folder instead, GoldSync keeps walking until it reaches each child asset.
+
+Configured top roots always act as containers, even for a ScreenGui such as Main. Plain, nonempty Folders need only a directory. Container properties, attributes, tags, empty Folders, and non-archivable Folders are preserved with `_root.rbxm` where needed.
+
+## Configuration for larger assets
+
+Use a Roblox **Configuration** instance in place of a Folder when a collection should stay in one file. Configuration has a gear icon in Studio.
+
+![A Configuration and all its children become one file](https://unpkg.com/goldsync@0.1.31/media/configuration-assets.png)
+
+A Configuration named `PowerAssets` becomes `PowerAssets.rbxm`, including all effects, folders, and scripts below it. Pull replaces that complete subtree. Camera keyframes and effects whose children reference each other are useful candidates for this grouping.
+
+Folders let teammates edit separate files independently. Configuration groups the collection into one Git change and one conflict unit. Keep referenced instances together when they belong to the same asset.
+
+When changing a Folder to another class, Push the changed parent. GoldSync verifies the exported subtree and backs up the previous files before replacing their layout.
 
 ## Daily use
 
-1. Open the game repository in Cursor, VS Code, or Zed.
-2. Run `rojo serve`.
-3. Open a configured place in Roblox Studio.
-4. Confirm the GoldSync status bar and Studio widget are connected.
+Matching assets synchronize automatically. When an entry needs attention, choose the copy you want to keep:
 
-Studio and file edits then synchronize automatically. On the first connection, if both sides already contain data, use **Push Studio** or **Pull File** once to select the authoritative copy. Stopping Rojo pauses normal synchronization.
+| Control | Direction |
+| --- | --- |
+| **Push →** | Studio to repository file |
+| **← Pull** | Repository file to Studio |
 
-Deleting a synchronized root in Studio deletes its RBXM file. GoldSync refuses the deletion if that file changed since Studio last synchronized it, preserving the file for manual conflict resolution.
+Attention entries appear under collapsible parent paths with short child names. Use an individual arrow for one asset, or the attention section's Push All / Pull All controls for all unresolved entries.
 
-The broker uses `127.0.0.1:34873`. Multiple repositories and different Rojo projects may be served at once because every Studio request is bound to its project and live Rojo session. GoldSync refuses multiple simultaneous Rojo servers for the same project name.
+Missing Studio assets require an explicit Pull to restore them. Push an intentionally removed Folder to remove its saved subtree with a backup and file-version checks. Configured roots cannot be deleted this way. Completed deletions do not need another Push.
 
-## Merge conflicts
+GoldSync pauses normal syncing while Rojo is disconnected.
 
-Configured RBXM conflicts pause that file before either side can overwrite it. GoldSync shows a VS Code notification naming the project. **Open Conflict Viewer** temporarily connects that workspace even while Rojo is offline.
+## Duplicate names and embedded scripts
 
-In Studio, **Open Merge Workspace** creates Base, Yours, Theirs, and editable Result trees under `ServerStorage.GoldSync Conflicts`. Use **Property Diff** when useful, edit Result, then click **Resolve Result**. Resolving writes and stages the selected RBXM file. The viewer is optional and can be disabled with `goldsync.conflictNotifications.enabled`.
+Same-named siblings keep their Studio names. Their files use suffixes such as `Crack1.rbxm`, `Crack1 (1).rbxm`, and `Crack1 (2).rbxm`. A saved `GoldSyncId` attribute maintains each duplicate's identity. Do not edit it manually. Assigned suffixes remain stable when siblings are removed.
 
-## Development
+Scripts, LocalScripts, and ModuleScripts inside assets are saved with their source. Keep separately managed game code in Rojo's source directories.
 
-Run the automated tests from this repository:
+## Git conflicts
 
-```powershell
-npm test
-```
+GoldSync pauses conflicted files while other assets continue syncing. Expand an affected item and select **Open Merge Workspace**.
 
-Package the Marketplace extension:
+The workspace under `ServerStorage.GoldSync Conflicts` contains Base, Yours, Theirs, and an editable Result. Use **Property Diff**, copy selected properties with **Use Yours** or **Use Theirs**, or edit Result directly in Studio.
 
-```powershell
-cd extension
-npm install
-npm run package
-```
+Check Result, then select **Resolve Result**. GoldSync writes the resulting RBXM, stages it in Git, and clears the conflict.
 
-To run the standalone diagnostic server against a game config:
+## Development
 
-```powershell
-.\start.ps1 C:\path\to\goldsync.project.json
-```
+Run the automated tests with `npm test`. The source includes the companion service, Studio plugin, installer, and optional editor extension.