Roblox XML file format

This document describes the XML format for Roblox place and model files. Common extensions for this format include rbxlx (place) and rbxmx (model). For brevity, this document will refer to the format as RBXLX.

Preliminary concepts

The RBXLX format is based on XML. Like XML, it has a concept of tags, elements, attributes, markup, and so on. However, more advanced concepts, like namespaces, may be ignored.

Format overview

Elements may be encoded in any order, and must be decodable in any order.

The following tree gives an overview of the document file structure. It describes the order in which Roblox encodes elements, the parent-child relationship between element types, and their quantities.

<roblox> (exactly one)
- <Meta> (zero or more)
- <External> (zero or more)
- <Item> (zero or more)
  - <Properties> (exactly one)
    - (type elements; ordered alphabetically by name attribute)
  - <Item> (zero or more)
- <SharedStrings> (zero or one)
  - <SharedString> (zero or more)

By convention, tabs are used for indentation.

Elements

This section describes the various element types, their formats, and their relationships with other element types.

The description of each element type has a Contains field. This describes how the inner content of the element should be interpreted. The following table list each type of container:

Type	Description
elements	Child elements are significant. Text content is ignored.
text	Text content is significant, but leading and trailing whitespace is ignored.
rawtext	All text content is significant.

`<roblox>`

Contains: elements

The root element of a file. The file must begin with this element. That is, the bytes <roblox. This element must be the only top-level element. For maximum compatibility, no content should appear after the end tag. That is, the file should end with the bytes </roblox>.

The following attributes are required:

Attribute	Status	Description
`version`	Required	Must have a value of `4`. Other versions are currently not supported.

Roblox encodes the following additional attributes. These are not required. Moreover, any defined schemas are ignored, and not required for a file to be valid.

Attribute	Value
`xmlns:xmime`	`http://www.w3.org/2005/05/xmlmime`
`xmlns:xsi`	`http://www.w3.org/2001/XMLSchema-instance`
`xsi:noNamespaceSchemaLocation`	`http://www.roblox.com/roblox.xsd`

Example

<roblox xmlns:xmime="http://www.w3.org/2005/05/xmlmime" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.roblox.com/roblox.xsd" version="4">
	...
</roblox>

`<Meta>`

Child of: <roblox>
Contains: text

Maps a metadata key to a value. Only present in model files.

The following attributes are required:

Attribute	Description
`name`	The key of the metadata entry.

The following metadata entries are known:

Key	Value	Description
`ExplicitAutoJoints`	`true`	Model was made in a workspace with Explicit AutoJointsMode.

Example

<Meta name="ExplicitAutoJoints">true</Meta>

`<External>`

Child of: <roblox>
Contains: text

<External> is a legacy concept that is no longer used.

This element has no attributes.

Roblox currently encodes files with two <External> elements, having the following content, respectively:

null
nil

Including these elements is optional.

Example

<External>null</External>
<External>nil</External>

`<Item>`

Child of: <roblox>, <Item>
Contains: elements

Describes an instance.

The following attributes are required:

Attribute	Description
`class`	The class name of the instance.

The following attributes are optional:

Attribute	Description
`referent`	A unique string used by `<Ref>` elements to refer to the instance.

Roblox encodes all <Item> elements with a referent attribute. Each value is generated by starting with the prefix RBX, followed by a UUID version 4, with - characters removed, and all characters converted to uppercase.

Note: The word "referent" is a misnomer. The attribute actually describes a reference, which is used by referents.

Example

<Item class="Workspace" referent="RBXD843BA20829A44A882E1202C8085A2C4">
	...
</Item>

`<Properties>`

Child of: <Item>
Contains: elements

Contains the properties of an instance.

This element has no attributes.

Each child element is a type element. Elements may be sorted by their name attribute.

Example

<Item class="Workspace" referent="RBXD843BA20829A44A882E1202C8085A2C4">
	<Properties>
		...
	</Properties>
</Item>

`<SharedStrings>`

Child of: <roblox>
Contains: elements

Contains definitions of shared strings.

Example

<SharedStrings>
	...
</SharedStrings>

`<SharedString>`

Child of: <SharedStrings>
Contains: text

Defines a shared string. The value of the md5 attribute is a Base64-encoded key. <SharedString> type elements use this key to refer to the value of the string.

The value is the text content, which is Base64-encoded.

Historically, the key was the MD5 hash of the string value. However, this is not required; the key can be any value that will uniquely identify the shared string. Roblox currently uses BLAKE2b truncated to 16 bytes.

Example

<SharedStrings>
	<SharedString md5="bNNVbesNpUvKBgtMOUeYOQ==">SGVsbG8sIHdvcmxkIQ==</SharedString>
</SharedStrings>

Type elements

A type element is an element that describes a single property of an instance. All type elements are the child of a <Properties> element. All type elements have the following required attributes:

Attribute	Description
`name`	The name of the property.

Each type element has a property type, which corresponds to the type of the property's value. This determines how the content of the type element is interpreted. The property type is determined with one of several methods:

Descriptor: The property type is determined according to the name attribute of the type element, and the class attribute of the nearest parent <Item> element. This combination of class and property may be used with an external class descriptor to query the property type of the element. With this method, the name of a type element can be ignored.
Element: The property type is determined according to the name of the type element.

Roblox uses the Descriptor method to decode type elements. Roblox also encodes type elements with a name corresponding to its property type.

The "canonical name" is the element name emitted when a type element is encoded. The following table lists each type and its corresponding name:

Canonical name	Property type	Notes
`Axes`	Axes
`BinaryString`	BinaryString
`BrickColor`	BrickColor	Roblox encodes as "int".
`Color3`	Color3
`Color3uint8`	Color3uint8
`ColorSequence`	ColorSequence
`Content`	Content
`CoordinateFrame`	CFrame
`Faces`	Faces
`Font`	Font
`NumberRange`	NumberRange
`NumberSequence`	NumberSequence
`Ref`	Instance
`PhysicalProperties`	PhysicalProperties
`ProtectedString`	ProtectedString
`Ray`	Ray
`Rect2D`	Rect
`SharedString`	SharedString
`UDim`	UDim
`UDim2`	UDim2
`UniqueId`	UniqueId
`Vector2`	Vector2
`Vector2int16`	Vector2int16
`Vector3`	Vector3
`Vector3int16`	Vector3int16
`bool`	bool
`double`	double
`float`	float
`int`	int	Roblox also encodes BrickColors with this name.
`int64`	int64
`string`	string
`token`	(enum item)
`Optional`(type)	(optional)	A name may have the "Optional" prefix, which indicates that the property type is the optional variant of the type corresponding to the rest of the name.

The type is used to determine how the value of a property is interpreted. Components of a type may be defined as being interpreted according to another type. In this case, only the inner content is interpreted.

For example, the Vector3 type has a sub-element for each of its X, Y, and Z components, which are interpreted according to the float type.

Axes

Child of: <Properties>
Canonical name: Axes
Property type: Axes
Contains: elements

Contains one <axes> element. The text of this element is formatted as an integer between 0 and 7, which is a bit field representing a combination of the axes' X, Y, and Z components. A 0 bit represents false, and a 1 bit represents true.

The components are ordered in the following way, from least-significant to most-significant:

X
Y
Z

Example

<!-- With no components. -->
<Axes name="Example"><axes>0</axes></Axes>

<!-- With X and Z components. -->
<Axes name="Example"><axes>5</axes></Axes>

<!-- With all components. -->
<Axes name="Example"><axes>7</axes></Axes>

BinaryString

Child of: <Properties>
Canonical name: BinaryString
Property type: BinaryString
Contains: text

The value is the text content, which is Base64-encoded. Newlines are ignored, so the content may be wrapped.

Example

<BinaryString name="Example">SGVsbG8sIHdvcmxkIQ==</BinaryString>

BrickColor

Child of: <Properties>
Canonical name: BrickColor
Property type: BrickColor
Contains: text

The value is the text content, which is a 32-bit integer representing the Number of the BrickColor.

Roblox encodes the tags as "int", but this is not required for Roblox to properly decode the type. For better compatibility, it is preferred that third-party implementations encode and decode "BrickColor" tags instead.

Example

<!-- Roblox encodes as int. -->
<int name="Example">194</int>

<!-- Preferred encoding. -->
<BrickColor name="Example">194</BrickColor>

Color3

Child of: <Properties>
Canonical name: Color3
Property type: Color3
Contains: elements / text

The value can be represented in one of several ways.

Text: The value is the text content, which is formatted as a 32-bit unsigned integer with the range 0 - 255. Bits of the integer correspond to values of components.

Component	Bits	Mask	Notes
(unused)	24-31	0xFF000000	Always has a value of 0xFF.
R	16-23	0x00FF0000
G	8-15	0x0000FF00
B	0- 7	0x000000FF

Elements: Contains an element for each component of the Color3:

R: Corresponds to the R component.
G: Corresponds to the G component.
B: Corresponds to the B component.

The value of each component is represented by the text content formatted as a 32-bit floating point number (see float) with the range 0 - 1.

It is recommended that Color3 is encoded with elements instead of text.

Example

<!-- Using a numeric value. -->
<Color3 name="Example">4288914085</Color3>

<!-- Using components. -->
<Color3 name="Example">
	<R>0.639215708</R>
	<G>0.635294139</G>
	<B>0.647058845</B>
</Color3>

Color3uint8

Child of: <Properties>
Canonical name: Color3uint8
Property type: Color3uint8
Contains: text

The value can be represented in one of several ways.

Text: The value is the text content, which is formatted as a 32-bit unsigned integer with the range 0 - 255. Bits of the integer correspond to values of components.

Component	Bits	Mask	Notes
(unused)	24-31	0xFF000000	Always has a value of 0xFF.
R	16-23	0x00FF0000
G	8-15	0x0000FF00
B	0- 7	0x000000FF

Elements: Contains an element for each component of the Color3:

R: Corresponds to the R component.
G: Corresponds to the G component.
B: Corresponds to the B component.

The value of each component is represented by the text content formatted as an 8-bit unsigned integer.

It is recommended that Color3uint8 is encoded with text instead of elements.

Example

<!-- Using a numeric value. -->
<Color3uint8 name="Example">4288914085</Color3uint8>

<!-- Using components. -->
<Color3uint8 name="Example">
	<R>163</R>
	<G>162</G>
	<B>165</B>
</Color3uint8>

ColorSequence

Child of: <Properties>
Canonical name: ColorSequence
Property type: ColorSequence
Contains: text

The value is the text content, formatted as a space-separated list of floating point numbers. To be correct, the list must contain a multiple of 5 numbers. Each group of 5 numbers forms the components of a ColorSequenceKeypoint, in the following order:

Time: Has the range 0 - 1.
Value.R: Has the range 0 - 1.
Value.G: Has the range 0 - 1.
Value.B: Has the range 0 - 1.
Envelope: Has the range 0 - 1. Currently unused by Roblox.

Example

<ColorSequence name="Example">0 1 0 0 0 0.5 1 1 0 0 1 0 0.5 1 0 </ColorSequence>

Content

Child of: <Properties>
Canonical name: Content
Property type: Content
Contains: text

Contains one of several elements:

Element	Description
`binary`	Legacy value for embedded binary data. Should be interpreted as empty.
`hash`	Legacy value for deferred data. Should be interpreted as empty.
`null`	Value is empty. Must have no inner content.
`url`	Value is the text content.

Example

<!-- Empty. -->
<Content name="Example"><null></null></Content>

<!-- With URL. -->
<Content name="Example"><url>rbxasset://textures/SpawnLocation.png</url></Content>

CoordinateFrame

Child of: <Properties>
Canonical name: CoordinateFrame
Property type: CFrame
Contains: elements

Contains an element for each component of the CFrame:

X
Y
Z
R00
R01
R02
R10
R11
R12
R20
R21
R22

The value of each component is represented by the text content formatted as a 32-bit floating point number (see float).

These components construct a CFrame in the following way:

CFrame.new(X, Y, Z, R00, R01, R02, R10, R11, R12, R20, R21, R22)

Example

<CoordinateFrame name="Example">
	<X>10</X>
	<Y>20</Y>
	<Z>30</Z>
	<R00>1</R00>
	<R01>0</R01>
	<R02>0</R02>
	<R10>0</R10>
	<R11>1</R11>
	<R12>0</R12>
	<R20>0</R20>
	<R21>0</R21>
	<R22>1</R22>
</CoordinateFrame>

Faces

Child of: <Properties>
Canonical name: Faces
Property type: Faces
Contains: elements

Contains one <faces> element. The text of this element is formatted as an integer between 0 and 63, which is a bit field representing a combination of the faces' Right, Top, Back, Left, Bottom, and Front components. A 0 bit represents false, and a 1 bit represents true.

The components are ordered in the following way, from least-significant to most-significant:

Right
Top
Back
Left
Bottom
Front

Example

<!-- With no components. -->
<Faces name="Example"><faces>0</faces></Faces>

<!-- With Right and Left components. -->
<Faces name="Example"><faces>9</faces></Faces>

<!-- With all components. -->
<Faces name="Example"><faces>63</faces></Faces>

Font

Child of: <Properties>
Canonical name: Font
Property type: Font
Contains: elements

Contains elements for each component of the Font.

Family: Value is interpreted according to the Content type.
Weight: Text content is formatted as an integer representing the value of a FontWeight enum item.
Style: Text content is formatted as a string representing the name of a FontStyle enum item.
CachedFaceId: Optional. Value is interpreted according to the Content type.

The FontWeight enum has the following items:

Name	Value
Thin	100
ExtraLight	200
Light	300
Regular	400
Medium	500
SemiBold	600
Bold	700
ExtraBold	800
Heavy	900

The FontStyle enum has the following items:

Name	Value
Normal	0
Italic	1

Example

<Font name="Example">
	<Family><url>rbxasset://fonts/families/SourceSansPro.json</url></Family>
	<Weight>400</Weight>
	<Style>Normal</Style>
	<CachedFaceId><url>rbxasset://fonts/SourceSansPro-Regular.ttf</url></CachedFaceId>
</Font>

NumberRange

Child of: <Properties>
Canonical name: NumberRange
Property type: NumberRange
Contains: text

The value is the text content, formatted as a space-separated list of floating point numbers. Numbers in the list correspond to the following components:

Min
Max

Example

<NumberRange name="Example">5 10 </NumberRange>

NumberSequence

Child of: <Properties>
Canonical name: NumberSequence
Property type: NumberSequence
Contains: text

The value is the text content, formatted as a space-separated list of floating point numbers. To be correct, the list must contain a multiple of 3 numbers. Each group of 3 numbers forms the components of a NumberSequenceKeypoint, in the following order:

Time
Value
Envelope

Example

<NumberSequence name="Example">0 1 0 0.500574 0.4875 0.24375 1 1 0 </NumberSequence>

Ref

Child of: <Properties>
Canonical name: Ref
Property type: Instance
Contains: text

The text content matches the value of a referent attribute of an <Item> element within the file. The value is the instance represented by the referred item.

Example

<Ref name="Example">RBXD843BA20829A44A882E1202C8085A2C4</Ref>

PhysicalProperties

Child of: <Properties>
Canonical name: PhysicalProperties
Property type: PhysicalProperties
Contains: elements

Contains at least one CustomPhysics element, which is interpreted according to the bool type. If this value is true, then the tag also contains an element for each component of the PhysicalProperties:

Density
Friction
Elasticity
FrictionWeight
ElasticityWeight

The value of each component is represented by the text content formatted as a 32-bit floating point number (see float).

Example

<!-- No custom physics. -->
<PhysicalProperties name="Example">
	<CustomPhysics>false</CustomPhysics>
</PhysicalProperties>

<!-- Custom physics. -->
<PhysicalProperties name="Example">
	<CustomPhysics>true</CustomPhysics>
	<Density>0.699999988</Density>
	<Friction>0.300000012</Friction>
	<Elasticity>0.5</Elasticity>
	<FrictionWeight>1</FrictionWeight>
	<ElasticityWeight>1</ElasticityWeight>
</PhysicalProperties>

ProtectedString

Child of: <Properties>
Canonical name: ProtectedString
Property type: ProtectedString
Contains: rawtext

The value is the text content.

Example

<!-- Using CDATA. -->
<ProtectedString name="Example"><![CDATA[for i = 1, 10 do
	print("Hello", i)
end
]]></ProtectedString>

<!-- For CDATA-incompatible strings. -->
<ProtectedString name="Example">for i = 1, 10 do
&#9;print(&quot;Hello&quot;, i) -- ]]&gt;
end
</ProtectedString>

Ray

Child of: <Properties>
Canonical name: Ray
Property type: Ray
Contains: elements

Contains elements for each component of the Ray:

origin
direction

Each element is interpreted according to the Vector3 type.

Example

<Ray name="Example">
	<origin>
		<X>0</X>
		<Y>0</Y>
		<Z>0</Z>
	</origin>
	<direction>
		<X>0</X>
		<Y>0</Y>
		<Z>0</Z>
	</direction>
</Ray>

Rect2D

Child of: <Properties>
Canonical name: Rect2D
Property type: Rect
Contains: elements

Contains elements for each component of the Rect:

min
max

Each element is interpreted as a <Vector2>.

Example

<Rect2D name="Example">
	<min>
		<X>0</X>
		<Y>0</Y>
	</min>
	<max>
		<X>0</X>
		<Y>0</Y>
	</max>
</Rect2D>

SharedString

Child of: <Properties>
Canonical name: SharedString
Property type: SharedString
Contains: text

The text content, which is Base64-encoded, matches the key of a <SharedString> definition. The value is the value of the shared string, which is Base64-encoded.

Example

<SharedString name="Example">bNNVbesNpUvKBgtMOUeYOQ==</SharedString>

UDim

Child of: <Properties>
Canonical name: UDim
Property type: UDim
Contains: elements

Contains elements for each component of the UDim:

S: Represents the Scale component. Interpreted as a <float>.
O: Represents the Offset component. Interpreted as an <int>.

Example

<UDim name="Example">
	<S>0.5</S>
	<O>100</O>
</UDim>

UDim2

Child of: <Properties>
Canonical name: UDim2
Property type: UDim2
Contains: elements

Contains elements for each component of the UDim2:

XS: Represents the X.Scale component. Interpreted as a <float>.
XO: Represents the X.Offset component. Interpreted as an <int>.
YS: Represents the Y.Scale component. Interpreted as a <float>.
YO: Represents the Y.Offset component. Interpreted as an <int>.

Example

<UDim2 name="Example">
	<XS>0.5</XS>
	<XO>-100</XO>
	<YS>0.5</YS>
	<YO>-100</YO>
</UDim2>

UniqueId

Child of: <Properties>
Canonical name: UniqueId
Property type: UniqueId
Contains: text

The value is the text content, formatted as a hexadecimal-encoded sequence of 16 bytes. Groups of bytes represent the components of the UniqueId:

Component	Bytes	Notes
Random	0 - 7	Interpreted as a big-endian, 64-bit signed integer.
Time	8 - 11	Interpreted as a big-endian, 32-bit unsigned integer.
Index	12 - 15	Interpreted as a big-endian, 32-bit unsigned integer.

Example

<UniqueId name="Example">44b188dace632b4702e9c68d004815fc</UniqueId>

Vector2

Child of: <Properties>
Canonical name: Vector2
Property type: Vector2
Contains: elements

Contains elements for each component of the Vector2:

X: Represents the X component. Interpreted as a <float>.
Y: Represents the Y component. Interpreted as a <float>.

Example

<Vector2 name="Example">
	<X>0</X>
	<Y>0</Y>
</Vector2>

Vector2int16

Child of: <Properties>
Canonical name: Vector2int16
Property type: Vector2int16
Contains: elements

Contains elements for each component of the Vector2int16:

X: Represents the X component. Interpreted as an <int>.
Y: Represents the Y component. Interpreted as an <int>.

Example

<Vector2int16 name="Example">
	<X>0</X>
	<Y>0</Y>
</Vector2int16>

Vector3

Child of: <Properties>
Canonical name: Vector3
Property type: Vector3
Contains: elements

Contains elements for each component of the Vector3:

X: Represents the X component. Interpreted as a <float>.
Y: Represents the Y component. Interpreted as a <float>.
Z: Represents the Z component. Interpreted as a <float>.

Example

<Vector3 name="Example">
	<X>0</X>
	<Y>0</Y>
	<Z>0</Z>
</Vector3>

Vector3int16

Child of: <Properties>
Canonical name: Vector3int16
Property type: Vector3int16
Contains: elements

Contains elements for each component of the Vector3int16:

X: Represents the X component. Interpreted as an <int>.
Y: Represents the Y component. Interpreted as an <int>.
Z: Represents the Z component. Interpreted as an <int>.

Example

<Vector3int16 name="Example">
	<X>0</X>
	<Y>0</Y>
	<Z>0</Z>
</Vector3int16>

bool

Child of: <Properties>
Canonical name: bool
Property type: bool
Contains: text

Text content is one of the following variations of true or false, representing the true or false state, respectively:

Case	True	False
Lowercase	`true`	`false`
Title case	`True`	`False`
Uppercase	`TRUE`	`FALSE`

For encoding, using Lowercase is recommended.

Example

<bool name="Example">true</bool>

<bool name="Example">false</bool>

double

Child of: <Properties>
Canonical name: double
Property type: double
Contains: text

The value is represented by the text content, formatted as floating-point number. A precision of at least 17 is required to properly represent a 64-bit floating point value, so this amount is recommended.

Example

<double name="Example">3.141592653589793116</double>

float

Child of: <Properties>
Canonical name: float
Property type: float
Contains: text

The value is represented by the text content, formatted as floating-point number. A precision of at least 9 is required to properly represent a 32-bit floating point value, so this amount is recommended.

Example

<float name="Example">3.14159274</float>

int

Child of: <Properties>
Canonical name: int
Property type: int
Contains: text

The value is represented by the text content, formatted as a 32-bit signed integer.

Example

<int name="Example">2147483647</int>

int64

Child of: <Properties>
Canonical name: int64
Property type: int64
Contains: text

The value is represented by the text content, formatted as a 64-bit signed integer.

Example

<int64 name="Example">4503599627370496</int64>

string

Child of: <Properties>
Canonical name: string
Property type: string
Contains: text

The value is the text content.

Example

<string name="Example">Hello, world!</string>

token

Child of: <Properties>
Canonical name: token
Property type: token
Contains: text

The value is text content, formatted as an integer representing the value of an enum item.

Example

<token name="Example">0</token>

Optional

Child of: <Properties>
Canonical name: Optional
Property type: Optional
Contains: elements

A tag with no elements indicates an empty optional. A tag with an element indicates an optional where the type is determined by the element. The following elements are known:

Element	Description
`<CFrame>`	Interpreted according to the CoordinateFrame type.

Example

<!-- Without value. -->
<OptionalCoordinateFrame name="Example"></OptionalCoordinateFrame>

<!-- With value. -->
<OptionalCoordinateFrame name="Example">
	<CFrame>
		<X>0</X>
		<Y>0</Y>
		<Z>0</Z>
		<R00>1</R00>
		<R01>0</R01>
		<R02>0</R02>
		<R10>0</R10>
		<R11>1</R11>
		<R12>0</R12>
		<R20>0</R20>
		<R21>0</R21>
		<R22>1</R22>
	</CFrame>
</OptionalCoordinateFrame>

Files

rbxlx.md

Latest commit

History

rbxlx.md

File metadata and controls

Roblox XML file format

Preliminary concepts

Format overview

Elements

<roblox>

Example

<Meta>

Example

<External>

Example

<Item>

Example

<Properties>

Example

<SharedStrings>

Example

<SharedString>

Example

Type elements

Axes

Example

BinaryString

Example

BrickColor

Example

Color3

Example

Color3uint8

Example

ColorSequence

Example

Content

Example

CoordinateFrame

Example

Faces

Example

Font

Example

NumberRange

Example

NumberSequence

Example

Ref

Example

PhysicalProperties

Example

ProtectedString

Example

Ray

Example

Rect2D

Example

SharedString

Example

UDim

Example

UDim2

Example

UniqueId

Example

Vector2

Example

Vector2int16

Example

Vector3

Example

Vector3int16

Example

bool

Example

double

Example

float

`<roblox>`

`<Meta>`

`<External>`

`<Item>`

`<Properties>`

`<SharedStrings>`

`<SharedString>`