Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Give BinaryStrings their own documentation #338

Merged
merged 1 commit into from
Aug 3, 2023
Merged

Give BinaryStrings their own documentation #338

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 75 additions & 0 deletions docs/binary-strings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# BinaryString blobs

Certain properties (such as `Instance.Tags`) are serialized as blobs of binary data. These blobs are represented by Roblox as `BinaryString` values. The format used for a given property is entirely custom and must be known to read and write values to that property.

This document serves as unofficial documentation for potential `BinaryString` values, describing their structure.

## Encoding

Values of this type are encoded using the [`BinaryString`](xml.md#binarystring) data type in the [XML](xml.md) format. In the [binary](binary.md) file format, they are encoded as [`String`](binary.md#string) values.

## Blobs

The following is a list of `BinaryString` blobs and their formatting. For clarity, the name of the property using a blob is used as the header name, and the class it is a part of is listed beneath the header.

When a format is sufficiently complex, it may be stored in its own document for clarity.

### AttributeSerialized
**Used By:** `Instance.AttributesSerialize`

This blob is used to serialize [attributes][Attributes]. Due to the complexity of the format, a specification is located [here](attributes.md).

[Attributes]: https://create.roblox.com/docs/studio/instance-attributes

### MaterialColors
**Used By:** `Terrain.MaterialColors`

This blob is used to serialize [`MaterialColors`][MaterialColors].

`MaterialColors` is stored internally as `69` bytes, which is read a sequence of 23 three-byte arrays. Each of these arrays represents the red, green, and blue components of the color of a specific variant of the [`Material`][Material] enum.

These values are in a fixed order. The following table describes what byte (from the beginning of the blob) corresponds to what component of what `Material` enum value.

| `RR` | `GG` | `BB` | Material Variant |
|:----:|:----:|:----:|:-----------------:|
| `00` | `01` | `02` | `None` (reserved) |
| `03` | `04` | `05` | `None` (reserved) |
| `06` | `07` | `08` | `Grass` |
| `09` | `10` | `11` | `Slate` |
| `12` | `13` | `14` | `Concrete` |
| `15` | `16` | `17` | `Brick` |
| `18` | `19` | `20` | `Sand` |
| `21` | `22` | `23` | `WoodPlanks` |
| `24` | `25` | `26` | `Rock` |
| `27` | `28` | `29` | `Glacier` |
| `30` | `31` | `32` | `Snow` |
| `33` | `34` | `35` | `Sandstone` |
| `36` | `37` | `38` | `Mud` |
| `39` | `40` | `41` | `Basalt` |
| `42` | `43` | `44` | `Ground` |
| `45` | `46` | `47` | `CrackedLava` |
| `48` | `49` | `50` | `Asphalt` |
| `51` | `52` | `53` | `Cobblestone` |
| `54` | `55` | `56` | `Ice` |
| `57` | `58` | `59` | `LeafyGrass` |
| `60` | `61` | `62` | `Salt` |
| `63` | `64` | `65` | `Limestone` |
| `66` | `67` | `68` | `Pavement` |

The first two rows appear to be unused at this moment and should always be written as `00 00 00` to preserve compatibility.

[MaterialColors]: https://create.roblox.com/docs/reference/engine/classes/Terrain#MaterialColors
[Material]: https://create.roblox.com/docs/reference/engine/enums/Material

### Tags
**Used By:** `Instance.Tags`

This blob is used to serialize [`CollectionService`][CollectionService] tags for an `Instance`.

`Tags` is stored as an array of bytes representing every tag on an `Instance`. The array is delineated using `00`. Otherwise, the literal bytes of the tag are written.

As an example, an `Instance` that had the tags `Hello`, `from`, and `Rojo` would have them serialized as follows:

`48 65 6C 6C 6F 00 66 72 6F 6D 00 52 6F 6A 6F`

[CollectionService]: https://create.roblox.com/docs/reference/engine/classes/CollectionService
4 changes: 2 additions & 2 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@ This is the home for rbx-dom, a collection of libraries for working with the Rob
## Unofficial Specifications
We maintain high quality documentation for Roblox's formats. This documentation is sourced entirely from the community and contains lessons learned from implementing these formats as part of rbx-dom.

* [Attributes Format](attributes.md)
* [Binary Model Format](binary.md)
* [DOM Data Model](dom.md) (stub)
* [XML Model Format](xml.md)
* [BinaryString blob formats](binary-strings.md)
* [DOM Data Model](dom.md) (stub)

## Maintenance

Expand Down