Compatibility Concerns
To streamline usage of rbx-dom, certain aspects of the file types are either ignored or intentionally changed. In the event that one of these changes causes problems in the future, this document maintains a list of potential compatibility issues we may run into. If relevant, an explanation for why a decision was made and/or how to fix a compatibility problem are included as well.
Broadly, these concerns be split into three categories:
This document does not consider new features by Roblox to be a compatibility concern unless they are not backwards compatible or the decision is made to not support them for whatever reason. However, if a significant feature is missing for an extended period of time, its addition to this document may be considered.
DOM-Wide
Issues of this category would impact the usage of rbx-dom as a whole if Roblox makes a breaking change.
Property serialization changes
It is possible the serialization of properties may change between versions of the reflection database. This frequently occurs when Roblox deprecates a legacy feature and there is an obvious replacement available. However, because we cannot anticipate Roblox’s features, a change in the serialization may result in that property being dropped by rbx-dom because it believes it should not serialize it anymore.
This is generally as simple as patching the database but it may be more involved, and will unfortunately have to be handled on a case-by-case basis.
Unsupported Property Types
In the XML format, QDir and QFont properties are deliberately not supported because they only occur in Settings files generated by Roblox. In the binary format, Bytecode properties are deliberately not supported because loading unsigned bytecode is extremely dangerous and Roblox does not support it in user files.
Properties of these types will not raise parsing errors if encountered, but if Roblox ever decides to use them for user-facing files, support would need to be added.
XML
Issues of this category would impact the usage of rbx-xml if Roblox makes a breaking change.
BrickColor Properties
Due to how Roblox and rbx-xml serialize BrickColor properties, they may be deserialized as Int32 values by rbx-xml. This will happen when no reflection database is used and may happen when an outdated one is used.
To fix this problem, an up-to-date reflection database should be used. The rbx-xml deserializer must know that the correct type of a property is BrickColor to correctly deserialize it, and a database will contain the types of every property. In the event that using an updated database does not work though, a patch may need to be made that changes the type of the property to BrickColor.
Strings that contain ]]>
String properties that contain leading or trailing whitespace characters are serialized using CDATA to preserve the whitespace. However, the sequence ]]> is used to end CDATA sections. This means that when a string property contains leading or trailing whitespace, and also contains ]]>, the property will serialize incorrectly.
This is an easy problem to fix but due to the performance concerns of traversing every string property serialized for the sequence ]]>, the current implementation does not. It’s unlikely that a string will both have whitespace padding and contain the sequence ]]> though, so it’s considered low priority to fix.
Empty Property Elements
Occasionally, Roblox writes new properties or data types with an empty element rather than with a default ‘filled in’ value. This will result in a parsing error for rbx-xml even if the type and property are both known.
While in a perfect world rbx-xml would be as flexible as Roblox’s own parser, it is not. To fix issues of this sort, the implementation of the datatype in rbx-xml must be modified to be more forgiving.
Referents
When assigning Referent values to an Instance, rbx-xml uses sequential integers rather than the UUID that Roblox uses. These integers are deterministic, so they result in significantly smaller diffs when using source control.
This is considered unlikely to ever be an issue, but it is noted for completion.
Binary
Issues of this category would impact the usage of rbx-binary if Roblox makes a breaking change.
Default Property Values
When generating the reflection database for properties, rbx-dom also stores the default value for that property written by Roblox Studio. Sometimes though, files can be saved with these properties before rbx-dom know about them. To avoid breaking or losing data, properties where the type is known are deserialized and may still be serialized. Due to how the binary format works though, if a single Instance of a class has a property set, all Instances of that class must also have it set. If the default value of a property is not known, a default for the given datatype is used instead for compatibility.
If the default for a data type is used, it may be not be the correct default for the property. This is generally fine but in extreme cases it may cause significant functionality problems. As a real world example, the default value for Float64 values is 0.0 but the default for Model.Scale at the time of writing is 1.0. This resulted in files that predated this property having all Models in them be scaled to down nothing.
The easiest way to fix and avoid this issue is to update the reflection database and patch it where appropriate. Some attention should also be paid to beta features, to ensure they don’t add anything that will need to be patched later.
INST Chunk Format
The binary format has two distinct formats for INST chunks. Internally we refer to these as the normal and service formats. When the format is set to service, we simply write an array of 1 values to the end of the chunk to ensure compatibility (see issue #11).
This is technically wrong. The ‘proper’ way to do this is to write 1 if the respective Instance is parented to the file’s root and 0 if it is not. However, this nuance has proven unnecessary because we simply don’t generate INST chunks with this format unless the class is a service, in which case there is only one per file.
This is not expected to cause any compatibility issues in the future, but it is documented for posterity.
Malformed PROP Chunks
Roblox has serialized invalid PROP chunks in the past when introducing new property values. Most notably, this occured when the Optional type was first introduced in the form of OptionalCoordinateFrame.
This incompatibility cannot be anticipated but some flexibility can be coded into deserialization to prevent this from causing serious error.
Arbitrary Changes
Despite there being a version field present in the format’s header, Roblox has made breaking changes without incrementing it in the past. Most notably, this includes support for zstd compression in chunks, which has no indication at all beyond the first 4 bytes of a chunk’s body being a specific magic number.
While it is not strictly speaking a ‘compatibility’ issue for Roblox to make an arbitrary change to the binary file format without incrementing the version, it is documented here because in the event it happens, there is no way to anticipate it and the change will be breaking until it is implemented and a new release of rbx-binary is made. This entry exists primarily as an acknowledgement that Roblox may do this without warning and rbx-binary must be reactive.