rbxfile

package module
v0.0.0-...-6fc7a22 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 11, 2021 License: MIT Imports: 6 Imported by: 0

README

GoDoc

rbxfile

The rbxfile package handles the decoding, encoding, and manipulation of Roblox instance data structures.

This package can be used to manipulate Roblox instance trees outside of the Roblox client. Such data structures begin with a Root struct. A Root contains a list of child Instances, which in turn contain more child Instances, and so on, forming a tree of Instances. These Instances can be accessed and manipulated using an API similar to that of Roblox.

Each Instance also has a set of "properties". Each property has a specific value of a certain type. Every available type implements the Value interface, and is prefixed with "Value".

Root structures can be decoded from and encoded to various formats, including Roblox's native file formats. The two sub-packages bin and xml provide formats for Roblox's binary and XML formats. Root structures can also be encoded and decoded with the json package.

Besides decoding from a format, root structures can also be created manually. The best way to do this is through the declare sub-package, which provides an easy way to generate root structures.

The implementation of the binary file format is based largely on the RobloxFileSpec document, a reverse-engineered specification by Gregory Comer.

Other projects that involve decoding and encoding Roblox files:

Documentation

Overview

The rbxfile package handles the decoding, encoding, and manipulation of Roblox instance data structures.

This package can be used to manipulate Roblox instance trees outside of the Roblox client. Such data structures begin with a Root struct. A Root contains a list of child Instances, which in turn contain more child Instances, and so on, forming a tree of Instances. These Instances can be accessed and manipulated using an API similar to that of Roblox.

Each Instance also has a set of "properties". Each property has a specific value of a certain type. Every available type implements the Value interface, and is prefixed with "Value".

Root structures can be decoded from and encoded to various formats, including Roblox's native file formats. The two sub-packages "bin" and "xml" provide formats for Roblox's binary and XML formats. Root structures can also be encoded and decoded with the "json" package.

Besides decoding from a format, root structures can also be created manually. The best way to do this is through the "declare" sub-package, which provides an easy way to generate root structures.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GenerateReference 

func GenerateReference() string

GenerateReference generates a unique string that can be used as a reference to an Instance.

func IsEmptyReference 

func IsEmptyReference(ref string) bool

IsEmptyReference returns whether a reference string is considered "empty", and therefore does not have a referent.

Types

type Instance 

type Instance struct {
	// ClassName indicates the instance's type.
	ClassName string

	// Reference is a unique string used to refer to the instance from
	// elsewhere in the tree.
	Reference string

	// IsService indicates whether the instance should be treated as a
	// service.
	IsService bool

	// Properties is a map of properties of the instance. It maps the name of
	// the property to its current value.
	Properties map[string]Value

	// Children contains instances that are the children of the current
	// instance. If this field is set directly, then FixTree should be called
	// afterwards to ensure the correctness of the tree.
	Children []*Instance
	// contains filtered or unexported fields
}

Instance represents a single Roblox instance.

func NewInstance 

func NewInstance(className string, parent *Instance) *Instance

NewInstance creates a new Instance of a given class, and an optional parent.

func (*Instance) AddChild 

func (inst *Instance) AddChild(child *Instance) error

AddChild appends a child instance to the instance's list of children. If the child has a parent, it is first removed. The parent of the child is set to the instance. An error is returned if the instance is a descendant of the child, or if the child is the instance itself.

func (*Instance) AddChildAt 

func (inst *Instance) AddChildAt(index int, child *Instance) error

AddChildAt inserts a child instance into the instance's list of children at a given position. If the child has a parent, it is first removed. The parent of the child is set to the instance. If the index is outside the bounds of the list, then it is constrained. An error is returned if the instance is a descendant of the child, or if the child is the instance itself.

func (*Instance) Clone 

func (inst *Instance) Clone() *Instance

Clone returns a copy of the instance. Each property and all descendants are copied as well. Unlike Roblox's implementation, the Archivable property is ignored.

A copied reference within the tree is resolved so that it points to the corresponding copy of the original referent. Copied references that point to an instance which isn't being copied will still point to the same instance.

func (*Instance) FindFirstChild 

func (inst *Instance) FindFirstChild(name string, recursive bool) *Instance

FindFirstChild returns the first found child whose Name property matches the given name. Returns nil if no child was found. If recursive is true, then FindFirstChild will be called on descendants as well.

func (*Instance) FixTree 

func (inst *Instance) FixTree()

FixTree walks through the descendants of the instance tree top-down and ensures that the parental references are correct. Any descendants that cause a circular reference are removed and not traversed.

func (*Instance) Get 

func (inst *Instance) Get(property string) (value Value)

Get returns the value of a property in the instance. The value will be nil if the property is not defined.

func (*Instance) GetFullName 

func (inst *Instance) GetFullName() string

GetFullName returns the "full" name of the instance, which is the combined names of the instance and every ancestor, separated by a `.` character.

func (*Instance) IsAncestorOf 

func (inst *Instance) IsAncestorOf(descendant *Instance) bool

IsAncestorOf returns whether the instance is the ancestor of another instance.

func (*Instance) IsDescendantOf 

func (inst *Instance) IsDescendantOf(ancestor *Instance) bool

IsDescendantOf returns whether the instance is the descendant of another instance.

func (*Instance) Name 

func (inst *Instance) Name() string

Name returns the Name property of the instance, or an empty string if it is invalid or not defined.

func (*Instance) Parent 

func (inst *Instance) Parent() *Instance

Parent returns the parent of the instance. Can return nil if the instance has no parent.

func (*Instance) RemoveAll 

func (inst *Instance) RemoveAll()

RemoveAll remove every child from the instance. The parent of each child is set to nil.

func (*Instance) RemoveChild 

func (inst *Instance) RemoveChild(child *Instance) *Instance

RemoveChild removes a child instance from the instance's list of children. The parent of the child is set to nil. Returns the removed child.

func (*Instance) RemoveChildAt 

func (inst *Instance) RemoveChildAt(index int) *Instance

RemoveChildAt removes the child at a given position from the instance's list of children. The parent of the child is set to nil. If the index is outside the bounds of the list, then no children are removed. Returns the removed child.

func (*Instance) Set 

func (inst *Instance) Set(property string, value Value)

Set sets the value of a property in the instance. If value is nil, then the value will be deleted from the Properties map.

func (*Instance) SetName 

func (inst *Instance) SetName(name string)

SetName sets the Name property of the instance.

func (*Instance) SetParent 

func (inst *Instance) SetParent(parent *Instance) error

SetParent sets the parent of the instance, removing itself from the children of the old parent, and adding itself as a child of the new parent. The parent can be set to nil. An error is returned if the parent is a descendant of the instance, or if the parent is the instance itself. If the new parent is the same as the old parent, then the position of the instance in the parent's children is unchanged.

func (*Instance) String 

func (inst *Instance) String() string

String implements the fmt.Stringer interface by returning the Name of the instance, or the ClassName if Name isn't defined.

type PropRef 

type PropRef struct {
	Instance  *Instance
	Property  string
	Reference string
}

PropRef specifies the property of an instance that is a reference, which is to be resolved into its referent at a later time.

type References 

type References map[string]*Instance

References is a mapping of reference strings to Instances.

func (References) Get 

func (refs References) Get(instance *Instance) (ref string)

Get gets a reference from an Instance, using References to check for duplicates. If the instance's reference already exists in References, then a new reference is generated and applied to the instance. The instance's reference is then added to References.

func (References) Resolve 

func (refs References) Resolve(propRef PropRef) bool

Resolve resolves a PropRef and sets the value of the property using References. If the referent does not exist, and the reference is not empty, then false is returned. True is returned otherwise.

type Root 

type Root struct {
	// Instances contains root instances contained in the tree.
	Instances []*Instance

	// Metadata contains metadata about the tree.
	Metadata map[string]string
}

Root represents the root of an instance tree. Root is not itself an instance, but a container for multiple root instances.

func NewRoot 

func NewRoot() *Root

NewRoot returns a new initialized Root.

func (*Root) Copy 

func (root *Root) Copy() *Root

Copy creates a copy of the root and its contents.

A copied reference within the tree is resolved so that it points to the corresponding copy of the original referent. Copied references that point to an instance which isn't being copied will still point to the same instance.

type Type 

type Type byte

Type represents a Roblox type. 

const (
	TypeInvalid Type = iota
	TypeString
	TypeBinaryString
	TypeProtectedString
	TypeContent
	TypeBool
	TypeInt
	TypeFloat
	TypeDouble
	TypeUDim
	TypeUDim2
	TypeRay
	TypeFaces
	TypeAxes
	TypeBrickColor
	TypeColor3
	TypeVector2
	TypeVector3
	TypeCFrame
	TypeToken
	TypeReference
	TypeVector3int16
	TypeVector2int16
	TypeNumberSequence
	TypeColorSequence
	TypeNumberRange
	TypeRect2D
	TypePhysicalProperties
	TypeColor3uint8
	TypeInt64
	TypeSharedString
)

func TypeFromAPIString 

func TypeFromAPIString(api rbxapi.Root, s string) Type

TypeFromAPIString returns a Type from a string, using a rbxapi.Root if needed. Valid strings are compatible with type strings typically found in a rbxapi.Root.

func TypeFromString 

func TypeFromString(s string) Type

TypeFromString returns a Type from its string representation. TypeInvalid is returned if the string does not represent an existing Type.

func (Type) String 

func (t Type) String() string

String returns a string representation of the type. If the type is not valid, then the returned value will be "Invalid".

type Value 

type Value interface {
	// Type returns an identifier indicating the type.
	Type() Type

	// String returns a string representation of the current value.
	String() string

	// Copy returns a copy of the value, which can be safely modified.
	Copy() Value
}

Value holds a value of a particular Type.

func NewValue 

func NewValue(typ Type) Value

NewValue returns new Value of the given Type. The initial value will not necessarily be the zero for the type. If the given type is invalid, then a nil value is returned.

type ValueAxes 

type ValueAxes struct {
	X, Y, Z bool
}

func (ValueAxes) Copy 

func (t ValueAxes) Copy() Value

func (ValueAxes) String 

func (t ValueAxes) String() string

func (ValueAxes) Type 

func (ValueAxes) Type() Type

type ValueBinaryString 

type ValueBinaryString []byte

func (ValueBinaryString) Copy 

func (t ValueBinaryString) Copy() Value

func (ValueBinaryString) String 

func (t ValueBinaryString) String() string

func (ValueBinaryString) Type 

func (ValueBinaryString) Type() Type

type ValueBool 

type ValueBool bool

func (ValueBool) Copy 

func (t ValueBool) Copy() Value

func (ValueBool) String 

func (t ValueBool) String() string

func (ValueBool) Type 

func (ValueBool) Type() Type

type ValueBrickColor 

type ValueBrickColor uint32

func (ValueBrickColor) Copy 

func (t ValueBrickColor) Copy() Value

func (ValueBrickColor) String 

func (t ValueBrickColor) String() string

func (ValueBrickColor) Type 

func (ValueBrickColor) Type() Type

type ValueCFrame 

type ValueCFrame struct {
	Position ValueVector3
	Rotation [9]float32
}

func (ValueCFrame) Copy 

func (t ValueCFrame) Copy() Value

func (ValueCFrame) String 

func (t ValueCFrame) String() string

func (ValueCFrame) Type 

func (ValueCFrame) Type() Type

type ValueColor3 

type ValueColor3 struct {
	R, G, B float32
}

func (ValueColor3) Copy 

func (t ValueColor3) Copy() Value

func (ValueColor3) String 

func (t ValueColor3) String() string

func (ValueColor3) Type 

func (ValueColor3) Type() Type

type ValueColor3uint8 

type ValueColor3uint8 struct {
	R, G, B byte
}

func (ValueColor3uint8) Copy 

func (t ValueColor3uint8) Copy() Value

func (ValueColor3uint8) String 

func (t ValueColor3uint8) String() string

func (ValueColor3uint8) Type 

func (ValueColor3uint8) Type() Type

type ValueColorSequence 

type ValueColorSequence []ValueColorSequenceKeypoint

func (ValueColorSequence) Copy 

func (t ValueColorSequence) Copy() Value

func (ValueColorSequence) String 

func (t ValueColorSequence) String() string

func (ValueColorSequence) Type 

func (ValueColorSequence) Type() Type

type ValueColorSequenceKeypoint 

type ValueColorSequenceKeypoint struct {
	Time     float32
	Value    ValueColor3
	Envelope float32
}

func (ValueColorSequenceKeypoint) String 

func (t ValueColorSequenceKeypoint) String() string

type ValueContent 

type ValueContent []byte

func (ValueContent) Copy 

func (t ValueContent) Copy() Value

func (ValueContent) String 

func (t ValueContent) String() string

func (ValueContent) Type 

func (ValueContent) Type() Type

type ValueDouble 

type ValueDouble float64

func (ValueDouble) Copy 

func (t ValueDouble) Copy() Value

func (ValueDouble) String 

func (t ValueDouble) String() string

func (ValueDouble) Type 

func (ValueDouble) Type() Type

type ValueFaces 

type ValueFaces struct {
	Right, Top, Back, Left, Bottom, Front bool
}

func (ValueFaces) Copy 

func (t ValueFaces) Copy() Value

func (ValueFaces) String 

func (t ValueFaces) String() string

func (ValueFaces) Type 

func (ValueFaces) Type() Type

type ValueFloat 

type ValueFloat float32

func (ValueFloat) Copy 

func (t ValueFloat) Copy() Value

func (ValueFloat) String 

func (t ValueFloat) String() string

func (ValueFloat) Type 

func (ValueFloat) Type() Type

type ValueInt 

type ValueInt int32

func (ValueInt) Copy 

func (t ValueInt) Copy() Value

func (ValueInt) String 

func (t ValueInt) String() string

func (ValueInt) Type 

func (ValueInt) Type() Type

type ValueInt64 

type ValueInt64 int64

func (ValueInt64) Copy 

func (t ValueInt64) Copy() Value

func (ValueInt64) String 

func (t ValueInt64) String() string

func (ValueInt64) Type 

func (ValueInt64) Type() Type

type ValueNumberRange 

type ValueNumberRange struct {
	Min, Max float32
}

func (ValueNumberRange) Copy 

func (t ValueNumberRange) Copy() Value

func (ValueNumberRange) String 

func (t ValueNumberRange) String() string

func (ValueNumberRange) Type 

func (ValueNumberRange) Type() Type

type ValueNumberSequence 

type ValueNumberSequence []ValueNumberSequenceKeypoint

func (ValueNumberSequence) Copy 

func (t ValueNumberSequence) Copy() Value

func (ValueNumberSequence) String 

func (t ValueNumberSequence) String() string

func (ValueNumberSequence) Type 

func (ValueNumberSequence) Type() Type

type ValueNumberSequenceKeypoint 

type ValueNumberSequenceKeypoint struct {
	Time, Value, Envelope float32
}

func (ValueNumberSequenceKeypoint) String 

func (t ValueNumberSequenceKeypoint) String() string

type ValuePhysicalProperties 

type ValuePhysicalProperties struct {
	CustomPhysics    bool
	Density          float32
	Friction         float32
	Elasticity       float32
	FrictionWeight   float32
	ElasticityWeight float32
}

func (ValuePhysicalProperties) Copy 

func (t ValuePhysicalProperties) Copy() Value

func (ValuePhysicalProperties) String 

func (t ValuePhysicalProperties) String() string

func (ValuePhysicalProperties) Type 

func (ValuePhysicalProperties) Type() Type

type ValueProtectedString 

type ValueProtectedString []byte

func (ValueProtectedString) Copy 

func (t ValueProtectedString) Copy() Value

func (ValueProtectedString) String 

func (t ValueProtectedString) String() string

func (ValueProtectedString) Type 

func (ValueProtectedString) Type() Type

type ValueRay 

type ValueRay struct {
	Origin, Direction ValueVector3
}

func (ValueRay) Copy 

func (t ValueRay) Copy() Value

func (ValueRay) String 

func (t ValueRay) String() string

func (ValueRay) Type 

func (ValueRay) Type() Type

type ValueRect2D 

type ValueRect2D struct {
	Min, Max ValueVector2
}

func (ValueRect2D) Copy 

func (t ValueRect2D) Copy() Value

func (ValueRect2D) String 

func (t ValueRect2D) String() string

func (ValueRect2D) Type 

func (ValueRect2D) Type() Type

type ValueReference 

type ValueReference struct {
	*Instance
}

func (ValueReference) Copy 

func (t ValueReference) Copy() Value

func (ValueReference) String 

func (t ValueReference) String() string

func (ValueReference) Type 

func (ValueReference) Type() Type

type ValueSharedString 

type ValueSharedString []byte

func (ValueSharedString) Copy 

func (t ValueSharedString) Copy() Value

func (ValueSharedString) String 

func (t ValueSharedString) String() string

func (ValueSharedString) Type 

func (ValueSharedString) Type() Type

type ValueString 

type ValueString []byte

func (ValueString) Copy 

func (t ValueString) Copy() Value

func (ValueString) String 

func (t ValueString) String() string

func (ValueString) Type 

func (ValueString) Type() Type

type ValueToken 

type ValueToken uint32

func (ValueToken) Copy 

func (t ValueToken) Copy() Value

func (ValueToken) String 

func (t ValueToken) String() string

func (ValueToken) Type 

func (ValueToken) Type() Type

type ValueUDim 

type ValueUDim struct {
	Scale  float32
	Offset int32
}

func (ValueUDim) Copy 

func (t ValueUDim) Copy() Value

func (ValueUDim) String 

func (t ValueUDim) String() string

func (ValueUDim) Type 

func (ValueUDim) Type() Type

type ValueUDim2 

type ValueUDim2 struct {
	X, Y ValueUDim
}

func (ValueUDim2) Copy 

func (t ValueUDim2) Copy() Value

func (ValueUDim2) String 

func (t ValueUDim2) String() string

func (ValueUDim2) Type 

func (ValueUDim2) Type() Type

type ValueVector2 

type ValueVector2 struct {
	X, Y float32
}

func (ValueVector2) Copy 

func (t ValueVector2) Copy() Value

func (ValueVector2) String 

func (t ValueVector2) String() string

func (ValueVector2) Type 

func (ValueVector2) Type() Type

type ValueVector2int16 

type ValueVector2int16 struct {
	X, Y int16
}

func (ValueVector2int16) Copy 

func (t ValueVector2int16) Copy() Value

func (ValueVector2int16) String 

func (t ValueVector2int16) String() string

func (ValueVector2int16) Type 

func (ValueVector2int16) Type() Type

type ValueVector3 

type ValueVector3 struct {
	X, Y, Z float32
}

func (ValueVector3) Copy 

func (t ValueVector3) Copy() Value

func (ValueVector3) String 

func (t ValueVector3) String() string

func (ValueVector3) Type 

func (ValueVector3) Type() Type

type ValueVector3int16 

type ValueVector3int16 struct {
	X, Y, Z int16
}

func (ValueVector3int16) Copy 

func (t ValueVector3int16) Copy() Value

func (ValueVector3int16) String 

func (t ValueVector3int16) String() string

func (ValueVector3int16) Type 

func (ValueVector3int16) Type() Type

Source Files

View all Source files

Directories

Path Synopsis
Package bin implements a decoder and encoder for Roblox's binary file format.
 Package bin implements a decoder and encoder for Roblox's binary file format.
The declare package is used to generate rbxfile structures in a declarative style.
 The declare package is used to generate rbxfile structures in a declarative style.
The json package is used to encode and decode rbxfile objects to the JSON format.
 The json package is used to encode and decode rbxfile objects to the JSON format.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.