rbxmk is a tool for modifying, manipulating, building, and compiling Roblox files. Be it quick, one-off transformations, or the main driver behind your project, rbxmk is a versatile toolbelt for aiding the development of games, plugins, models, modules, and so on.
Download
The latest released version of rbxmk is v0.9.1, and is available for a number of platforms:
Windows | Mac | Linux |
---|---|---|
Windows 64-bit | macOS | Linux 64-bit |
Windows 32-bit | Linux 32-bit |
See the Release page for more information on the latest version.
The rbxmk repository contains the latest unreleased version. Instructions for compiling and installing manually are available there.
rbxmk is fully featured, but thorough testing of all features is still a work in progress. Please practice redundancy and use backups to reduce the risk of data loss. Be sure to report issues as you encounter them!
Changelog
v0.9.1
Highlights:
- Add support for
.luau
extension.- Add
luau
format. - Add
client.luau
format. - Add
localscript.luau
format. - Add
modulescript.luau
format. - Add
script.luau
format. - Add
server.luau
format.
- Add
- When a descriptor is set while encoding or decoding an instance, the service status is determined by the Service tag from instance’s class descriptor instead of the instance’s IsService field.
- This improves conversion from XML Roblox formats to binary Roblox formats.
- Add support for Optional types.
- If a descriptor is set, optional properties are handled transparently by accepting either nil (for None), or a value of the optional’s type (for Some).
- Add types.none to create an empty Optional exprim.
- Add types.some to create an Optional exprim that contains a value.
- Currently, this only affects the “Model.WorldPivotData” property, which is an optional CFrame.
- Add support for UniqueId type.
- Improve interface of the doc command.
- Frag mode is the default. List mode is enabled with the
--list
flag.
- Frag mode is the default. List mode is enabled with the
- Add RootDesc.Copy method.
Fixes:
- Fix descriptor IsA checks failing when superclass matches current class.
- Fix encoding of PhysicalProperties type in rbxl format.
- Fix options not working for the rbx formats.
- Fix SetAttribute throwing an error when setting an attribute to nil.
- Fix SetAttributes pulling wrong argument for dictionary.
- Fix nondeterministic order of encoded SharedStrings in rbxl format.
Internal:
- Switch to cobra for handling CLI.
- When the program is executed from a GUI, a message is displayed indicating that it is a command-line tool.
- Adds
completion
command for generating autocompletion scripts for various shells.
See a comparison with the previous version for a thorough list of changes.
The Documentation page provides a complete reference for this version of rbxmk.
Usage
rbxmk uses Lua scripts to produce and retrieve data, transform it, and send it off to a variety of sources, including the file system, assets on the Roblox website, general HTTP resources, and even the clipboard.
This section will provide an overview of the features of rbxmk. The Documentation pages provide a complete reference on how rbxmk is used.
Commands
rbxmk is a program with a command-line interface, consisting of a number of sub-commands:
Command | Description |
---|---|
run |
Execute a script. |
i |
Enter interactive mode. |
download-asset |
Download an asset. |
upload-asset |
Upload an asset. |
dump |
Dump the script API. |
help |
Display help. |
run is the primary command, which is used to run Lua scripts.
rbxmk run file.lua
Arguments can be passed to the script, received within the script from the ...
operator.
rbxmk run file.lua hello 3.14159 true
The i command is like the run command, but starts an interactive session similar to lua -i
, where lines of Lua code can be written and evaluated directly.
The download-asset and upload-asset commands provide shortcuts for quickly downloading or updating assets on the Roblox website. The same actions can be performed within rbxmk scripts as well.
The dump command produces machine-readable descriptions of rbxmk’s Lua environment, including a general JSON format, as well as the selene TOML format.
The help command provides a description for any command. In addition to the documentation, this can be used to learn more about a particular command.
Lua environment
The environment of rbxmk script is meant to emulate Roblox. No Luau-specific features are available, but the libraries and variables included in the environment closely match those of Roblox. There are of course additional libraries exclusive to rbxmk.
Instances
Instances are one of the main types of data that rbxmk deals with. As in Roblox, they can be created from scratch:
local brick = Instance.new("Part")
brick.Name = "Brick"
brick.BrickColor = BrickColor.Red()
brick.Anchored = true
Instances include many of the basic methods, such as GetChildren, FindFirstChild, and Destroy, as well as the common properies ClassName, Name, and Parent.
Notably, child indexing is deliberately not implemented. That is, if a “Model” instance contains a child named “Brick”, then Model.Brick
cannot be used to get the child. Instead, rbxmk provides the Descend method to recursively acquire descendants in a safe manner:
local brick = game:Descend("Workspace", "Model", "Brick")
Attributes are also accessible with the usual attribute methods. Additionally, rbxmk provides the SetAttributes method to efficiently set all attributes at once.
Descriptors
By default, rbxmk has no knowledge of the class of an instance. Properties are assumed based on how they are decoded, and the types used when set. Descriptors provide extra information about the classes, members, and enums of an implementation, used to enforce the content of instances.
rbxmk provides no descriptors by default, but there are several flags available for including descriptors automatically.
# Use local API dump as global descriptor.
rbxmk run --desc-file dump.desc.json file.lua
# Automatically download API dump for latest version of Roblox.
rbxmk run --desc-latest file.lua
This concept of descriptors allows rbxmk scripts to be as forward- or backward-compatible as required by your project. Solutions without descriptors are also available.
Libraries
The environment includes the standard math, string, table, and os libraries, and most of the global functions. Additionally included are the Roblox-specific extensions, such as math.clamp, string.split, and table.find. rbxmk also provides several of its own libraries.
The rbxmk library contains functions related specifically to rbxmk, which includes running files and strings as scripts, setting global configuration, or decoding and encoding from a variety of formats.
The fs library provides an interface to the file system.
The path library provides functions for working with file paths.
The clipboard library provides an interface to the operating system’s clipboard.
The rbxassetid library provides an interface to assets on the Roblox website.
The http enables general HTTP requests. Requests run concurrently, but can be resolved or canceled.
Many more features are available. Once again, the documentation provides a complete reference.
Examples
Download a Roblox asset to a local file
Start with the following script, saved as download-asset.rbxmk.lua
:
local id, output = ...
local asset = rbxassetid.read({
AssetID = id,
Format = "bin",
})
fs.write(output, asset, "bin")
Then, to download Crossroads to a local file, run the following command:
rbxmk run download-asset.rbxmk.lua 1818 Crossroads.rbxl
Convert URL in clipboard to model
Start with the following script, saved as copy-model.rbxmk.lua
:
-- Read a model asset URL from the clipboard, then copy the content of the model
-- to the clipboard, ready to be pasted into Studio.
local useStudioCookies = ...
local url = clipboard.read("txt")
local id = tonumber(url:match("%d+"))
if not id then
error(string.format("failed to parse asset ID from URL %q", url), 0)
end
local options = {
AssetID = id,
Format = "rbxm",
}
if useStudioCookies then
options.Cookies = Cookie.from("studio")
end
local asset = rbxassetid.read(options)
clipboard.write(asset, "rbxm")
Then, run the following command:
rbxmk run copy-model.rbxmk.lua
To use Studio cookies for authentication:
rbxmk run copy-model.rbxmk.lua true