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

Substantial documentation improvements

Browse Source
This commit is contained in:
Lucien Greathouse
2019-06-07 18:29:09 -07:00
parent 0ed6c57c7f
commit 2a4ca21050
12 changed files with 221 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
docs/creating-a-place.md
View File

@@ -1,68 +0,0 @@
[TOC]
## Creating the Rojo Project
To use Rojo to build a place, you'll need to create a new project file, which tells Rojo how your project is structured on-disk and in Roblox.
Create a new folder, then run `rojo init` inside that folder to initialize an empty project.
```sh
mkdir my-new-project
cd my-new-project
rojo init
```
Rojo will make a small project file in your directory, named `default.project.json`. It'll make sure that any code in the directory `src` will get put into `ReplicatedStorage.Source`.
Speaking of, let's make sure we create a directory named `src`, and maybe a Lua file inside of it:
```sh
mkdir src
echo 'print("Hello, world!")' > src/hello.lua
```
## Building Your Place
Now that we have a project, one thing we can do is build a Roblox place file for our project. This is a great way to get started with a project quickly with no fuss.
All we have to do is call `rojo build`:
```sh
rojo build -o MyNewProject.rbxlx
```
If you open `MyNewProject.rbxlx` in Roblox Studio now, you should see a `Folder` containing a `ModuleScript` under `ReplicatedStorage`!
!!! info
To generate a binary place file instead, use `rbxl`. Note that support for binary model/place files (`rbxm` and `rbxl`) is very limited in Rojo presently.
## Live-Syncing into Studio
Building a place file is great for the initial build, but for actively working on your place, you'll want something quicker.
In Roblox Studio, make sure the Rojo plugin is installed. If you need it, check out [the installation guide](installation) to learn how to install it.
To expose your project to the plugin, you'll need to _serve_ it from the command line:
```sh
rojo serve
```
This will start up a web server that tells Roblox Studio what instances are in your project and sends notifications if any of them change.
Note the port number, then switch into Roblox Studio and press the Rojo **Connect** button in the plugins tab. Type in the port number, if necessary, and press **Start**.
If everything went well, you should now be able to change files in the `src` directory and watch them sync into Roblox Studio in real time!
## Uploading Your Place
Aimed at teams that want serious levels of automation, Rojo can upload places to Roblox.com automatically.
You'll need an existing place on Roblox.com as well as the `.ROBLOSECURITY` cookie of an account that has write access to that place.
!!! warning
It's recommended that you set up a Roblox account dedicated to deploying your place instead of your personal account in case your security cookie is compromised.
Generating and uploading your place file is as simple as:
```sh
rojo upload --asset_id [PLACE ID] --cookie "[SECURITY COOKIE]"
```

10
docs/extra.css
View File

@@ -1,3 +1,13 @@
.md-typeset__table {
width: 100%;
}
.feature-image img {
border: 1px solid rgba(0, 0, 0, 0.2);
box-shadow: 1px 1px 4px rgba(0, 0, 0, 0.2);
}
.codehilite {
border: 1px solid rgba(0, 0, 0, 0.2);
box-shadow: 1px 1px 4px rgba(0, 0, 0, 0.2);
}

0
docs/guide/existing-game.md Normal file
View File

5
docs/installation.md → docs/guide/installation.md
View File

@@ -1,7 +1,8 @@
This is this installation guide for Rojo **0.5.x**.
[TOC]
## Overview
Rojo has two components:
* The command line interface (CLI)
@@ -35,7 +36,7 @@ The Rojo Roblox Studio plugin is available from Rojo's [GitHub Releases page](ht
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)
!['Plugins Folder' button in Roblox Studio](../images/plugins-folder-in-studio.png)
{: align="center" }
### Installing from Roblox.com

0
docs/migrating-to-epiphany.md → docs/guide/migrating-to-epiphany.md
View File

90
docs/guide/new-game.md Normal file
View File

@@ -0,0 +1,90 @@
[TOC]
## Creating the Rojo Project
To use Rojo to build a game, you'll need to create a new project file, which tells Rojo how to turn your files into a Roblox place.
First, create a new folder to contain the files for your game and open up a new terminal inside of it, like cmd.exe or Bash.
It's convenient to make the folder from the command line:
```sh
mkdir my-new-project
cd my-new-project
```
Inside the folder, initialize a new Rojo project:
```sh
rojo init
```
Rojo will make a small project file in your directory, named `default.project.json`. It matches the "Baseplate" template from Roblox Studio, except that it'll take any files you put in a folder called `src` and put it into `ReplicatedStorage.Source`.
Speaking of files, make sure to create a directory named `src` in this folder, or Rojo will be upset about missing files!
```sh
mkdir src
```
Let's also add a Lua file, `hello.lua` to the `src` folder, so that we can make this project our own.
```sh
echo 'return "Hello, Rojo!"' > src/hello.lua
```
## Building Your Place
Now that we have a project, one thing we can do is build a Roblox place file for our project. This is a great way to get started with a project quickly with no fuss.
All we have to do is call `rojo build`:
```sh
rojo build -o MyNewProject.rbxlx
```
If you open `MyNewProject.rbxlx` in Roblox Studio now, you should see a `Folder` containing a `ModuleScript` under `ReplicatedStorage`!
!!! info
To generate a binary place file instead, use `rbxl`. Note that support for binary model/place files (`rbxm` and `rbxl`) is very limited in Rojo presently.
## Live-Syncing into Studio
Building a place file is great for starting to work on a game, but for active iteration, you'll want something faster.
In Roblox Studio, make sure the Rojo plugin is installed. If you need it, check out [the installation guide](installation) to learn how to install it.
To expose your project to the plugin, you'll need to start a new **live sync session** from the command line:
```sh
rojo serve
```
You should see output like this in your terminal:
```sh
$ rojo serve
Rojo server listening on port 34872
```
Switch into Roblox Studio and press the **Connect** button on the Rojo plugin toolbar. A dialog should appear:
![Rojo plugin connection dialog](../images/connection-dialog.png)
{: class="feature-image" align="center" }
If the port number doesn't match the output from the command line, change it, and then press **Connect**.
If all went well, you should now be able to change files in the `src` directory and watch them sync into Roblox Studio in real time!
## Uploading Your Place
Aimed at teams that want serious levels of automation, Rojo can upload places to Roblox.com automatically.
You'll need an existing game on Roblox.com as well as the `.ROBLOSECURITY` cookie of an account that has write access to that game.
!!! warning
It's recommended that you set up a Roblox account dedicated to deploying your game instead of your personal account in case your security cookie is compromised.
Generating and publishing your game is as simple as:
```sh
rojo upload --asset_id [PLACE ID] --cookie "[SECURITY COOKIE]"
```
An example project is available on GitHub that deploys to Roblox.com from GitHub and Travis-CI automatically: [https://github.com/LPGhatguy/roads](https://github.com/LPGhatguy/roads)

BIN
docs/images/connection-dialog.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

69
docs/project-format.md → docs/reference/project-format.md
View File

@@ -24,19 +24,70 @@ Instance Descriptions correspond one-to-one with the actual Roblox Instances in
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 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
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.
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, for example.
* 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.
Instance Property Values are intentionally very strict. Rojo will eventually be able to infer types for you!
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:
@@ -61,10 +112,7 @@ This project describes the layout you might use if you were making the next hit
"HttpService": {
"$className": "HttpService",
"$properties": {
"HttpEnabled": {
"Type": "Bool",
"Value": true
}
"HttpEnabled": true
}
},
@@ -85,10 +133,7 @@ This project describes the layout you might use if you were making the next hit
"Workspace": {
"$className": "Workspace",
"$properties": {
"Gravity": {
"Type": "Float32",
"Value": 67.3
}
"Gravity": 67.3
},
"Terrain": {

6
docs/sync-details.md → docs/reference/sync-details.md
View File

@@ -36,12 +36,12 @@ If a directory contains a file named `init.server.lua`, `init.client.lua`, or `i
For example, these files:
![Tree of files on disk](images/sync-example-files.svg)
![Tree of files on disk](../images/sync-example-files.svg)
{: align="center" }
Will turn into these instances in Roblox:
![Tree of instances in Roblox](images/sync-example-instances.svg)
![Tree of instances in Roblox](../images/sync-example-instances.svg)
{: align="center" }
## Localization Tables
@@ -80,7 +80,7 @@ A JSON model describing a folder containing a `Part` and a `RemoteEvent` could b
It would turn into instances in this shape:
![Tree of instances in Roblox](images/sync-example-json-model.svg)
![Tree of instances in Roblox](../images/sync-example-json-model.svg)
{: align="center" }
## Binary and XML Models

23
docs/rojo-alternatives.md Normal file
View File

@@ -0,0 +1,23 @@
There are a number of existing plugins for Roblox that move code from the filesystem into Roblox.
Besides Rojo, you might consider:
* [rbxmk by Anaminus](https://github.com/anaminus/rbxmk)
* [Rofresh by Osyris](https://github.com/osyrisrblx/rofresh)
* [RbxRefresh by Osyris](https://github.com/osyrisrblx/RbxRefresh)
* [Studio Bridge by Vocksel](https://github.com/vocksel/studio-bridge)
* [Elixir by Vocksel](https://github.com/vocksel/elixir)
* [RbxSync by evaera](https://github.com/evaera/RbxSync)
* [CodeSync by MemoryPenguin](https://github.com/MemoryPenguin/CodeSync)
* [rbx-exteditor by MemoryPenguin](https://github.com/MemoryPenguin/rbx-exteditor)
So why did I build Rojo?
Each of these tools solves what is essentially the same problem from a few different angles. The goal of Rojo is to take all of the lessons and ideas learned from these projects and build a tool that can solve this problem for good.
Additionally:
* I think that this tool needs to be built in a compiled language without a runtime, for easy distribution and good performance.
* I think that the conventions promoted by other sync plugins (`.module.lua` for modules, as well a single sync point) are sub-optimal.
* I think that I have a good enough understanding of the problem to build something robust.
* I think that Rojo should be able to do more than just sync code.

43
docs/why-rojo.md
View File

@@ -1,23 +1,32 @@
There are a number of existing plugins for Roblox that move code from the filesystem into Roblox.
Adding a tool like Rojo to your Roblox workflow can be daunting, but it comes with some key advantages.
Besides Rojo, you might consider:
[TOC]
* [rbxmk by Anaminus](https://github.com/anaminus/rbxmk)
* [Rofresh by Osyris](https://github.com/osyrisrblx/rofresh)
* [RbxRefresh by Osyris](https://github.com/osyrisrblx/RbxRefresh)
* [Studio Bridge by Vocksel](https://github.com/vocksel/studio-bridge)
* [Elixir by Vocksel](https://github.com/vocksel/elixir)
* [RbxSync by evaera](https://github.com/evaera/RbxSync)
* [CodeSync by MemoryPenguin](https://github.com/MemoryPenguin/CodeSync)
* [rbx-exteditor by MemoryPenguin](https://github.com/MemoryPenguin/rbx-exteditor)
## External Text Editors
Rojo opens the door to use the absolute best text editors in the world and their rich plugin ecosystem.
So why did I build Rojo?
Some very popular, free editors include [Visual Studio Code](https://code.visualstudio.com) and [Sublime Text](https://www.sublimetext.com).
Each of these tools solves what is essentially the same problem from a few different angles. The goal of Rojo is to take all of the lessons and ideas learned from these projects and build a tool that can solve this problem for good.
These advanced text editors have features like multi-cursor editing, goto symbol, multi-file regex find and replace, bookmarks and much more.
Additionally:
Many Rojo VS Code users also use extensions like:
* I think that this tool needs to be built in a compiled language without a runtime, for easy distribution and good performance.
* I think that the conventions promoted by other sync plugins (`.module.lua` for modules, as well a single sync point) are sub-optimal.
* I think that I have a good enough understanding of the problem to build something robust.
* I think that Rojo should be able to do more than just sync code.
* [vscode-rbxlua](https://marketplace.visualstudio.com/items?itemName=AmaranthineCodices.vscode-rbxlua)
* [Roblox Lua Autocompletes](https://marketplace.visualstudio.com/items?itemName=Kampfkarren.roblox-lua-autofills)
* [TabNine](https://tabnine.com)
## Version Control
By building your game (or just the scripts) as individual files on the filesystem, it becomes easy to start using professional-grade version control tools like [Git](https://git-scm.com) and [GitHub](https://github.com).
Hundreds of thousands of companies and individual developers use Git to version their software projects. With Rojo, Roblox developers can take advantage of the best collaboration tool around.
Using a repository hosting service like GitHub or GitLab brings powerful features to Roblox developers like code reviews and issue tracking that professional engineers can't live without.
## Other Tools
There are decades of excellent tools available that operate on files. With Rojo, it's possible to take advantage of any of them!
Popular tools include:
* [luacheck](https://github.com/mpeterv/luacheck), a static analysis tool to help you write better Lua
* [ripgrep](https://github.com/BurntSushi/ripgrep), an extremely fast code search tool
* [Tokei](https://github.com/XAMPPRocky/tokei), a tool for statistics like lines of code