File Types

Argon supports various file types, here is how they are transformed into Roblox instances!

Overview

File Type	File Name
Folder	any directory
Server Script	*.server.lua / *.server.luau
Client Script	*.client.lua / *.client.luau
Module Script	*.lua / *.luau
XML Model	*.rbxmx
Binary Model	*.rbxm
JSON Model	*.model.json
JSON Module	*.json
TOML Module	*.toml
YAML Module	*.yaml / *.yml
MessagePack Module	*.msgpack
Markdown	*.md
Plain Text	*.txt
Localization Table	*.csv
Project	*.project.json
Data File	*.data.json / .data.json

Instances with Children

All mentioned file types can contain children. To do so you have to create a folder with the desired name and add .src or init file with the suffix based on the desired file type inside that folder. The only exceptions are: Project whose immediate children are ignored and Data File which is used to describe instance. Here are some examples:

Instance + Children

Filesystem	Roblox

(Instance + Data) + Children

Filesystem	Roblox

Instance + (Children + Data)

Filesystem	Roblox

danger

Only one .src / init file and one .data / init.meta can be present in the same folder!

Folder

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 described above.

Scripts

Files with lua or luau extensions are transformed into the corresponding Roblox script instances:

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

tip

You can disable scripts by adding --disable comment at the very beginning of the script source without needing to create special Data File only for this property!

note

If the project has legacyScripts setting disabled:

• .server.lua(u) will turn into a Script with a Server run context
• .client.lua(u) will turn into a Script with a Local run context

Roblox Models

Both binary (rbxm) and XML (rbxmx) models generated by Roblox Studio and other tools are supported. They get seamlessly integrated with the project tree.

Property type support chart

Property Type	Example Property	CLI	Plugin	XML	Binary
Attributes	Instance.Attributes	✅	✅	✅	✅
Axes	ArcHandles.Axes	✅	✅	✅	✅
BinaryString	BinaryStringValue.Value	✅	⏺️	✅	✅
Bool	Part.Anchored	✅	✅	✅	✅
BrickColor	Part.BrickColor	✅	✅	✅	✅
Bytecode	N/A	❌	⛔	❌	❌
CFrame	Camera.CFrame	✅	✅	✅	✅
Color3	Lighting.Ambient	✅	✅	✅	✅
Color3uint8	Part.BrickColor	✅	✅	✅	✅
ColorSequence	Beam.Color	✅	✅	✅	✅
Content	Decal.Texture	✅	✅	✅	✅
Enum	Part.Shape	✅	✅	✅	✅
Faces	Handles.Faces	✅	✅	✅	✅
Float32	Players.RespawnTime	✅	✅	✅	✅
Float64	Sound.PlaybackLoudness	✅	✅	✅	✅
Font	TextLabel.Font	✅	✅	✅	✅
Int32	Frame.ZIndex	✅	✅	✅	✅
Int64	Player.UserId	✅	✅	✅	✅
MaterialColors	Terrain.MaterialColors	✅	✅	✅	✅
NumberRange	ParticleEmitter.Lifetime	✅	✅	✅	✅
NumberSequence	Beam.Transparency	✅	✅	✅	✅
OptionalCFrame	Model.WorldPivotData	✅	✅	✅	✅
PhysicalProperties	Part.CustomPhysicalProperties	✅	✅	✅	✅
ProtectedString	ModuleScript.Source	✅	✅	✅	✅
Ray	RayValue.Value	✅	✅	✅	✅
Rect	ImageButton.SliceCenter	✅	✅	✅	✅
Ref	Model.PrimaryPart	✅	✅	✅	✅
Region3	N/A	✅	✅	❌	❌
Region3int16	Terrain.MaxExtents	✅	✅	❌	❌
SecurityCapabilities	Folder.SecurityCapabilities	✅	❌	✅	✅
SharedString	N/A	✅	✅	✅	✅
String	Instance.Name	✅	✅	✅	✅
Tags	UIListLayout.Padding	✅	✅	✅	✅
UDim	Frame.Size	✅	✅	✅	✅
UDim2	Instance.UniqueId	✅	❌	✅	✅
Vector2	ImageLabel.ImageRectSize	✅	✅	✅	✅
Vector2int16	N/A	✅	✅	✅	❌
Vector3	Part.Size	✅	✅	✅	✅
Vector3int16	TerrainRegion.ExtentsMax	✅	✅	✅	✅
QDir	Studio.Auto-Save Path	⛔	⛔	⛔	⛔
QFont	Studio.Font	⛔	⛔	⛔	⛔

✅ Implemented | ❌ Unimplemented | ⏺️ Partially Implemented | ⛔ Never

JSON Model

File ending with .model.json is used to describe multiple instances in a single file or to conveniently describe single but more complex one like Part. Example JSON model named Coin.model.json:

{
  "ClassName": "Part",
  "Properties": {
    "Size": [2, 2, 2]
  }
  "Children": [
    {
      "Name": "Input",
      "ClassName": "ClickDetector",
    },
    {
      "Name": "Send",
      "ClassName": "RemoteEvent"
    }
  ]
}

Would be turned into these instances:

JSON Module

Any file with the json extension that is not a JSON Model, Project File, or a Data File will be turned into a ModuleScript that returns a table representing the same structure as the JSON file. Example JSON file:

{
  "string": "abc",
  "bool": true,
  "array": [1, 2, 3],
  "object": {
    "int": 1337,
    "float": 4.2
  }
}

Would become a ModuleScript with the following Source:

return {
	["string"] = "abc",
	["bool"] = true,
	["array"] = {1, 2, 3},
	["object"] = {
		["int"] = 1337,
		["float"] = 4.2,
	}
}

JSON files are a great way to store bulk data (e.g. asset IDs) in a human-readable format.

TOML Module

Any file with the toml extension will be turned into a ModuleScript that returns a table representing the same structure as the TOML file. Example TOML file:

string = "abc"
bool = true
array = [1, 2, 3]

[object]
int = 1337
float = 4.2

Would become a ModuleScript with the following Source:

return {
	["string"] = "abc",
	["bool"] = true,
	["array"] = {1, 2, 3},
	["object"] = {
		["int"] = 1337,
		["float"] = 4.2,
	}
}

Due to the easy to read and edit format of TOML, it can be convenient to use them as configuration files.

info

DateTime values are converted into strings because Luau does not have a good representation of this data type.

YAML Module

Any file with the yaml or yml extension will be turned into a ModuleScript that returns a table representing the same structure as the YAML file. Example YAML file:

string: abc
bool: true

array:
  - 1
  - 2
  - 3

object:
  int: 1337
  float: 4.2

Would become a ModuleScript with the following Source:

return {
	["string"] = "abc",
	["bool"] = true,
	["array"] = {1, 2, 3},
	["object"] = {
		["int"] = 1337,
		["float"] = 4.2,
	}
}

Thanks to its easy syntax, YAML files are great as configuration files as well.

warning

Mappings only support string, number and bool keys, other ones will be completely skipped!

MessagePack Module

Any file with the msgpack extension will be turned into a ModuleScript that returns a table representing the same structure as the original file. MessagePack is a binary format so it's fast and small but it's not human-readable. It is great for storing large amounts of data that don't need to be edited by hand.

Markdown

Any file with the md extension is transformed into a StringValue instance containing Markdown translated to Rich Text Markup. Example Markdown file:

# Heading

> Block quote

- Unordered list item A
- Unordered list item B

1. Ordered list item A
2. Ordered list item B

Some **Bold** text, with addition of _italic_ and `code`

Would become a StringValue with the following Value:

<b>Heading</b>

<i>Block quote</i>

<b>•</b> Unordered list item A
<b>•</b> Unordered list item B

1. Ordered list item A
2. Ordered list item B

Some <b>Bold</b> text, with addition of <i>italic</i> and <font family='rbxasset://fonts/families/RobotoMono.json'>code</font>

Plain Text

Any file with the txt extension is transformed into a StringValue instance with its Value property set to the file contents. Example text file:

Hello world!

Localization Table

Any file with the csv extension is transformed into a LocalizationTable instance. You should follow this Roblox format:

Key,Source,Context,Example,pl
Wow,Wow!,,An expression of surprise,Łał!

Project

File ending with .project.json is considered project which describes how the underlying instance tree should look like and how files should be processed along the way. You can learn about its format on the Project page.

If a directory contains a file named default.project.json, the contents of the project file will be used instead.

danger

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

Data File

File ending with .data.json is considered data file which can specify:

• className: Sets the ClassName of a containing Folder instance
• properties: A map of properties to apply on the instance
• keepUnknowns: Whether children that Argon doesn't know about should be deleted

This page is based on Rojo's Sync Details as Argon processes files in a very similar way.