ari-party/rojo
1
0
Fork 0
forked from rojo-rbx/rojo
Code Pull Requests Activity

New docs

Browse Source
This commit is contained in:
Lucien Greathouse
2019-02-08 18:03:46 -08:00
parent 5e4c1a8359
commit d5f3e25bea
4 changed files with 139 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/images/plugins-folder-in-studio.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 19 KiB

46
docs/installation.md
View File

@@ -1,25 +1,45 @@
[TOC]
## Overview
Rojo has two components:
* The server, a binary written in Rust
* The plugin, a Roblox Studio plugin written in Lua
* The command line interface (CLI)
* The Roblox Studio plugin
It's important that the plugin and server are compatible. The plugin will show errors in the Roblox Studio Output window if there is a version mismatch.
!!! info
It's important that your installed version of the plugin and CLI are compatible.
## Installing the Server
To install the server, either:
The plugin will show errors in the Roblox Studio output window if there is a version mismatch.
* If you have Rust installed, use `cargo install rojo`
* Or, download a pre-built Windows binary from [the GitHub releases page](https://github.com/LPGhatguy/rojo/releases)
## Installing the CLI
**The Rojo binary must be run from the command line, like Terminal on MacOS or `cmd.exe` on Windows. It's recommended that you put the Rojo binary on your `PATH` to make this easier.**
### Installing from GitHub
If you're on Windows, there are pre-built binaries available from Rojo's [GitHub Releases page](https://github.com/LPGhatguy/rojo/releases).
The Rojo CLI must be run from the command line, like Terminal.app on MacOS or `cmd.exe` on Windows. It's recommended that you put the Rojo CLI executable on your `PATH` to make this easier.
### Installing from Cargo
If you have Rust installed, the easiest way to get Rojo is with Cargo!
To install the latest 0.5.0 alpha, use:
```sh
cargo install rojo --version 0.5.0-alpha.3
```
## Installing the Plugin
To install the plugin, either:
* Install the plugin from the [Roblox plugin page](https://www.roblox.com/library/1211549683/Rojo).
* This gives you less control over what version you install -- you will always have the latest version.
* Or, download the latest release from [the GitHub releases section](https://github.com/LPGhatguy/rojo/releases) and install it into your Roblox plugins folder
* You can open this folder by clicking the "Plugins Folder" button from the Plugins toolbar in Roblox Studio
### Installing from GitHub
The Rojo Roblox Studio plugin is available available from Rojo's [GitHub Releases page](https://github.com/LPGhatguy/rojo/releases).
Download the attached `rbxm` file and put it into your Roblox Studio plugins folder. You can find that folder by pressing **Plugins Folder** from your Plugins toolbar in Roblox Studio:
!['Plugins Folder' button in Roblox Studio](images/plugins-folder-in-studio.png)
{: 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 on Windows, 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 add partitions and start/stop the Rojo server!

101
docs/project-format.md
View File

@@ -1 +1,100 @@
WIP
[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`.
## Instance Property Value
The shape of Instance Property Values is defined by the [rbx_tree](https://github.com/LPGhatguy/rbx-tree) 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, for example.
Instance Property Values are intentionally very strict. Rojo will eventually be able to infer types for you!
## 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": {
"Type": "Bool",
"Value": true
}
}
},
"ReplicatedStorage": {
"$className": "ReplicatedStorage",
"$path": "src/ReplicatedStorage"
},
"StarterPlayer": {
"$className": "StarterPlayer",
"StarterPlayerScripts": {
"$className": "StarterPlayerScripts",
"$path": "src/StarterPlayerScripts"
}
},
"Workspace": {
"$className": "Workspace",
"$properties": {
"Gravity": {
"Type": "Float32",
"Value": 67.3
}
},
"Terrain": {
"$path": "Terrain.rbxm"
}
}
}
}
```

21
docs/sync-details.md
View File

@@ -36,19 +36,13 @@ If a directory contains a file named `init.server.lua`, `init.client.lua`, or `i
For example, these files:
<div align="center">
<a href="../images/sync-example-files.svg">
<img src="../images/sync-example-files.svg" alt="Tree of files on disk" />
</a>
</div>
![Tree of files on disk](images/sync-example-files.svg)
{: align="center" }
Will turn into these instances in Roblox:
<div align="center">
<a href="../images/sync-example-instances.svg">
<img src="../images/sync-example-instances.svg" alt="Tree of instances in Roblox" />
</a>
</div>
![Tree of instances in Roblox](images/sync-example-instances.svg)
{: 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.
@@ -86,11 +80,8 @@ A JSON model describing a folder containing a `Part` and a `RemoteEvent` could b
It would turn into instances in this shape:
<div align="center">
<a href="../images/sync-example-json-model.svg">
<img src="../images/sync-example-json-model.svg" alt="Tree of instances in Roblox" />
</a>
</div>
![Tree of instances in Roblox](images/sync-example-json-model.svg)
{: align="center" }
## Binary and XML Models
Rojo supports both binary (`.rbxm`) and XML (`.rbxmx`) models generated by Roblox Studio or another tool.