rojo-rbx/rojo
1
0
Fork 1
mirror of https://github.com/rojo-rbx/rojo.git synced 2026-04-20 20:55:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation to include meta docs

Browse Source
This commit is contained in:
Lucien Greathouse
2019-07-02 15:30:56 -07:00
parent e045989d39
commit aa3e43207f
4 changed files with 80 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
docs/reference/sync-details.md
View File

@@ -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).
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!