goldsync 0.1.16 → 0.1.34

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:
+GoldSync runs on Windows with Node.js 20 or newer. From your game repository, run:
 
 ```powershell
-npm run package:companion
+npx --yes goldsync@latest install
 ```
 
-Send the ZIP from `dist` to the programmer and extract it anywhere. From the game repository terminal, run its installer as one command:
+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.
 
-```powershell
-& "C:\path\to\GoldSync-Companion\install.cmd"
-```
-
-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.
+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.
 
-For a local development build, run:
-
-```powershell
-.\install.ps1
-```
+## Configure your roots
 
-That installs dependencies, builds the Studio plugin and VS Code extension, creates the latest VSIX under `extension`, and installs it locally.
-
-## 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,69 @@ 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.
 
-## Daily use
+## How files are grouped
 
-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.
+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.
 
-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.
+![Folders organize directories; the first asset is saved whole](https://unpkg.com/goldsync@0.1.31/media/file-boundaries.png)
 
-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.
+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.
 
-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.
+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.
 
-## Merge conflicts
+## Configuration for larger assets
 
-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.
+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.
 
-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`.
+![A Configuration and all its children become one file](https://unpkg.com/goldsync@0.1.31/media/configuration-assets.png)
 
-## Development
+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.
 
-Run the automated tests from this repository:
+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.
 
-```powershell
-npm test
-```
+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.
 
-Package the Marketplace extension:
+## Daily use
+
+To make local files authoritative and replace the configured Studio roots completely, run:
 
 ```powershell
-cd extension
-npm install
-npm run package
+npx --yes goldsync@latest restore-studio --yes
 ```
 
-To run the standalone diagnostic server against a game config:
+Update GoldSync, restart Studio, and connect Rojo first. This command discards unsaved Studio changes inside the configured roots, removes extra instances, and resets their sync state. Other Studio roots and local files are unchanged. It validates every snapshot before replacing the roots and reports completion in the terminal. It requires version 2 tree roots.
 
-```powershell
-.\start.ps1 C:\path\to\goldsync.project.json
-```
+The command uses the files currently on disk. It does not fetch Git or remove old local `.rbxm` files. Restore the local assets from your intended Git revision first if that is the copy you want in Studio.
+
+Matching assets synchronize automatically. When an entry needs attention, choose the copy you want to keep:
+
+| Control | Direction |
+| --- | --- |
+| **Push →** | Studio to repository file |
+| **← Pull** | Repository file to Studio |
+
+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.
+
+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.
+
+GoldSync pauses normal syncing while Rojo is disconnected.
+
+## Duplicate names and embedded scripts
+
+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.
+
+Scripts, LocalScripts, and ModuleScripts inside assets are saved with their source. Keep separately managed game code in Rojo's source directories.
+
+## Git conflicts
+
+GoldSync pauses conflicted files while other assets continue syncing. Expand an affected item and select **Open Merge Workspace**.
+
+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.
+
+Check Result, then select **Resolve Result**. GoldSync writes the resulting RBXM, stages it in Git, and clears the conflict.
+
+## Development
+
+Run the automated tests with `npm test`. The source includes the companion service, Studio plugin, installer, and optional editor extension.