rbxl

README

rbxfile/rbxl

Package rbxl implements a decoder and encoder for Roblox's binary file format.

This package registers the formats "rbxl" and "rbxm" to the rbxfile package.

The easiest way to decode and encode files is through the functions DeserializePlace, SerializePlace, DeserializeModel, and SerializeModel. These decode and encode directly between byte streams and Root structures specified by the rbxfile package. For most purposes, this is all that is required to read and write Roblox binary files. Further documentation gives an overview of how the package works internally.

Overview

A Serializer is used to transform data from byte streams to Root structures and back. A serializer specifies a decoder and encoder. Both a decoder and encoder combined is referred to as a "codec".

Codecs transform data between a generic rbxfile.Root structure, and this package's "format model" structure. Custom codecs can be implemented. For example, you might wish to decode files normally, but encode them in an alternative way:

serializer := NewSerializer(nil, CustomEncoder)

Custom codecs can be used with a Serializer by implementing the Decoder and Encoder interfaces. Both do not need to be implemented. In the example above, passing nil as an argument causes the serializer to use the default "RobloxCodec", which implements both a default decoder and encoder. This codec attempts to emulate how Roblox decodes and encodes its files.

A FormatModel is the representation of the file format itself, rather than the data it contains. The FormatModel is like a buffer between the byte stream and the Root structure. FormatModels can be encoded (and rarely, decoded) to and from Root structures in multiple ways, which is specified by codecs. However, there is only one way to encode and decode to and from a byte stream, which is handled by the FormatModel.

Documentation

Overview

Package rbxl implements a decoder and encoder for Roblox's binary file format.

Index

• Variables
• type ChunkError
  • func (err ChunkError) Error() string
  • func (err ChunkError) Unwrap() error
• type CodecError
  • func (err CodecError) Error() string
  • func (err CodecError) Unwrap() error
• type DataError
  • func (err DataError) Error() string
  • func (err DataError) Unwrap() error
• type Decoder
  • func (d Decoder) Decode(r io.Reader) (root *rbxfile.Root, warn, err error)
  • func (d Decoder) Decompress(w io.Writer, r io.Reader) (warn, err error)
  • func (d Decoder) Dump(w io.Writer, r io.Reader) (warn, err error)
• type DecoderStats
• type Encoder
  • func (e Encoder) Encode(w io.Writer, root *rbxfile.Root) (warn, err error)
• type Mode
• type ValueError
  • func (err ValueError) Error() string
  • func (err ValueError) Unwrap() error
• type XMLError
  • func (err XMLError) Error() string
  • func (err XMLError) Unwrap() error

Variables

var ErrXML = errors.New("unexpected XML format")

ErrXML indicates the unexpected detection of the legacy XML format.

Types

type ChunkError

type ChunkError struct {
	// Index is the position of the chunk within the file.
	Index int
	// Sig is the signature of the chunk.
	Sig sig

	Cause error
}

ChunkError indicates an error that occurred within a chunk.

func (ChunkError) Error

func (err ChunkError) Error() string

func (ChunkError) Unwrap

func (err ChunkError) Unwrap() error

type CodecError

type CodecError struct {
	Cause error
}

CodecError wraps an error that occurred while encoding or decoding a binary format model.

func (CodecError) Error

func (err CodecError) Error() string

func (CodecError) Unwrap

func (err CodecError) Unwrap() error

type DataError

type DataError struct {
	// Offset is the byte offset where the error occurred.
	Offset int64

	Cause error
}

DataError wraps an error that occurred while encoding or decoding byte data.

func (DataError) Error

func (err DataError) Error() string

func (DataError) Unwrap

func (err DataError) Unwrap() error

type Decoder

type Decoder struct {
	// Mode indicates which type of format is decoded.
	Mode Mode

	// If NoXML is true, then the decoder will not attempt to decode the legacy
	// XML format for backward compatibility.
	NoXML bool

	// If not nil, stats will be set while decoding.
	Stats *DecoderStats
}

Decoder decodes a stream of bytes into an rbxfile.Root.

func (Decoder) Decode

func (d Decoder) Decode(r io.Reader) (root *rbxfile.Root, warn, err error)

Decode reads data from r and decodes it into root according to the rbxl format.

func (Decoder) Decompress

func (d Decoder) Decompress(w io.Writer, r io.Reader) (warn, err error)

Decompress reencodes the compressed chunks of the binary format as uncompressed. The format is decoded from r, then encoded to w.

Returns ErrXML if the the data is in the legacy XML format.

func (Decoder) Dump

func (d Decoder) Dump(w io.Writer, r io.Reader) (warn, err error)

Dump writes to w a readable representation of the binary format decoded from r.

Returns ErrXML if the the data is in the legacy XML format.

type DecoderStats

type DecoderStats struct {
	XML           bool           // Whether the format is XML.
	Version       uint16         // Version of the format.
	ClassCount    uint32         // Number of classes reported by the header.
	InstanceCount uint32         // Number of instances reported by the header.
	Chunks        int            // Total number of chunks.
	ChunkTypes    map[string]int // Number of chunks per signature.
}

DecoderStats contains statistics generated while decoding the format.

type Encoder

type Encoder struct {
	// Mode indicates which type of format is encoded.
	Mode Mode

	// Uncompressed sets whether compression is forcibly disabled for all
	// chunks.
	Uncompressed bool
}

Encoder encodes a rbxfile.Root into a stream of bytes.

func (Encoder) Encode

func (e Encoder) Encode(w io.Writer, root *rbxfile.Root) (warn, err error)

Encode formats root according to the rbxl format, and writers it to w.

type Mode

type Mode uint8

Mode indicates how the codec formats data.

const (
	Place Mode = iota // Data is handled as a Roblox place (RBXL) file.
	Model             // Data is handled as a Roblox model (RBXM) file.
)

type ValueError

type ValueError struct {
	Type byte

	Cause error
}

ValueError is an error that is produced by a Value of a certain Type.

func (ValueError) Error

func (err ValueError) Error() string

func (ValueError) Unwrap

func (err ValueError) Unwrap() error

type XMLError

type XMLError struct {
	Cause error
}

XMLError wraps an error that occurred while parsing the legacy XML format.

func (XMLError) Error

func (err XMLError) Error() string

func (XMLError) Unwrap

func (err XMLError) Unwrap() error