rojo 0.4.0

Rojo is a flexible multi-tool designed for creating robust Roblox projects. It's in early development, but is still useful for many projects.

It's designed for power users who want to use the best tools available for building games, libraries, and plugins.

This is the main Rojo repository, containing the binary and project server component. For the source for the Roblox plugin, see the rojo-plugin repository.

The master branches of both respositories should always pass all tests and be functional, but are not suitable for production use!

Features

Rojo has a number of desirable features right now:

• Work on scripts from the filesystem, in your favorite editor
• Version your place, library, or plugin using Git or another VCS
• Sync JSON-format models from the filesystem into your game

Later this year, Rojo will be able to:

• Sync rbxmx-format Roblox models bi-directionally between the filesystem and Roblox Studio
• Create installation scripts for libraries to be used in standalone places
  • Similar to rbxpacker, another one of my projects
• Add strongly-versioned dependencies to your project

Installation

Rojo has two components:

• The command line tool, written in Rust
• The Roblox Studio plugin, written in Lua

To install the command line tool, there are two options:

• Cargo, if you have Rust installed
  • Use cargo install rojo -- Rojo will be available with the rojo command
• Download a pre-built Windows binary from the GitHub releases page

Usage

For more help, use rojo help.

New Project

Just create a new folder and tell Rojo to initialize it!

mkdir my-new-project
cd my-new-project

rojo init

Rojo will create an empty project in the directory.

The default project looks like this:

{
  "name": "my-new-project",
  "servePort": 8000,
  "partitions": {}
}

Start Dev Server

To create a server that allows the Rojo Dev Plugin to access your project, use:

rojo serve

The tool will tell you whether it found an existing project. You should then be able to connect and use the project from within Roblox Studio!

Migrating an Existing Roblox Project

Coming soon!

Syncing into Roblox

In order to sync code into Roblox, you'll need to add one or more "partitions" to your configuration. A partition tells Rojo how to map directories to Roblox objects.

Each entry in the partitions table has a unique name, a filesystem path, and the full name of the Roblox object to sync into.

For example, if you want to map your src directory to an object named My Cool Game in ReplicatedStorage, you could use this configuration:

{
  "name": "rojo",
  "servePort": 8000,
  "partitions": {
    "game": {
      "path": "src",
      "target": "ReplicatedStorage.My Cool Game"
    }
  }
}

The path parameter is relative to the project file.

The target parameter is a path to a Roblox object to link the partition to. It starts at game and crawls down the tree. If any objects don't exist along the way, they'll be created as Folder instances.

Run rojo serve in the directory containing this project, then press the "Sync In" or "Toggle Polling" buttons in the Roblox Studio plugin to move code into your game.

Sync Details

The structure of files and folders on the filesystem are preserved when syncing into game.

Creation of Roblox instances follows a simple set of rules. The first rule that matches the file name is chosen:

Any folders on the filesystem will turn into Folder objects unless they contain a file named init.lua, init.server.lua, or init.client.lua. Following the convention of Lua, those objects will instead be whatever the init file would turn into.

For example, this file tree:

• my-game
  • init.client.lua
  • foo.lua

Will turn into this tree in Roblox:

• my-game (LocalScript with source from my-game/init.client.lua)
  • foo (ModuleScript with source from my-game/foo.lua)

Inspiration

There are lots of other tools that sync scripts into Roblox, or otherwise work to improve the development flow outside of Roblox Studio.

Here are a few, if you're looking for alternatives or supplements to Rojo:

• Studio Bridge by Vocksel
• RbxRefresh by Osyris
• RbxSync by evaera
• CodeSync and rbx-exteditor by MemoryPenguin
• rbxmk by Anaminus

I also have a couple tools that Rojo intends to replace:

• rbxfs, which has been deprecated by Rojo
• rbxpacker, which is still useful

Contributing

Pull requests are welcome!

The master branch of both repositories have tests running on Travis for every commit and pull request. The test suite on master should always pass!

The Rojo and Rojo Plugin repositories should stay in sync with eachother, so that the current master of each repository can be used together.

License

Rojo is available under the terms of the MIT license. See LICENSE.md for details.