diff --git a/docs/extra.css b/docs/extra.css new file mode 100644 index 00000000..020a7103 --- /dev/null +++ b/docs/extra.css @@ -0,0 +1,3 @@ +.md-typeset__table { + width: 100%; +} \ No newline at end of file diff --git a/docs/images/connection-error.png b/docs/images/connection-error.png deleted file mode 100644 index af3c16fa..00000000 Binary files a/docs/images/connection-error.png and /dev/null differ diff --git a/docs/images/plugin-buttons.png b/docs/images/plugin-buttons.png deleted file mode 100644 index 58739930..00000000 Binary files a/docs/images/plugin-buttons.png and /dev/null differ diff --git a/docs/images/sync-example-files.gv b/docs/images/sync-example-files.gv new file mode 100644 index 00000000..1b1ac78c --- /dev/null +++ b/docs/images/sync-example-files.gv @@ -0,0 +1,17 @@ +digraph "Sync Files" { + graph [ + ranksep = "0.7", + nodesep = "0.5", + ]; + node [ + fontname = "monospace", + shape = "record", + ]; + + my_model [label = "MyModel"] + init_server [label = "init.server.lua"] + foo [label = "foo.lua"] + + my_model -> init_server + my_model -> foo +} \ No newline at end of file diff --git a/docs/images/sync-example-files.svg b/docs/images/sync-example-files.svg new file mode 100644 index 00000000..64de9f10 --- /dev/null +++ b/docs/images/sync-example-files.svg @@ -0,0 +1,38 @@ + + + + + + +Sync Files + + +my_model + +MyModel + + +init_server + +init.server.lua + + +my_model->init_server + + + + +foo + +foo.lua + + +my_model->foo + + + + + diff --git a/docs/images/sync-example-instances.gv b/docs/images/sync-example-instances.gv new file mode 100644 index 00000000..4902a8b1 --- /dev/null +++ b/docs/images/sync-example-instances.gv @@ -0,0 +1,15 @@ +digraph "Sync Files" { + graph [ + ranksep = "0.7", + nodesep = "0.5", + ]; + node [ + fontname = "monospace", + shape = "record", + ]; + + my_model [label = "MyModel (Script)"] + foo [label = "foo (ModuleScript)"] + + my_model -> foo +} \ No newline at end of file diff --git a/docs/images/sync-example-instances.svg b/docs/images/sync-example-instances.svg new file mode 100644 index 00000000..24f4a52d --- /dev/null +++ b/docs/images/sync-example-instances.svg @@ -0,0 +1,28 @@ + + + + + + +Sync Files + + +my_model + +MyModel (Script) + + +foo + +foo (ModuleScript) + + +my_model->foo + + + + + diff --git a/docs/images/sync-example-json-model.gv b/docs/images/sync-example-json-model.gv new file mode 100644 index 00000000..376108d3 --- /dev/null +++ b/docs/images/sync-example-json-model.gv @@ -0,0 +1,17 @@ +digraph "Sync Files" { + graph [ + ranksep = "0.7", + nodesep = "0.5", + ]; + node [ + fontname = "monospace", + shape = "record", + ]; + + model [label = "My Cool Model (Folder)"] + root_part [label = "RootPart (Part)"] + send_money [label = "SendMoney (RemoteEvent)"] + + model -> root_part + model -> send_money +} \ No newline at end of file diff --git a/docs/images/sync-example-json-model.svg b/docs/images/sync-example-json-model.svg new file mode 100644 index 00000000..27dd3251 --- /dev/null +++ b/docs/images/sync-example-json-model.svg @@ -0,0 +1,38 @@ + + + + + + +Sync Files + + +model + +My Cool Model (Folder) + + +root_part + +RootPart (Part) + + +model->root_part + + + + +send_money + +SendMoney (RemoteEvent) + + +model->send_money + + + + + diff --git a/docs/images/sync-example.png b/docs/images/sync-example.png deleted file mode 100644 index ab56863b..00000000 Binary files a/docs/images/sync-example.png and /dev/null differ diff --git a/docs/migrating-to-epiphany.md b/docs/migrating-to-epiphany.md index 98fca7b8..fbd48481 100644 --- a/docs/migrating-to-epiphany.md +++ b/docs/migrating-to-epiphany.md @@ -50,9 +50,6 @@ Metadata begins with a dollar sign (`$`), like `$className`. This is so that chi All other values are considered children, where the key is the instance's name, and the value is an object, repeating the process. -## Migrating `.model.json` Files -No upgrade path yet, stay tuned. - ## 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. diff --git a/docs/sync-details.md b/docs/sync-details.md index 55a1e543..b655bb13 100644 --- a/docs/sync-details.md +++ b/docs/sync-details.md @@ -9,6 +9,20 @@ This page aims to describe how Rojo turns files on the filesystem into Roblox ob | `*.lua` | `ModuleScript` | | `*.csv` | `LocalizationTable` | | `*.txt` | `StringValue` | +| `*.model.json` | Any | +| `*.rbxm` | Any | +| `*.rbxmx` | Any | + +## 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. + +Some common cases you might hit are: + +* Binary data (Terrain, CSG, CollectionService tags) +* `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 documentation](https://github.com/LPGhatguy/rbx-tree/tree/master/rbx_tree#coverage). ## Folders Any directory on the filesystem will turn into a `Folder` instance unless it contains an 'init' script, described below. @@ -20,16 +34,68 @@ If a directory contains a file named `init.server.lua`, `init.client.lua`, or `i For example, these files: -* my-game - * init.client.lua - * foo.lua +
+ + Tree of files on disk + +
Will turn into these instances in Roblox: -![Example of Roblox instances](/images/sync-example.png) +
+ + Tree of instances in Roblox + +
## Localization Tables Any CSV files are transformed into `LocalizationTable` instances. Rojo expects these files to follow the same format that Roblox does when importing and exporting localization information. ## Plain Text Files -Plain text files (`.txt`) files are transformed into `StringValue` instances. This is useful for bringing in text data that can be read by scripts at runtime. \ No newline at end of file +Plain text files (`.txt`) files are transformed into `StringValue` instances. This is useful for bringing in text data that can be read by scripts at runtime. + +## JSON Models +Files ending in `.model.json` can be used to describe simple models. They're designed to be hand-written and are useful for instances like `RemoteEvent`. + +A JSON model describing a folder containing a `Part` and a `RemoteEvent` could be described as: + +```json +{ + "Name": "My Cool Model", + "ClassName": "Folder", + "Children": [ + { + "Name": "RootPart", + "ClassName": "Part", + "Properties": { + "Size": { + "Type": "Vector3", + "Value": [4, 4, 4] + } + } + }, + { + "Name": "SendMoney", + "ClassName": "RemoteEvent" + } + ] +} +``` + +It would turn into instances in this shape: + +
+ + Tree of instances in Roblox + +
+ +## Binary and XML Models +Rojo supports both binary (`.rbxm`) and XML (`.rbxmx`) models generated by Roblox Studio or another tool. + +Not all property types are supported! + +For a rundown of supported types, see: + +* [rbxm Type Coverage](https://github.com/LPGhatguy/rbx-tree/tree/master/rbx_binary#coverage) +* [rbxmx Type Coverage](https://github.com/LPGhatguy/rbx-tree/tree/master/rbx_xml#coverage) \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index a45c478e..e07ab8bc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -17,6 +17,9 @@ nav: - Sync Details: sync-details.md - Migrating from 0.4.x to 0.5.x: migrating-to-epiphany.md +extra_css: + - extra.css + markdown_extensions: - attr_list - admonition