Crate rbx_xml

Configurable Roblox XML place/model format (rbxmx and rbxlx) serializer and deserializer.

rbx_xml uses the rbx_dom_weak crate as its DOM.

This crate implements most of the format and is driven by an up-to-date reflection database.

Deserialization

To decode a place or model, use a method like from_reader_default if you’re reading from a file, or from_str_default if you already have a string. These methods also have variants like from_str that let you pass in custom options.

use rbx_dom_weak::types::Variant;

let model_file = r#"
<roblox version="4">
    <Item class="NumberValue" referent="RBX3B3D9D3DB43D4E6793B190B081E0A886">
        <Properties>
            <string name="Name">My NumberValue</string>
            <double name="Value">12345</double>
        </Properties>
    </Item>
</roblox>
"#;

let model = rbx_xml::from_str_default(model_file)?;

let data_model = model.root();
let number_value_ref = data_model.children()[0];
let number_value = model.get_by_ref(number_value_ref).unwrap();

assert_eq!(
    number_value.properties.get("Value"),
    Some(&Variant::Float64(12345.0)),
);

If you’re decoding from a file, you’ll want to do your own I/O buffering, like with BufReader:

use std::{
    io::BufReader,
    fs::File,
};

let file = BufReader::new(File::open("place.rbxlx")?);
let place = rbx_xml::from_reader_default(file)?;

Note that the WeakDom instance returned by the rbx_xml decode methods will have a root instance with the class name DataModel. This is great for deserializing a place, but kind of strange for deserializing a model.

Because models can have multiple instances at the top level, rbx_xml can’t just return an WeakDom with your single instance at the top. Instead, the crate instead always creates a top-level DataModel instance which is pretty close to free.

Serialization

To serialize an existing WeakDom instance, use methods like to_writer_default or to_writer.

For example, to re-save the place file we loaded above:

use std::{
    io::BufWriter,
    fs::File,
};
use rbx_dom_weak::{WeakDom, InstanceBuilder};

let place = WeakDom::new(InstanceBuilder::new("DataModel"));

// A Roblox place file contains all of its top-level instances.
let top_level_refs = place.root().children();

// Just like when reading a place file, we should buffer our I/O.
let file = BufWriter::new(File::create("place-2.rbxlx")?);

rbx_xml::to_writer_default(file, &place, top_level_refs)?;

Configuration

rbx_xml exposes a few configuration options at the moment in the form of DecodeOptions and EncodeOptions. For information on the configuration, see the documentation for those structs.

The non-default reader and writer functions accept these as their options argument.

Structs

• DecodeError
  An error that can occur when deserializing an XML-format model or place.
• DecodeOptions
  Options available for deserializing an XML-format model or place.
• EncodeError
  An error that can occur when serializing an XML-format model or place.
• EncodeOptions
  Options available for serializing an XML-format model or place.

Enums

• DecodePropertyBehavior
  Describes the strategy that rbx_xml should use when deserializing properties.
• EncodePropertyBehavior
  Describes the strategy that rbx_xml should use when serializing properties.

Functions

• from_reader
  Decodes an XML-format model or place from something that implements the std::io::Read trait.
• from_reader_default
  Decodes an XML-format model or place from something that implements the std::io::Read trait using the default decoder options.
• from_str
  Decodes an XML-format model or place from a string.
• from_str_default
  Decodes an XML-format model or place from a string using the default decoder options.
• to_writer
  Serializes a subset of the given tree to an XML format model or place, writing to something that implements the std::io::Write trait.
• to_writer_default
  Serializes a subset of the given tree to an XML format model or place, writing to something that implements the std::io::Write trait using the default encoder options.