mirror of
https://github.com/rojo-rbx/rojo.git
synced 2026-04-20 20:55:50 +00:00
Substantial documentation improvements
This commit is contained in:
Lucien Greathouse
145
docs/reference/project-format.md
Normal file
145
docs/reference/project-format.md
Normal file
@@ -0,0 +1,145 @@
|
||||
[TOC]
|
||||
|
||||
## Project File
|
||||
|
||||
Rojo projects are JSON files that have the `.project.json` extension. They have these fields:
|
||||
|
||||
* `name`: A string indicating the name of the project.
|
||||
* This is only used for diagnostics.
|
||||
* `tree`: An [Instance Description](#instance-description) describing the root instance of the project.
|
||||
|
||||
## Instance Description
|
||||
Instance Descriptions correspond one-to-one with the actual Roblox Instances in the project. They can be specified directly in the project file or be pulled from the filesystem.
|
||||
|
||||
* `$className`: The ClassName of the Instance being described.
|
||||
* Optional if `$path` is specified.
|
||||
* `$path`: The path on the filesystem to pull files from into the project.
|
||||
* Optional if `$className` is specified.
|
||||
* Paths are relative to the folder containing the project file.
|
||||
* `$properties`: Properties to apply to the instance. Values should be [Instance Property Values](#instance-property-value).
|
||||
* Optional
|
||||
* `$ignoreUnknownInstances`: Whether instances that Rojo doesn't know about should be deleted.
|
||||
* Optional
|
||||
* Default is `false` if `$path` is specified, otherwise `true`.
|
||||
|
||||
All other fields in an Instance Description are turned into instances whose name is the key. These values should also be Instance Descriptions!
|
||||
|
||||
Instance Descriptions are fairly verbose and strict. In the future, it'll be possible for Rojo to [infer class names for known services like `Workspace`](https://github.com/LPGhatguy/rojo/issues/179).
|
||||
|
||||
## Instance Property Value
|
||||
There are two kinds of property values on instances, **implicit** and **explicit**.
|
||||
|
||||
In the vast majority of cases, you should be able to use **implicit** property values. To use them, just use a value that's the same shape as the type that the property has:
|
||||
|
||||
```json
|
||||
"MyPart": {
|
||||
"$className": "Part",
|
||||
"$properties": {
|
||||
"Size": [3, 5, 3],
|
||||
"Color": [0.5, 0, 0.5],
|
||||
"Anchored": true,
|
||||
"Material": "Granite"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`Vector3` and `Color3` properties can just be arrays of numbers, as can types like `Vector2`, `CFrame`, and more!
|
||||
|
||||
Enums can be set to a string containing the enum variant. Rojo will raise an error if the string isn't a valid variant for the enum.
|
||||
|
||||
There are some cases where this syntax for assigning properties _doesn't_ work. In these cases, Rojo requires you to use the **explicit** property syntax.
|
||||
|
||||
Some reasons why you might need to use an **explicit** property:
|
||||
|
||||
* Using exotic property types like `BinaryString`
|
||||
* Using properties added to Roblox recently that Rojo doesn't know about yet
|
||||
|
||||
The shape of explicit property values is defined by the [rbx-dom](https://github.com/LPGhatguy/rbx-dom) library, so it uses slightly different conventions than the rest of Rojo.
|
||||
|
||||
Each value should be an object with the following required fields:
|
||||
|
||||
* `Type`: The type of property to represent.
|
||||
* [Supported types can be found here](https://github.com/LPGhatguy/rbx-tree#property-type-coverage).
|
||||
* `Value`: The value of the property.
|
||||
* The shape of this field depends on which property type is being used. `Vector3` and `Color3` values are both represented as a list of numbers, while `BinaryString` expects a base64-encoded string, for example.
|
||||
|
||||
Here's the same object, but with explicit properties:
|
||||
|
||||
```json
|
||||
"MyPart": {
|
||||
"$className": "Part",
|
||||
"$properties": {
|
||||
"Size": {
|
||||
"Type": "Vector3",
|
||||
"Value": [3, 5, 3]
|
||||
},
|
||||
"Color": {
|
||||
"Type": "Color3",
|
||||
"Value": [0.5, 0, 0.5]
|
||||
},
|
||||
"Anchored": {
|
||||
"Type": "Bool",
|
||||
"Value": true
|
||||
},
|
||||
"Material": {
|
||||
"Type": "Enum",
|
||||
"Value": 832
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Example Projects
|
||||
This project bundles up everything in the `src` directory. It'd be suitable for making a plugin or model:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "AwesomeLibrary",
|
||||
"tree": {
|
||||
"$path": "src"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This project describes the layout you might use if you were making the next hit simulator game, *Sisyphus Simulator*:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Sisyphus Simulator",
|
||||
"tree": {
|
||||
"$className": "DataModel",
|
||||
|
||||
"HttpService": {
|
||||
"$className": "HttpService",
|
||||
"$properties": {
|
||||
"HttpEnabled": true
|
||||
}
|
||||
},
|
||||
|
||||
"ReplicatedStorage": {
|
||||
"$className": "ReplicatedStorage",
|
||||
"$path": "src/ReplicatedStorage"
|
||||
},
|
||||
|
||||
"StarterPlayer": {
|
||||
"$className": "StarterPlayer",
|
||||
|
||||
"StarterPlayerScripts": {
|
||||
"$className": "StarterPlayerScripts",
|
||||
"$path": "src/StarterPlayerScripts"
|
||||
}
|
||||
},
|
||||
|
||||
"Workspace": {
|
||||
"$className": "Workspace",
|
||||
"$properties": {
|
||||
"Gravity": 67.3
|
||||
},
|
||||
|
||||
"Terrain": {
|
||||
"$path": "Terrain.rbxm"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
91
docs/reference/sync-details.md
Normal file
91
docs/reference/sync-details.md
Normal file
@@ -0,0 +1,91 @@
|
||||
This page aims to describe how Rojo turns files on the filesystem into Roblox objects.
|
||||
|
||||
[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 |
|
||||
|
||||
## 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 chart](https://github.com/LPGhatguy/rbx-tree#property-type-coverage).
|
||||
|
||||
## Folders
|
||||
Any directory on the filesystem will turn into a `Folder` instance unless it contains an 'init' script, described below.
|
||||
|
||||
## Scripts
|
||||
The default script type in Rojo projects is `ModuleScript`, since most scripts in well-structued Roblox projects will be modules.
|
||||
|
||||
If a directory contains a file named `init.server.lua`, `init.client.lua`, or `init.lua`, that folder will be transformed into a `*Script` instance with the contents of the 'init' file. This can be used to create scripts inside of scripts.
|
||||
|
||||
For example, these files:
|
||||
|
||||
|
||||
{: align="center" }
|
||||
|
||||
Will turn into these instances in Roblox:
|
||||
|
||||
|
||||
{: align="center" }
|
||||
|
||||
## 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.
|
||||
|
||||
## 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:
|
||||
|
||||
|
||||
{: align="center" }
|
||||
|
||||
## Binary and XML Models
|
||||
Rojo supports both binary (`.rbxm`) and XML (`.rbxmx`) models generated by Roblox Studio or another tool.
|
||||
|
||||
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).
|
||||
Reference in New Issue
Block a user