From 9cee587f22fab738122d63cfedff4b31c4daa353 Mon Sep 17 00:00:00 2001 From: Lucien Greathouse Date: Sun, 8 Apr 2018 00:16:21 -0700 Subject: [PATCH] Remove documentation from README and point to snazzy new documentation website --- README.md | 156 ++---------------------------------------------------- 1 file changed, 5 insertions(+), 151 deletions(-) diff --git a/README.md b/README.md index 79ee70c4..767399d6 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,9 @@ Travis-CI Build Status Current server version + + Rojo Documentation +
@@ -29,157 +32,8 @@ Later this year, Rojo will be able to: * Sync `rbxmx` models between the filesystem and Roblox Studio * Package projects into `rbxmx` files from the command line -## Installation -Rojo has two components: - -* The server, a binary written in Rust -* The plugin, a Roblox Studio plugin written in Lua - -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. - -To install the server, either: - -* 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) - -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 - -## Server Usage -For more help, use `rojo help`. - -### New Project -Create a new folder, then use `rojo init` inside that folder to initialize an empty project: - -```sh -mkdir my-new-project -cd my-new-project - -rojo init -``` - -Rojo will create an empty project file named `rojo.json` in the directory. - -The default project file is: - -```json -{ - "name": "my-new-project", - "servePort": 8000, - "partitions": {} -} -``` - -### Start Dev Server -To start the Rojo dev server, use: - -```sh -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 -[Bi-directional script syncing](https://github.com/LPGhatguy/rojo/issues/5) is on the roadmap for Rojo this year, but isn't implemented. - -In the mean-time, manually migrating scripts is probably the best route forward. - -### 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 on your filesystem to Roblox objects. - -Each entry in the `partitions` map 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: - -```json -{ - "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, starting at `game`. If any objects don't exist along the way, Rojo will try to create them. - -**Any objects in a partition may be wiped away by Rojo after syncing! If this is not desired, use multiple, smaller partitions.** - -Run `rojo serve` in the directory containing this project, then press the "Sync In" or "Toggle Polling" buttons in the Roblox Studio plugin to sync into your game. - -### Sync Details -The structure of files and diectories 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: - -| File Name | Instance Type | Notes | -| -------------- | -------------- | ----------------------------------------- | -| `*.server.lua` | `Script` | `Source` will contain the file's contents | -| `*.client.lua` | `LocalScript` | `Source` will contain the file's contents | -| `*.lua` | `ModuleScript` | `Source` will contain the file's contents | -| `*.model.json` | *Varies* | See the example below | -| `*` | `StringValue` | `Value` will contain the file's contents | - -Any directories on the filesystem will turn into `Folder` objects. - -Any directory containing one of these files will instead be a `ModuleScript`, `Script`, `LocalScript` containing the directory's contents: - -* `init.lua` -* `init.server.lua` -* `init.client.lua` - -For example, this file tree: - -* my-game - * init.client.lua - * foo.lua - -Will turn into these instances in Roblox: - -* `my-game` (`LocalScript` with source from `my-game/init.client.lua`) - * `foo` (`ModuleScript` with source from `my-game/foo.lua`) - -`*.model.json` files are a way to represent simple Roblox instances on the filesystem until `rbxmx` and `rbxlx` support is implemented in Rojo. - -This feature is intended for small instances, like `RemoteEvent` or `*Value` objects. - -JSON Model files are strict, with every property being required. They look like this: - -```json -{ - "Name": "hello", - "ClassName": "Model", - "Children": [ - { - "Name": "Some Part", - "ClassName": "Part", - "Children": [], - "Properties": {} - }, - { - "Name": "Some StringValue", - "ClassName": "StringValue", - "Children": [], - "Properties": { - "Value": { - "Type": "String", - "Value": "Hello, world!" - } - } - } - ], - "Properties": {} -} -``` +## [Documentation Website](https://lpghatguy.github.io/rojo) +You can also view the documentation by browsing the [docs folder of the repository](https://github.com/LPGhatguy/rojo/tree/master/docs), but because it uses a number of Markdown extensions, it may not be very readable. ## Inspiration There are lots of other tools that sync scripts into Roblox or provide other tools for working with Roblox places.