diff --git a/docs/creating-a-place.md b/docs/creating-a-place.md deleted file mode 100644 index d20f8ffd..00000000 --- a/docs/creating-a-place.md +++ /dev/null @@ -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]" -``` \ No newline at end of file diff --git a/docs/extra.css b/docs/extra.css index 020a7103..ed31fbc9 100644 --- a/docs/extra.css +++ b/docs/extra.css @@ -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); } \ No newline at end of file diff --git a/docs/guide/existing-game.md b/docs/guide/existing-game.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/installation.md b/docs/guide/installation.md similarity index 92% rename from docs/installation.md rename to docs/guide/installation.md index 728c8dfd..b56f31c8 100644 --- a/docs/installation.md +++ b/docs/guide/installation.md @@ -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 diff --git a/docs/migrating-to-epiphany.md b/docs/guide/migrating-to-epiphany.md similarity index 100% rename from docs/migrating-to-epiphany.md rename to docs/guide/migrating-to-epiphany.md diff --git a/docs/guide/new-game.md b/docs/guide/new-game.md new file mode 100644 index 00000000..7a3f46ca --- /dev/null +++ b/docs/guide/new-game.md @@ -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) \ No newline at end of file diff --git a/docs/images/connection-dialog.png b/docs/images/connection-dialog.png new file mode 100644 index 00000000..5a3d5f29 Binary files /dev/null and b/docs/images/connection-dialog.png differ diff --git a/docs/project-format.md b/docs/reference/project-format.md similarity index 58% rename from docs/project-format.md rename to docs/reference/project-format.md index c21e32ff..4b6f80d3 100644 --- a/docs/project-format.md +++ b/docs/reference/project-format.md @@ -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": { diff --git a/docs/sync-details.md b/docs/reference/sync-details.md similarity index 94% rename from docs/sync-details.md rename to docs/reference/sync-details.md index 2bb6ec53..ae64e7fe 100644 --- a/docs/sync-details.md +++ b/docs/reference/sync-details.md @@ -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 diff --git a/docs/rojo-alternatives.md b/docs/rojo-alternatives.md new file mode 100644 index 00000000..247dad7b --- /dev/null +++ b/docs/rojo-alternatives.md @@ -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. \ No newline at end of file diff --git a/docs/why-rojo.md b/docs/why-rojo.md index 247dad7b..290c6208 100644 --- a/docs/why-rojo.md +++ b/docs/why-rojo.md @@ -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. \ No newline at end of file +* [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 \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 2f27e470..c0dac993 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,11 +11,15 @@ theme: nav: - Home: index.md - Why Rojo?: why-rojo.md - - Installation: installation.md - - Creating a Place with Rojo: creating-a-place.md - - Migrating from 0.4.x to 0.5.x: migrating-to-epiphany.md - - Project Format: project-format.md - - Sync Details: sync-details.md + - Guide: + - Installation: guide/installation.md + - Creating a Game with Rojo: guide/new-game.md + # - Moving an Existing Game to Rojo: guide/existing-game.md + - Migrating from 0.4.x to 0.5.x: guide/migrating-to-epiphany.md + - Reference: + - Project Format: reference/project-format.md + - Sync Details: reference/sync-details.md + - Rojo Alternatives: rojo-alternatives.md - Rojo Internals: - Internals Overview: internals/overview.md