diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index 03690d9..67e34ca 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -57,13 +57,13 @@ export default defineConfig({ collapsed: false, items: [ { - text: 'Project File', + text: 'Project', collapsed: false, items: [ - { text: 'Project File Syntax', link: '/lync/project-format/project-file/project-file-syntax' }, - { text: 'Packages', link: '/lync/project-format/project-file/packages' }, - { text: 'Automated Downloads', link: '/lync/project-format/project-file/automated-downloads' }, - { text: 'Automated Jobs', link: '/lync/project-format/project-file/automated-jobs' } + { text: 'Project File', link: '/lync/project-format/project/project-file' }, + { text: 'Packages', link: '/lync/project-format/project/packages' }, + { text: 'Automated Downloads', link: '/lync/project-format/project/automated-downloads' }, + { text: 'Automated Jobs', link: '/lync/project-format/project/automated-jobs' } ] }, { diff --git a/docs/lync/getting-started/usage/lync-executable.md b/docs/lync/getting-started/usage/lync-executable.md index ae557b3..00a5ef4 100644 --- a/docs/lync/getting-started/usage/lync-executable.md +++ b/docs/lync/getting-started/usage/lync-executable.md @@ -14,7 +14,6 @@ The Lync executable can start a live sync session, build to file, and fetch down `project.json?` - The project file to read from and serve. - `REMOTE?` - Connect to the project's `remoteAddress` instead of the localhost. ::: @@ -40,4 +39,4 @@ This mode works without having Roblox Studio installed and without an internet c The `FETCH` mode downloads the list of sources in the project file. -See [project-format/project-file/automated-downloads](/lync/project-format/project-file/automated-downloads). +See [project-format/project/automated-downloads](/lync/project-format/project/automated-downloads). diff --git a/docs/lync/index.md b/docs/lync/index.md index 3fc828d..7bca8ed 100644 --- a/docs/lync/index.md +++ b/docs/lync/index.md @@ -39,9 +39,9 @@ See [project-format/files/supported-files](/lync/project-format/files/supported- Lync offers additional built-in tools for power users to automate aspects of the project. -- [**Packages**](/lync/project-format/project-file/packages) - Download GitHub repositories and insert their contents into the project. -- [**Automated Downloads**](/lync/project-format/project-file/automated-downloads) - Download a list of sources into the project. -- [**Automated Jobs**](/lync/project-format/project-file/automated-jobs) - Run scripts based on file system event criteria. +- [**Packages**](/lync/project-format/project/packages) - Download GitHub repositories and insert their contents into the project. +- [**Automated Downloads**](/lync/project-format/project/automated-downloads) - Download a list of sources into the project. +- [**Automated Jobs**](/lync/project-format/project/automated-jobs) - Run scripts based on file system event criteria. ### Future Proofed diff --git a/docs/lync/introduction/community-tooling.md b/docs/lync/introduction/community-tooling.md index 26e6bd1..6c01303 100644 --- a/docs/lync/introduction/community-tooling.md +++ b/docs/lync/introduction/community-tooling.md @@ -13,7 +13,7 @@ This list is by no means complete. ::: tip Lync can download packages and keep them up to date. -See [project-format/project-file/packages](/lync/project-format/project-file/packages). +See [project-format/project/packages](/lync/project-format/project/packages). ::: ::: info Language Servers and Linters diff --git a/docs/lync/project-format/files/excel-tables.md b/docs/lync/project-format/files/excel-tables.md index b85c793..e31ec05 100644 --- a/docs/lync/project-format/files/excel-tables.md +++ b/docs/lync/project-format/files/excel-tables.md @@ -10,10 +10,14 @@ The resulting table can be formatted in multiple ways. - `*.Excel.JSON` ::: ::: info Keys -- string `spreadsheet` - A relative path to the associated Excel Spreadsheet. -- string `ref` - The 2D range with which to pull data from. Formatted as `sheetName!rowColumn:rowColumn`, e.g. `Sheet1!A1:C3`. It can also be a [named range](https://support.microsoft.com/en-us/office/create-a-named-range-from-selected-cells-in-a-worksheet-fd8905ed-1130-4cca-9bb0-ad02b7e594fd), which allows the range to be modified from inside the Excel worksheet. -- boolean `hasHeader` - Whether or not the first row should be used as keys for nesting elements in the translated Excel Table. -- number `numColumnKeys` - Defines by how many columns each entry should be nested. +- `spreadsheet`: string + - A relative path to the associated Excel Spreadsheet. +- `ref`: string + - The 2D range with which to pull data from. Formatted as `sheetName!rowColumn:rowColumn`, e.g. `Sheet1!A1:C3`. It can also be a [named range](https://support.microsoft.com/en-us/office/create-a-named-range-from-selected-cells-in-a-worksheet-fd8905ed-1130-4cca-9bb0-ad02b7e594fd), which allows the range to be modified from inside the Excel worksheet. +- `hasHeader`: boolean + - Whether or not the first row should be used as keys for nesting elements in the translated Excel Table. +- `numColumnKeys`: number + - Defines by how many columns each entry should be nested. ::: ## Examples diff --git a/docs/lync/project-format/files/json-models.md b/docs/lync/project-format/files/json-models.md index da0fe0c..c996c98 100644 --- a/docs/lync/project-format/files/json-models.md +++ b/docs/lync/project-format/files/json-models.md @@ -10,12 +10,15 @@ Unlike Model Files (`RBXM`/`RBXMX`\;) their data is limited to that which can be - `*.Model.JSON` ::: ::: info Keys -- string `name` - Instance.Name. -- string `className` - Instance.ClassName. -- {[string]: any} `properties` - Functions as `instance[property] = value`. -- {[string]: any} `attributes` - Functions as `instance:SetAttribute(attribute, value)`. -- {string} `tags` - Functions as `CollectionService:AddTag(instance, tag)` -- {Instance} `children` - The list of children. +- `name`: string *(Optional)* +- `className`: string *(Optional)* +- `properties`: {[string]: any} *(Optional)* + - Functions as `instance[property] = value`. +- `attributes`: {[string]: any} *(Optional)* + - Functions as `instance:SetAttribute(attribute, value)`. +- `tags`: {string} *(Optional)* + - Functions as `CollectionService:AddTag(instance, tag)` +- `children`: {Instance} *(Optional)* ::: ## Example diff --git a/docs/lync/project-format/files/meta-files.md b/docs/lync/project-format/files/meta-files.md index 08f57fd..1a4f13b 100644 --- a/docs/lync/project-format/files/meta-files.md +++ b/docs/lync/project-format/files/meta-files.md @@ -11,10 +11,14 @@ They are used in scenarios where it would be desirable to change the properties - `Init.Meta.JSON` - For directories. ::: ::: info Keys -- string `className` - Instance.ClassName. Usable only with directories. -- {[string]: any} `properties` - Functions as `instance[property] = value`. -- {[string]: any} `attributes` - Functions as `instance:SetAttribute(attribute, value)`. -- {string} `tags` - Functions as `CollectionService:AddTag(instance, tag)` +- `className`: string *(Optional)* + - Usable only with directories. +- `properties`: {[string]: any} *(Optional)* + - Functions as `instance[property] = value`. +- `attributes`: {[string]: any} *(Optional)* + - Functions as `instance:SetAttribute(attribute, value)`. +- `tags`: {string} *(Optional)* + - Functions as `CollectionService:AddTag(instance, tag)` ::: ## Examples diff --git a/docs/lync/project-format/files/supported-files.md b/docs/lync/project-format/files/supported-files.md index 11183a8..e68b247 100644 --- a/docs/lync/project-format/files/supported-files.md +++ b/docs/lync/project-format/files/supported-files.md @@ -15,7 +15,7 @@ All forms of Roblox content can be stored on the filesystem and synced. | TOML Tables | `TOML` | [ModuleScript](https://create.roblox.com/docs/reference/engine/classes/ModuleScript) | | Plain Text | `TXT` | [StringValue](https://create.roblox.com/docs/reference/engine/classes/StringValue) | | Localization Table | `CSV` | [LocalizationTable](https://create.roblox.com/docs/reference/engine/classes/LocalizationTable) | -| [Child Projects](/lync/project-format/project-file/project-file-syntax) | `*.Project.JSON` | Varies | +| [Child Projects](/lync/project-format/project/project-file) | `*.Project.JSON` | Varies | | [Meta Files](/lync/project-format/files/meta-files) | `*.Meta.JSON` | Varies | | [JSON Models](/lync/project-format/files/json-models) | `*.Model.JSON` | Varies | | [Excel Tables](/lync/project-format/files/excel-tables) | `*.Excel.JSON` | [ModuleScript](https://create.roblox.com/docs/reference/engine/classes/ModuleScript) | diff --git a/docs/lync/project-format/project-file/automated-downloads.md b/docs/lync/project-format/project-file/automated-downloads.md deleted file mode 100644 index 0c3dff0..0000000 --- a/docs/lync/project-format/project-file/automated-downloads.md +++ /dev/null @@ -1,4 +0,0 @@ -::: danger UNFINISHED -This documentation is unfinished. -::: -# Automated Downloads diff --git a/docs/lync/project-format/project-file/automated-jobs.md b/docs/lync/project-format/project-file/automated-jobs.md deleted file mode 100644 index 0ca9884..0000000 --- a/docs/lync/project-format/project-file/automated-jobs.md +++ /dev/null @@ -1,4 +0,0 @@ -::: danger UNFINISHED -This documentation is unfinished. -::: -# Automated Jobs diff --git a/docs/lync/project-format/project-file/project-file-syntax.md b/docs/lync/project-format/project-file/project-file-syntax.md deleted file mode 100644 index 04c17dd..0000000 --- a/docs/lync/project-format/project-file/project-file-syntax.md +++ /dev/null @@ -1,4 +0,0 @@ -::: danger UNFINISHED -This documentation is unfinished. -::: -# Project File Syntax diff --git a/docs/lync/project-format/project/automated-downloads.md b/docs/lync/project-format/project/automated-downloads.md new file mode 100644 index 0000000..1bba355 --- /dev/null +++ b/docs/lync/project-format/project/automated-downloads.md @@ -0,0 +1,16 @@ +::: danger UNFINISHED +This documentation is unfinished. +::: + +# Automated Downloads + +## Syntax + +::: info Keys +- `name`: string +- `url`: string +- `type`: string +- `headers`: {\[string]: string} +- `postData`: (string | Object) +- `path`: string +::: diff --git a/docs/lync/project-format/project/automated-jobs.md b/docs/lync/project-format/project/automated-jobs.md new file mode 100644 index 0000000..b0a019b --- /dev/null +++ b/docs/lync/project-format/project/automated-jobs.md @@ -0,0 +1,13 @@ +::: danger UNFINISHED +This documentation is unfinished. +::: + +# Automated Jobs + +## Syntax + +::: info Keys +- `globPath`: string +- `on`: \{string} +- `commandName`: string +::: diff --git a/docs/lync/project-format/project-file/packages.md b/docs/lync/project-format/project/packages.md similarity index 99% rename from docs/lync/project-format/project-file/packages.md rename to docs/lync/project-format/project/packages.md index 6c02c9b..bb49704 100644 --- a/docs/lync/project-format/project-file/packages.md +++ b/docs/lync/project-format/project/packages.md @@ -1,6 +1,7 @@ ::: danger UNFINISHED This documentation is unfinished. ::: + # Packages ::: tip diff --git a/docs/lync/project-format/project/project-file.md b/docs/lync/project-format/project/project-file.md new file mode 100644 index 0000000..53c8129 --- /dev/null +++ b/docs/lync/project-format/project/project-file.md @@ -0,0 +1,130 @@ +# Project File + +Lync projects define the Instance tree inside Roblox, as well as configuring the behavior for building to file, sourcemaps, [**Automated Downloads**](/lync/project-format/project/automated-downloads), [**Automated Jobs**](/lync/project-format/project/automated-jobs), and more. + +## Syntax + +::: info File Name +- `Default.Project.JSON` + - The default project to load when running Lync without the project file argument. +- `*.Project.JSON` + - For non-default projects. +::: +::: info Keys +- `name`: string + - The name of the project for informational purposes. +- `base`: string *(Optional)* + - The path to the file to build in when using `OPEN` and `BUILD` modes. + - When omitted, Lync builds in a new file. +- `build`: string + - The path to save the finished build file when using `OPEN` and `BUILD` modes. +- `port`: number + - The network port to serve the project on when using `SERVE` and `OPEN` modes. +- `remoteAddress`: string *(Optional)* + - The IP address or hostname to connect to instead of the localhost. +- `servePlaceIds`: {number} *(Optional)* + - An array of place IDs to serve. Lync will refuse to connect if the open place ID isn't in the array. +- `globIgnorePaths`: {string} *(Optional)* + - An array of glob paths to ignore when mapping the project. +- `sourcemapEnabled`: {RBXM: boolean, RBXMX: boolean} *(Optional)* + - Controls which types of Model Files (`RBXM`/`RBXMX`) are parsed during sourcemap generation. +- `sources`: Object *(Optional)* + - See [project-format/project/automated-downloads](/lync/project-format/project/automated-downloads). +- `jobs`: Object *(Optional)* + - See [project-format/project/automated-jobs](/lync/project-format/project/automated-jobs). +- `tree`: Object + - The root Instance. +::: +::: danger UNAVAILABLE +`remoteAddress` is unimplemented. +::: + +### Example + +```json +{ + "name": "Example Project", + "base": "Base.rbxl", + "build": "Build.rbxl", + "port": 34873, + "remoteAddress": "localhost", + "servePlaceIds": [ 1818 ], + "globIgnorePaths": [ "ignoredDirectory/**" ], + "sourcemapEnabled": { + "RBXM": true, + "RBXMX": true + }, + "sources": { ... }, + "jobs": { ... }, + + "tree": { + ... + } +} +``` + +## Instance Definitions + +::: info Keys +- `$className`: string *(Optional)* + - Has no effect when `$path` is specified. +- `$path`: (string | Object) *(Optional)* + - A path to a file or directory that overrides the Instance Definition. + - Use `"$path": { "optional": "..." }` when the file or directory could possibly be non-existant. + - Use `"$path": { "package": "...", "type": "..." }` for [Packages](/lync/project-format/project/packages). +- `$properties`: {[string]: any} *(Optional)* + - Functions as `instance[property] = value`. +- `$attributes`: {[string]: any} *(Optional)* + - Functions as `instance:SetAttribute(attribute, value)`. +- `$tags`: {string} *(Optional)* + - Functions as `CollectionService:AddTag(instance, tag)`. +- `$clearOnSync`: boolean *(Optional)* + - When `true`, the associated Instance and its descendants will be destroyed in Studio when performing sync operations. + - Useful for clearing unmapped content when modifications are made outside your active live sync session. +::: + +### Values + +Values not storable in JSON, like `Enum`, `Color3`, `Vector3` and so on, should be represented as a single Lua string wrapped inside an array (e.g., `[ "Value" ]`.) + + +### Example + +```json +"Wood Brick": { + "$className": "Part", + "$properties": { + "Color": [ "Color3.fromRGB(132, 66, 4)" ], + "Material": [ "Enum.Material.Wood" ], + "Transparency": 0, + "Position": [ "Vector3.new(0, 10, 0)" ], + "Anchored": true + }, + "$attributes": { + "ExampleAttribute": true + }, + "$tags": [ "ExampleTag1", "ExampleTag2", "ExampleTag3" ] +} +``` + +## Terrain + +::: info Keys +- `$terrainRegion`: {[1]: string, [2]: Lua, [3]: boolean} *(Optional)* + - Functions as `Terrain:PasteRegion(region, corner, pasteEmptyCells)`. +- `$terrainMaterialColors`: {[string]: Lua} *(Optional)* + - Functions as `Terrain:SetMaterialColor(material, value)`. +::: + +### Example + +```json +"Workspace": { + "Terrain": { + "$terrainRegion": [ "Assets/TerrainRegion.rbxm", [ "Vector3int16.new(-32000, -32000, -32000)" ], true ], + "$terrainMaterialColors": { + "Grass": [ "Color3.new(0, 0.5, 0)" ] + } + } +} +``` \ No newline at end of file diff --git a/docs/lync/project-format/sourcemap.md b/docs/lync/project-format/sourcemap.md index ad490a1..1073804 100644 --- a/docs/lync/project-format/sourcemap.md +++ b/docs/lync/project-format/sourcemap.md @@ -10,10 +10,11 @@ This file cannot be deleted and should be ignored unless you're a tool developer - `sourcemap.json` ::: ::: info Keys -- string `name` - Instance.Name. -- string `className` - Instance.ClassName. -- {string} `filePaths` - The list of files that have an effect on the Instance. -- {Instance} `children` - The list of children. +- `name`: string +- `className`: string +- `filePaths`: \{string} + - The list of files that have an effect on the Instance. +- `children`: \{Instance} ::: ## Example