|
| 1 | +--- |
| 2 | +title: Script Sync |
| 3 | +description: Use Studio's Script Sync feature to edit your Luau scripts in an external text editor. |
| 4 | +--- |
| 5 | + |
| 6 | +import BetaAlert from '../includes/beta-features/beta-alert.md' |
| 7 | + |
| 8 | +<BetaAlert betaName="Script Sync" leadIn="Script Sync is currently in Studio beta. To enable this feature, select " leadOut="." components={props.components} /> |
| 9 | + |
| 10 | +Roblox Studio has a built-in [script editor](../studio/script-editor.md) for editing the code in your Roblox project. The editor includes key features like linting, type checking, autocomplete and collaborative editing. |
| 11 | + |
| 12 | +Many developers, however, have a preferred text editor, such as [Visual Studio Code](https://code.visualstudio.com), [Sublime Text](https://www.sublimetext.com), [Notepad++](https://notepad-plus-plus.org), or [Vim](https://www.vim.org). Popular development environments often have features or plugins that don't exist in Studio. To use an external text editor with Studio, enable the **Script Sync** feature. |
| 13 | + |
| 14 | +Script Sync works by synchronizing the scripts in your [data model](../projects/data-model.md) to text files on your local disk. Changes made to the Luau files on disk are applied to the scripts in Studio, and vice versa. This synchronization means that you can edit a script in an external editor like VS Code and immediately see the change in Studio. |
| 15 | + |
| 16 | +## When to use Script Sync |
| 17 | + |
| 18 | +- If you want to use your preferred text editor or check code into version control, but use Studio for everything else, Script Sync is a good fit. It also works with Roblox's [built-in collaboration tools](../projects/collaboration.md), which third-party tools often do not. |
| 19 | + |
| 20 | + Script Sync works well with existing Roblox projects, as it's an extra feature rather than a total shift in how you manage the project. |
| 21 | + |
| 22 | +- If you want to check your entire project (not just code) into version control or use your file system as the source of truth for your project, [third-party tools](../projects/external-tools.md) like Rojo are a better choice. |
| 23 | + |
| 24 | +<Alert severity="info"> |
| 25 | +It is currently not possible to control Roblox Studio's debugger from an external development environment. |
| 26 | +</Alert> |
| 27 | + |
| 28 | +## Set up Script Sync |
| 29 | + |
| 30 | +1. In the **Explorer**, select one or more folders that you want to sync. |
| 31 | +1. Right-click and select **Script Sync** ⟩ **Sync with Directory**. |
| 32 | + |
| 33 | + <img src="../assets/scripting/external-tools/script-sync.png" alt="The Explorer window with the Script Sync menu expanded." width="400" /> |
| 34 | + |
| 35 | +1. Choose a directory on your computer (or create a new one) and click **Save**. |
| 36 | +1. In Studio, right-click on the folder again and select **Script Sync** ⟩ **Reveal in Explorer** (Windows) or **Reveal in Finder** (macOS). |
| 37 | +1. Open the directory in your preferred text editor. |
| 38 | + |
| 39 | + Alternatively, right-click an individual script in Studio and select **Open in External Editor**. |
| 40 | + |
| 41 | +You can sync individual scripts, but we **highly** recommend syncing folders; if you sync a folder, Script Sync automatically syncs its child folders and scripts, which lets you create, delete, and rename scripts without having to enable syncing each time. |
| 42 | + |
| 43 | +<Alert severity="success"> |
| 44 | +You only have to set up syncing once. When you restart Studio and open your place, Script Sync remembers what you were syncing and resumes automatically. |
| 45 | +</Alert> |
| 46 | + |
| 47 | +## Key tips |
| 48 | + |
| 49 | +- Script Sync only syncs `Class.Script`, `Class.LocalScript`, `Class.ModuleScript` and `Class.Folder` instances. All other instances in a synced folder are ignored. Avoid syncing folders that contain scripts alongside other instances. |
| 50 | +- Don't sync scripts that have attributes or tags. Script Sync ignores these, which can lead to data loss if you create or delete scripts or start syncing with an older version of your files on disk. |
| 51 | +- Script Sync requires the names of scripts be compatible with your file system—no duplicate names or unsupported characters. If Studio encounters any of these issues, it throws an error and asks you to resolve the situation before resuming sync. |
| 52 | +- If any synced files or folders change while Studio is closed, Studio asks you how you want to resolve the situation when you reopen the place. |
| 53 | +- Deleting a top-level (or "root") instance—the instance you initially synced—on your local disk can cause Studio to throw an error. To delete a top-level instance: |
| 54 | + |
| 55 | + 1. In Studio, right-click the script or folder and select **Script Sync** ⟩ **Stop Sync**. |
| 56 | + 1. Choose the **Delete file(s)** or **Delete folder(s)** option to delete the instance from your local disk. |
| 57 | + 1. Delete the script or folder in Studio. |
| 58 | + |
| 59 | + You can delete child instances in Studio or on your local disk without disabling syncing, and the deletion syncs as you'd expect. |
| 60 | + |
| 61 | +## Set up a language server |
| 62 | + |
| 63 | +Language servers give your text editor language-specific features like autocomplete, type checking, "go to definition," and more. For VS Code, we recommend [Luau Language Server](https://marketplace.visualstudio.com/items?itemName=JohnnyMorganz.luau-lsp). |
| 64 | + |
| 65 | +Language server protocol (LSP) extensions need to understand the data model hierarchy of a project to work properly. The VS Code extension comes with a companion Studio plugin ([Luau Language Server Companion](https://create.roblox.com/store/asset/10913122509/Luau-Language-Server-Companion)) that provides this data. |
| 66 | + |
| 67 | +**We highly recommend installing both.** If you use the VS Code extension and companion Studio plugin, language features will work correctly in VS Code while using Script Sync. |
| 68 | + |
| 69 | +## Recommended extensions |
| 70 | + |
| 71 | +<Alert severity="info"> |
| 72 | +The community maintains these extensions. We recommend them based on their functionality, but can't offer guarantees about performance or security. Before installing an extension, check that it comes from a reputable source and isn't malicious. |
| 73 | +</Alert> |
| 74 | + |
| 75 | +- [Roblox Luau LSP](https://marketplace.visualstudio.com/items?itemName=JohnnyMorganz.luau-lsp) and [Luau Language Server Companion](https://create.roblox.com/store/asset/10913122509/Luau-Language-Server-Companion) - Language features (see above) |
| 76 | +- [selene](https://marketplace.visualstudio.com/items?itemName=Kampfkarren.selene-vscode) - Static code analysis (linting) |
| 77 | +- [StyLua](https://marketplace.visualstudio.com/items?itemName=JohnnyMorganz.stylua) - Automatic code formatting |
| 78 | + |
| 79 | +## Sync rules |
| 80 | + |
| 81 | +When syncing an instance with children with a directory on disk, Studio will automatically sync create, rename, move, and delete operations on children with the corresponding files and folders on disk. This approach lets you maintain your code without having to manually stop and start syncing on individual scripts. |
| 82 | + |
| 83 | +On disk, Script Sync uses the following rules to disambiguate the different types of scripts from each other. |
| 84 | + |
| 85 | +| Naming convention on disk | Instance type in Studio | |
| 86 | +| :---- | :---- | |
| 87 | +| `name.luau` | `Class.ModuleScript` | |
| 88 | +| `name.server.luau` | Script with `Server` `Class.Script.RunContext` | |
| 89 | +| `name.client.luau` | Script with `Client` `Class.Script.RunContext` | |
| 90 | +| `name.local.luau` | `Class.LocalScript` | |
| 91 | +| `name.legacy.luau` | Script with `Legacy` `Class.Script.RunContext` | |
| 92 | +| `name.plugin.luau` | Script with `Plugin` `Class.Script.RunContext` | |
| 93 | +| `name/` (directory) | `Class.Folder` | |
| 94 | +| `name/init.*.luau` | Script instance with children. Type (`*`) is determined by the above rules. | |
| 95 | + |
| 96 | +## Settings |
| 97 | + |
| 98 | +Script Sync has several settings in the **Studio Settings** window (<kbd>Alt</kbd><kbd>S</kbd> or <kbd></kbd>⌥<kbd>S</kbd>). The default options are a good fit for most use cases. |
| 99 | + |
| 100 | +| Setting | Description | |
| 101 | +| :---- | :---- | |
| 102 | +| Auto resume sync on place open | Whether Studio should resume syncing when you open a place. Disabling this setting dramatically reduces the utility of Script Sync. | |
| 103 | +| Resume conflicted sync on place open | How Studio should handle conflicts when you open a place. The default option, **Do not resume**, forces you to resolve conflicts manually to avoid data loss. You can also choose to prefer the version on disk or the version in Studio. | |
| 104 | +| Keep local files/directories after sync | How to handle files on disk after you select **Script Sync** > **Stop Sync** in Studio. |
| 105 | +| File extension | The file extension to use for scripts on disk. |
![rbx-open-source-docs[bot]](https://avatars.githubusercontent.com/in/357490?v=4&size=40){kind=avatar}
0 commit comments