diff --git a/docs/guide/existing-game.md b/docs/guide/existing-game.md index 5a8fab7c..7edb4a0d 100644 --- a/docs/guide/existing-game.md +++ b/docs/guide/existing-game.md @@ -1,6 +1,9 @@ -**TODO** +**This page is under construction!** ## Summary +* Tools to port existing games are in progress! + * [rbxlx-to-rojo](https://github.com/rojo/rbxlx-to-rojo) + * `rojo export` ([issue #208](https://github.com/rojo-rbx/rojo/issues/208)) * Can port as much or as little of your game as you like * Rojo can manage just a slice of your game! * Some Roblox idioms aren't very well supported diff --git a/docs/guide/installation.md b/docs/guide/installation.md index b56f31c8..7fc21d1e 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -13,6 +13,9 @@ Rojo has two components: The plugin will show errors in the Roblox Studio output window if there is a version mismatch. +## Visual Studio Code Extension +If you use Visual Studio Code, you can install [the Rojo VS Code extension](https://marketplace.visualstudio.com/items?itemName=evaera.vscode-rojo), which will install both halves of Rojo for you. It even has a nifty UI to sync files and start/stop the Rojo server! + ## Installing the CLI ### Installing from GitHub @@ -40,7 +43,4 @@ Download the attached `rbxm` file and put it into your Roblox Studio plugins fol {: align="center" } ### Installing from Roblox.com -Visit [Rojo's Roblox.com Plugin page](https://www.roblox.com/library/1997686364/Rojo-0-5-0-alpha-3) in Roblox Studio and press **Install**. - -## Visual Studio Code Extension -If you use Visual Studio Code, you can install [Evaera's unofficial Rojo extension](https://marketplace.visualstudio.com/items?itemName=evaera.vscode-rojo), which will install both halves of Rojo for you. It even has a nifty UI to sync files and start/stop the Rojo server! \ No newline at end of file +Visit [Rojo's Roblox.com Plugin page](https://www.roblox.com/library/1997686364/Rojo-0-5-0-alpha-3) in Roblox Studio and press **Install**. \ No newline at end of file diff --git a/docs/guide/migrating-to-epiphany.md b/docs/guide/migrating-to-epiphany.md index 5adb36f9..87acf09c 100644 --- a/docs/guide/migrating-to-epiphany.md +++ b/docs/guide/migrating-to-epiphany.md @@ -55,4 +55,9 @@ All other values are considered children, where the key is the instance's name, ## Migrating Unknown Files If you used Rojo to sync in files as `StringValue` objects, you'll need to make sure those files end with the `txt` extension to preserve this in Rojo 0.5.x. -Unknown files are now ignored in Rojo instead of being converted to `StringValue` objects. \ No newline at end of file +Unknown files are now ignored in Rojo instead of being converted to `StringValue` objects. + +## Migrating `init.model.json` files +In Rojo 0.4.x, it's possible to create a file named `init.model.json` that lets you describe a model that becomes the container for all of the other files in the folder, just like `init.lua`. + +In Rojo 0.5.x, this feature has been replaced with `init.meta.json` files. See [Sync Details](../reference/sync-details) for more information about these new files. \ No newline at end of file diff --git a/docs/reference/sync-details.md b/docs/reference/sync-details.md index ae64e7fe..75a6e6f3 100644 --- a/docs/reference/sync-details.md +++ b/docs/reference/sync-details.md @@ -3,17 +3,18 @@ This page aims to describe how Rojo turns files on the filesystem into Roblox ob [TOC] ## Overview -| File Name | Instance Type | -| -------------- | ------------------- | -| any directory | `Folder` | -| `*.server.lua` | `Script` | -| `*.client.lua` | `LocalScript` | -| `*.lua` | `ModuleScript` | -| `*.csv` | `LocalizationTable` | -| `*.txt` | `StringValue` | -| `*.model.json` | Any | -| `*.rbxm` | Any | -| `*.rbxmx` | Any | +| File Name | Instance Type | +| -------------- | ------------------------- | +| any directory | `Folder` | +| `*.server.lua` | `Script` | +| `*.client.lua` | `LocalScript` | +| `*.lua` | `ModuleScript` | +| `*.csv` | `LocalizationTable` | +| `*.txt` | `StringValue` | +| `*.model.json` | Any | +| `*.rbxm` | Any | +| `*.rbxmx` | Any | +| `*.meta.json` | Modifies another instance | ## Limitations Not all property types can be synced by Rojo in real-time due to limitations of the Roblox Studio plugin API. In these cases, you can usually generate a place file and open it when you start working on a project. @@ -24,7 +25,9 @@ Some common cases you might hit are: * `MeshPart.MeshId` * `HttpService.HttpEnabled` -For a list of all property types that Rojo can reason about, both when live-syncing and when building place files, look at [rbx_tree's type coverage chart](https://github.com/LPGhatguy/rbx-tree#property-type-coverage). +For a list of all property types that Rojo can reason about, both when live-syncing and when building place files, look at [rbx-dom's type coverage chart](https://github.com/rojo-rbx/rbx-dom#property-type-coverage). + +This limitation may be solved by [issue #205](https://github.com/rojo-rbx/rojo/issues/205) in the future. ## Folders Any directory on the filesystem will turn into a `Folder` instance unless it contains an 'init' script, described below. @@ -88,4 +91,54 @@ Rojo supports both binary (`.rbxm`) and XML (`.rbxmx`) models generated by Roblo Support for the `rbxmx` is very good, while support for `rbxm` is still very early, buggy, and lacking features. -For a rundown of supported types, check out [rbx-dom's type coverage chart](https://github.com/LPGhatguy/rbx-dom#property-type-coverage). \ No newline at end of file +For a rundown of supported types, check out [rbx-dom's type coverage chart](https://github.com/rojo-rbx/rbx-dom#property-type-coverage). + +## Meta Files +New in Rojo 0.5.0-alpha.12 are meta files, named `.meta.json`. + +Meta files allow attaching extra Rojo data to models defined in other formats, like Roblox's `rbxm` and `rbxmx` model formats, or even Lua scripts. + +This can be used to set Rojo-specific settings like `ignoreUnknownInstances`, or can be used to set properties like `Disabled` on a script. + +Meta files can contain: + +* `className`: Changes the `className` of a containing `Folder` into something else. + * Usable only in `init.meta.json` files +* `properties`: A map of properties to set on the instance, just like projects + * Usable on anything except `.rbxmx`, `.rbxm`, and `.model.json` files, which already have properties +* `ignoreUnknownInstances`: Works just like `$ignoreUnknownInstances` in project files + +### Meta Files to set Rojo metadata +Sometimes it's useful to apply properties like `ignoreUnknownInstances` on instances that are defined on the filesystem instead of within the project itself. + +### Meta Files for Disabled Scripts +Meta files can be used to set properties on `Script` instances, like `Disabled`. + +If your project had `foo.server.lua` and you wanted to make sure it would be disabled, you could create a `foo.meta.json` next to it with: + +```json +{ + "properties": { + "Disabled": true + } +} +``` + +### Meta Files for Tools +If you wanted to represent a tool containing a script and a model for its handle, create a directory with an `init.meta.json` file in it: + +```json +{ + "className": "Tool", + "properties": { + "Grip": [ + 0, 0, 0, + 1, 0, 0, + 0, 1, 0, + 0, 0, 1, + ] + } +} +``` + +Instead of a `Folder` instance, you'll end up with a `Tool` instance with the `Grip` property set! \ No newline at end of file