mirror of
https://github.com/rojo-rbx/rojo.git
synced 2026-04-20 12:45:05 +00:00
Update documentation to include meta docs
This commit is contained in:
Lucien Greathouse
@@ -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
|
||||
|
||||
@@ -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!
|
||||
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**.
|
||||
@@ -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.
|
||||
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.
|
||||
@@ -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!
|
||||
Reference in New Issue
Block a user