Crate guido_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 no useful configuration yet, but there are methods that accept DecodeOptions and EncodeOptions that will be useful when it does.

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.