diff --git a/docs/getting-started/creating-a-place.md b/docs/getting-started/creating-a-place.md new file mode 100644 index 00000000..1ff300ed --- /dev/null +++ b/docs/getting-started/creating-a-place.md @@ -0,0 +1,64 @@ +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 `roblox-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.rbxl +``` + +If you open `MyNewProject.rbxl` in Roblox Studio now, you should see a `Folder` containing a `ModuleScript` under `ReplicatedStorage`! + +!!! info + To generate an XML place file instead, like if you're checking the place file into version control, just use `rbxlx` as the extension on the output file instead. + +## 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 --place_id [PLACE ID] --cookie "[SECURITY COOKIE]" +``` \ No newline at end of file diff --git a/docs/getting-started/creating-a-project.md b/docs/getting-started/creating-a-project.md deleted file mode 100644 index 49dad7fc..00000000 --- a/docs/getting-started/creating-a-project.md +++ /dev/null @@ -1,77 +0,0 @@ -# Creating a Project -To use Rojo, you'll need to create a new project file, which tells Rojo what your project is, and how to load it into Roblox Studio. - -## New Project -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 create an empty project file named `rojo.json` in the directory. - -The default configuration doesn't do anything. We need to tell Rojo where our code is on the filesystem, and where we want to put it in the Roblox tree. - -To do that, open up `rojo.json` and add an entry to the `partitions` table: - -```json -{ - "name": "your-project-name-here", - "servePort": 8000, - "partitions": { - "src": { - "path": "src", - "target": "ReplicatedStorage.Project" - } - } -} -``` - -!!! warning - Make sure that the `src` directory exists in your project, or Rojo will throw an error! - -!!! warning - Any objects contained in the `target` of a partition will be destroyed by Rojo if not found on the filesystem! - -A Rojo project has one or more *partitions*. Partitions define how code should be transferred between the filesystem and Roblox by mapping directories and files to Roblox objects. - -Each partition has: - -* A name (the key in the `partitions` object), which is used for debugging -* `path`, the location on the filesystem relative to `rojo.json` -* `target`, the location in Roblox relative to `game` - -## Syncing into Studio - -Once you've added your partition to the project file, you can start the Rojo dev server by running a command in your project's directory: - -```sh -rojo serve -``` - -If your project is in the right place, Rojo will let you know that it was found and start an HTTP server that the plugin can connect to. - -In Roblox Studio, open the plugins tab and find Rojo's buttons. - -![Location of Rojo's plugin buttons in Roblox Studio](/images/plugin-buttons.png) -{: align="center" } - -Press **Test Connection** to verify that the plugin can communicate with the dev server. Watch the Output panel for the results. - -!!! info - If you see an error message, return to the previous steps and make sure that the Rojo dev server is running. - - ![Rojo error in Roblox Studio Output](/images/connection-error.png) - {: align="center" } - -After your connection was successful, press **Sync In** to move code from the filesystem into Studio, or use **Toggle Polling** to have Rojo automatically sync in changes as they happen. - -## Importing an Existing Project -Rojo will eventually support importing an existing Roblox project onto the filesystem for use with Rojo. - -Rojo doesn't currently support converting an existing project or syncing files from Roblox Studio onto the filesystem. In the mean time, you can manually copy your files into the structure that Rojo expects. - -Up-to-date information will be available on [issue #5](https://github.com/LPGhatguy/rojo/issues/5) as this is worked on. \ No newline at end of file diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 2b843a32..77a5728c 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -1,4 +1,3 @@ -# Installation Rojo has two components: * The server, a binary written in Rust diff --git a/docs/index.md b/docs/index.md index a3319d83..03f92af1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,5 @@ -# Home This is the documentation home for Rojo. **Rojo** is a flexible multi-tool designed for creating robust Roblox projects. -This documentation is a work in progress, and is incomplete. \ No newline at end of file +This documentation is a continual work in progress. If you find any issues, please file an issue on [Rojo's issue tracker](https://github.com/LPGhatguy/rojo/issues)! \ No newline at end of file diff --git a/docs/migrating-to-epiphany.md b/docs/migrating-to-epiphany.md new file mode 100644 index 00000000..98fca7b8 --- /dev/null +++ b/docs/migrating-to-epiphany.md @@ -0,0 +1,59 @@ +Rojo underwent a large refactor during most of 2018 to enable a bunch of new features and lay groundwork for lots more in 2019. As such, Rojo **0.5.x** projects are not compatible with Rojo **0.4.x** projects. + +## Supporting Both 0.4.x and 0.5.x +Rojo 0.5.x uses a different name for its project format. While 0.4.x used `rojo.json`, 0.5.x uses `roblox-project.json`, which allows them to coexist. + +If you aren't sure about upgrading or want to upgrade gradually, it's possible to keep both files in the same project without causing problems. + +## Upgrading Your Project File +Project files in 0.5.x are more explicit and flexible than they were in 0.4.x. Project files can now describe models and plugins in addition to places. + +This new project file format also guards against two of the biggest pitfalls when writing a config file: + +* Using a service as a partition target directly, which often wiped away extra instances +* Defining two partitions that overlapped, which made Rojo act unpredictably + +The biggest change is that the `partitions` field has been replaced with a new field, `tree`, that describes the entire hierarchy of your project from the top-down. + +A project for 0.4.x that syncs from the `src` directory into `ReplicatedStorage.Source` would look like this: + +```json +{ + "name": "Rojo 0.4.x Example", + "partitions": { + "path": "src", + "target": "ReplicatedStorage.Source" + } +} +``` + +In 0.5.x, the project format is more explicit: + +```json +{ + "name": "Rojo 0.5.x Example", + "tree": { + "$className": "DataModel", + "ReplicatedStorage": { + "$className": "ReplicatedStorage", + "Source": { + "$path": "src" + } + } + } +} +``` + +For each object in the tree, we define *metadata* and *children*. + +Metadata begins with a dollar sign (`$`), like `$className`. This is so that children and metadata can coexist without creating too many nested layers. + +All other values are considered children, where the key is the instance's name, and the value is an object, repeating the process. + +## Migrating `.model.json` Files +No upgrade path yet, stay tuned. + +## Migrating Unknown Files +If you used Rojo to sync in files as `StringValue` objects, you'll need to make sure those files end with the `txt` extension to preserve this in Rojo 0.5.x. + +Unknown files are now ignored in Rojo instead of being converted to `StringValue` objects. \ No newline at end of file diff --git a/docs/sync-details.md b/docs/sync-details.md index a9f2b7be..55a1e543 100644 --- a/docs/sync-details.md +++ b/docs/sync-details.md @@ -1,21 +1,24 @@ -# Sync Details This page aims to describe how Rojo turns files on the filesystem into Roblox objects. +## Overview +| File Name | Instance Type | +| -------------- | ------------------- | +| any directory | `Folder` | +| `*.server.lua` | `Script` | +| `*.client.lua` | `LocalScript` | +| `*.lua` | `ModuleScript` | +| `*.csv` | `LocalizationTable` | +| `*.txt` | `StringValue` | + ## Folders -Any directory on the filesystem will turn into a `Folder` instance in Roblox, unless that folder matches the name of a service or other existing instance. In those cases, that instance will be preserved. +Any directory on the filesystem will turn into a `Folder` instance unless it contains an 'init' script, described below. ## Scripts -Rojo can represent `ModuleScript`, `Script`, and `LocalScript` objects. The default script type is `ModuleScript`, since most scripts in well-structued Roblox projects will be modules. +The default script type in Rojo projects is `ModuleScript`, since most scripts in well-structued Roblox projects will be modules. -| File Name | Instance Type | -| -------------- | -------------- | -| `*.server.lua` | `Script` | -| `*.client.lua` | `LocalScript` | -| `*.lua` | `ModuleScript` | +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. -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 conents of the `init` file. This can be used to create scripts inside of scripts. - -For example, this file tree: +For example, these files: * my-game * init.client.lua @@ -25,41 +28,8 @@ Will turn into these instances in Roblox: ![Example of Roblox instances](/images/sync-example.png) -## Models -Rojo supports a JSON model format for representing simple models. It's designed for instance types like `BindableEvent` or `Value` objects, and is not suitable for larger models. +## 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. -Rojo JSON models are stored in `.model.json` files. - -Starting in Rojo version **0.4.10**, model files named `init.model.json` that are located in folders will replace that folder, much like Rojo's `init.lua` support. This can be useful to version instances like `Tool` that tend to contain several instances as well as one or more scripts. - -!!! info - In the future, Rojo will support `.rbxmx` models. See [issue #7](https://github.com/LPGhatguy/rojo/issues/7) for more details and updates on this feature. - -!!! warning - Prior to Rojo version **0.4.9**, the `Properties` and `Children` properties are required on all instances in JSON models! - -JSON model files are fairly strict; any syntax errors will cause the model to fail to sync! They look like this: - -`hello.model.json` -```json -{ - "Name": "hello", - "ClassName": "Model", - "Children": [ - { - "Name": "Some Part", - "ClassName": "Part" - }, - { - "Name": "Some StringValue", - "ClassName": "StringValue", - "Properties": { - "Value": { - "Type": "String", - "Value": "Hello, world!" - } - } - } - ] -} -``` \ No newline at end of file +## 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. \ No newline at end of file diff --git a/docs/why-rojo.md b/docs/why-rojo.md index b6872309..f4ecae06 100644 --- a/docs/why-rojo.md +++ b/docs/why-rojo.md @@ -1,4 +1,3 @@ -# Why Rojo? There are a number of existing plugins for Roblox that move code from the filesystem into Roblox. Besides Rojo, there is: diff --git a/mkdocs.yml b/mkdocs.yml index 703712bf..a6cbf9fc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,8 +14,9 @@ pages: - Why Rojo?: why-rojo.md - Getting Started: - Installation: getting-started/installation.md - - Creating a Project: getting-started/creating-a-project.md + - Creating a Place with Rojo: getting-started/creating-a-place.md - Sync Details: sync-details.md + - Migrating from 0.4.x to 0.5.x: migrating-to-epiphany.md markdown_extensions: - attr_list