Skip to content

Latest commit

 

History

History
247 lines (175 loc) · 8.24 KB

sync-details.md

File metadata and controls

247 lines (175 loc) · 8.24 KB
Raw
sidebar_position title
5
Sync Details

Sync Details

This page aims to describe how Rojo turns files on the filesystem into Roblox objects.

Overview

Concept File Name
Folders any directory
Server Scripts *.server.lua
Client Scripts *.client.lua
Module Scripts *.lua
XML Models *.rbxmx
Binary Models *.rbxm
Localization Tables *.csv
Plain Text *.txt
JSON Modules *.json
TOML Modules *.toml
JSON Models *.model.json
Projects *.project.json
Meta Files *.meta.json

Limitations

Not all property types can be synced by Rojo in real-time due to limitations of the Roblox Studio plugin API. In these cases, you can usually generate a place file and open it when you start working on a project.

Some common cases you might hit are:

  • Binary data (Terrain, CSG parts)
  • MeshPart.MeshId
  • HttpService.HttpEnabled

For a list of all property types that Rojo can reason about, both when live-syncing and when building place files, look at rbx-dom's type coverage chart.

This limitation may be solved by issue #205 in the future.

Folders

Any directory on the filesystem will turn into a Folder instance with the same name.

It is possible for a directory to contain certain files that change what the directory turns into:

  • An init.lua, init.server.lua, or init.client.lua file, described in Scripts.
  • An init.meta.json file that defines className, described in Meta Files.
  • A default.project.json file, described in Projects.

Scripts

Rojo transforms any files with the lua extension into the various script instances that Roblox has.

  • Any file ending in .server.lua will turn into a Script instance.
  • Any file ending in .client.lua will turn into a LocalScript instance.
  • Any other .lua file will turn into a ModuleScript instance.

Rojo reserves three special script names. These scripts change their parent directory into a script instead of a folder:

  • init.server.lua will change its parent directory into a Script instance.
  • init.client.lua will change its parent directory into a LocalScript instance.
  • init.lua will change its parent directory into a ModuleScript instance.

For example, these files:

graph TD;
  my_model(My Model/)
  init(init.server.lua)
  foo(foo.lua)

  my_model --> init
  my_model --> foo
Loading

Will turn into these instances in Roblox:

graph TD;
  my_model("My Model (Script)")
  foo("Foo (Script)")

  my_model --> foo
Loading

Only one "init script" can be present in the same folder.

Models

Rojo supports both binary (.rbxm) and XML (.rbxmx) models generated by Roblox Studio or another tool.

For a rundown of supported types, check out rbx-dom's type coverage chart.

Localization Tables

Any file with the csv extension is transformed into a LocalizationTable instance. Rojo expects these files to follow the same format that Roblox does when importing and exporting localization information.

An example CSV localization table is:

Key,Source,Context,Example,es
Ack,Ack!,,An exclamation of despair,¡Ay!

Plain Text

Any file with the txt extension is transformed into a StringValue instance. This is useful for bringing in text data that can be read by scripts at runtime.

JSON Modules

Any file with the json extension that is not a JSON Model or a Project File will be synced as a ModuleScript that returns a table representing the same structure as the JSON file. That is, the following JSON:

{
  "Hello": "world!",
  "bool": true,
  "array": [1, 2, 3],
  "object": {
    "key 1": 1337,
    "key 2": []
  }
}

Would become a ModuleScript with the following Source:

return {
	Hello = "world!",
	array = {1, 2, 3},
	bool = true,
	object = {
		["key 1"] = 1337,
		["key 2"] = {},
	},
}

TOML Modules

Any file with the toml extension will be synced as a ModuleScript that returns a table representing the same structure as the TOML file. Due to the easy to read and edit format of TOML, it can be convenient to use them as config files. For a better idea of what synced toml files look like, see JSON Modules.

There is a single limitation for TOML syncing: DateTime values are converted into string values and not the corresponding data type. This is due to the conflicting formats used between them. This is not something most people should have to worry about, but it's still something to be aware of.

JSON Models

Files ending in .model.json can be used to describe simple models. They're designed to be hand-written and are useful for instances like RemoteEvent.

A JSON model describing a folder containing a Part and a RemoteEvent could be written as a file named My Cool Model.model.json with:

{
  "ClassName": "Folder",
  "Children": [
    {
      "Name": "RootPart",
      "ClassName": "Part",
      "Properties": {
        "Size": [4, 4, 4]
      }
    },
    {
      "Name": "SendMoney",
      "ClassName": "RemoteEvent"
    }
  ]
}

It would turn into these instances:

graph TD;
  parent("My Cool Model (Folder)")
  part("RootPart (Part)")
  remote("SendMoney (RemoteEvent)")

  parent --> part
  parent --> remote
Loading

Projects

Starting in Rojo 6.0, project files can be included in other project files. This can be useful for reusing pieces between multiple project files.

Projects that are intended to be included inside other projects should describe models, not places.

If a directory contains a file named default.project.json, Rojo will use the contents of the project file instead of anything else in the directory.

Meta Files

New in Rojo 0.5 are meta files, named .meta.json.

Meta files allow attaching extra Rojo data to models defined in other formats, like Roblox's rbxm and rbxmx model formats, or even Lua scripts.

This can be used to set Rojo-specific settings like ignoreUnknownInstances, or can be used to set properties like Disabled on a script.

Meta files can contain:

  • className: Changes the className of a containing Folder into something else.
    • Usable only in init.meta.json files
  • properties: A map of properties to set on the instance, just like projects
    • Usable on anything except .rbxmx, .rbxm, and .model.json files, which already have properties
  • ignoreUnknownInstances: Works just like $ignoreUnknownInstances in project files

Meta Files to set Rojo metadata

Sometimes it's useful to apply properties like ignoreUnknownInstances on instances that are defined on the filesystem instead of within the project itself.

If your project has hello.txt and there are instances underneath it that you want Rojo to ignore when live-syncing, you could create hello.meta.json with:

{
  "ignoreUnknownInstances": true
}

Meta Files for Disabled Scripts

Meta files can be used to set properties on Script instances, like Disabled.

If your project has foo.server.lua and you want to make sure it would be disabled, you could create a foo.meta.json next to it with:

{
  "properties": {
    "Disabled": true
  }
}

Meta Files for Tools

If you wanted to represent a tool containing a script and a model for its handle, create a directory with an init.meta.json file in it:

{
  "className": "Tool",
  "properties": {
    "Grip": [0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1]
  }
}

Instead of a Folder instance, you'll end up with a Tool instance with the Grip property set.