This is a fork of Remodel with changes specific to the workflow at Uplift Games.
Changes from upstream Remodel:
- Uses Luau instead of Lua
- Adds runCommand to run spawn executables and read results
- Adds task library
- Adds httpRequest method
- Makes most remodel functions async
- Fixes ref cloning to match Roblox behavior
- Adds the ability to read Ref properties from Luau
- Adds Font support
- Adds Model Scale support
- Adds Font and Gui Inset migrations
Release Instructions
New Uplift Games-specific releases should:
- Be created on the
uplift-games-fork-releasesbranch (this is like ourmain) - Be tagged with an appropriate semver plus a pre-release tag in the following format:
v1.2.3-uplift.release.1
...wherev1.2.3is the semver anduplift.release.1increments with each release under that semver.
This tag should be created locally and pushed to kick off automated builds (see Notes on version tags) - The chosen semver should be relative to upstream according to the difference
at that release.
For example, if upstream is onv1.0.0and we make a minor change, we'll be onv1.0.1-uplift.release.1. If we make another minor change, we'll be onv1.0.1-uplift.release.2because we are still only minor changes away from upstream. This way, if our changes get upstreamed, we won't be going backwards in semver. - Add our changes to
CHANGELOG.md. If we rebase on a new version of Remodel that includes some of our additions, we should list only what has changed between upstream Remodel and our fork. - Where possible, our changes should become PRs to the upstream Remodel repo. When we do this, we should include a link to the PR in the changelog entry.
Notes on version tags:
- Tags can be created locally with the command
git tag v1.2.3-uplift.release.1 - Tags can be pushed to the remote with the command
git push origin v1.2.3-uplift.release.1 - When a tag starting with
vis pushed to this repo, an action is kicked off which creates a release draft and attached build artifacts when they're completed. Go to the releases page and edit the draft to publish it.
Remodel is a command line tool for manipulating Roblox files and the instances contained within them. It's a scriptable tool designed to enable workflows where no other tool will do.
Remodel can be used to do almost anything with Roblox files. Some uses include:
- Extracting models from a place to use with Rojo
- Copying terrain from one place into another
- Minifying scripts before deploying a place
- Automatically attaching build metadata to a place
- Synchronizing development places with production
Remodel is still in early development, but much of its API is already stable. Feedback is welcome!
The following instructions are for installing the Uplift fork of remodel. If you're looking to install standard Remodel, see Remodel's Installation section.
With Aftman
Remodel can be installed with Aftman, a toolchain manager for Roblox projects:
[tools]
remodel = "UpliftGames/remodel@0.12.0-uplift.release.12"You can download pre-built binaries from the GitHub Releases page.
Most of Remodel's interface is its Lua API. Users write Luau scripts that Remodel runs, providing them with a special set of APIs.
One use for Remodel is to break a place file apart into multiple model files. Imagine we have a place file named my-place.rbxlx that has some models stored in ReplicatedStorage.Models.
We want to take those models and save them to individual files in a folder named models.
local game = remodel.readPlaceFile("my-place.rbxlx")
-- If the directory does not exist yet, we'll create it.
remodel.createDirAll("models")
local Models = game.ReplicatedStorage.Models
for _, model in ipairs(Models:GetChildren()) do
-- Save out each child as an rbxmx model
remodel.writeModelFile("models/" .. model.Name .. ".rbxmx", model)
endFor more examples, see the examples folder.
Remodel supports some parts of Roblox's API in order to make code familiar to existing Roblox users.
Instance.new(className)(0.5.0+)- The second argument (parent) is not supported by Remodel.
<Instance>.Name(read + write)<Instance>.ClassName(read only)<Instance>.Parent(read + write)<Instance>:Destroy()(0.5.0+)<Instance>:Clone()(0.6.0+)<Instance>:GetChildren()<Instance>:GetDescendants()(0.8.0+)<Instance>:FindFirstChild(name)- The second argument (recursive) is not supported by Remodel.
<DataModel>:GetService(name)(0.6.0+)
Remodel supports some parts of Roblox's Task API.
task.spawn(function | thread, ...): threadtask.defer(function | thread, ...): threadtask.delay(duration: number, function | thread, ...): threadtask.wait(duration: number): number
Remodel will run until all tasks that it's aware of are complete.
Remodel's coroutine handling looks a lot like Roblox's: async operations yield
the current coroutine until they complete. You can resume or close the coroutine
early. With some minor modifications, libraries like Promise work in remodel.
If remodel is running longer than expected, you likely have a coroutine running
in the background. You can list all running tasks to the output with
_runtime.debug.list_lua_tasks()
Remodel has its own API that goes beyond what can be done inside Roblox.
remodel.readPlaceFile(path: string): Instance
Load an rbxlx file from the filesystem.
Returns a DataModel instance, equivalent to game from within Roblox.
Throws on error.
remodel.readModelFile(path: string): List<Instance>
Load an rbxmx or rbxm (0.4.0+) file from the filesystem.
Note that this function returns a list of instances instead of a single instance! This is because models can contain mutliple top-level instances.
Throws on error.
remodel.readPlaceAsset(assetId: string): Instance
Reads a place asset from Roblox.com, equivalent to remodel.readPlaceFile.
This method requires web authentication for private assets! See Authentication for more information.
Throws on error.
remodel.readModelAsset(assetId: string): List<Instance>
Reads a model asset from Roblox.com, equivalent to remodel.readModelFile.
This method requires web authentication for private assets! See Authentication for more information.
Throws on error.
remodel.writePlaceFile(path: string, instance: DataModel)
Saves an rbxlx file out of the given DataModel instance.
If the instance is not a DataModel, this method will throw. Models should be saved with writeModelFile instead.
Throws on error.
remodel.writeModelFile(path: string, instance: Instance)
Saves an rbxmx or rbxm (0.4.0+) file out of the given Instance.
If the instance is a DataModel, this method will throw. Places should be saved with writePlaceFile instead.
Throws on error.
remodel.writeExistingPlaceAsset(instance: Instance, assetId: string)
Uploads the given DataModel instance to Roblox.com over an existing place.
If the instance is not a DataModel, this method will throw. Models should be uploaded with writeExistingModelAsset instead.
This method always requires web authentication! See Authentication for more information.
Throws on error.
remodel.writeExistingModelAsset(instance: Instance, assetId: string)
Uploads the given instance to Roblox.com over an existing model.
If the instance is a DataModel, this method will throw. Places should be uploaded with writeExistingPlaceAsset instead.
This method always requires web authentication! See Authentication for more information.
Throws on error.
remodel.getRawProperty(instance: Instance, name: string): any?
Gets the property with the given name from the given instance, bypassing all validation.
This is intended to be a simple to implement but very powerful API while Remodel grows more ergonomic functionality.
Throws if the value type stored on the instance cannot be represented by Remodel yet. See Supported Roblox Types for more details.
remodel.setRawProperty(
instance: Instance,
name: string,
type: string,
value: any,
)
Sets a property on the given instance with the name, type, and value given. Valid values for type are defined in Supported Roblox Types in the left half of the bulleted list.
This is intended to be a simple to implement but very powerful API while Remodel grows more ergonomic functionality.
Throws if the value type cannot be represented by Remodel yet. See Supported Roblox Types for more details.
remodel.readFile(path: string): string
Reads the file at the given path.
Throws on error, like if the file did not exist.
remodel.readDir(path: string): List<string>
Returns a list of all of the file names of the children in a directory.
Throws on error, like if the directory did not exist.
remodel.writeFile(path: string, contents: string)
Writes the file at the given path.
Throws on error.
remodel.removeFile(path: string)
Removes the file at the given path.
This is a thin wrapper around Rust's fs::remove_file function.
Throws on error.
remodel.createDirAll(path: string)
Makes a directory at the given path, as well as all parent directories that do not yet exist.
This is a thin wrapper around Rust's fs::create_dir_all function. Similar to mkdir -p from Unix.
Throws on error.
remodel.removeDir(path: string)
Removes a directory at the given path.
This is a thin wrapper around Rust's fs::remove_dir_all function.
Throws on error.
remodel.isFile(path: string): bool
Tells whether the given path is a file.
This is a thin wrapper around Rust's fs::metadata function.
Throws on error, like if the path does not exist.
remodel.isDir(path: string): bool
Tells whether the given path is a directory.
This is a thin wrapper around Rust's fs::metadata function.
Throws on error, like if the path does not exist.
remodel.runCommand(command: string, args: { string }?): { stdout: string, stderr: string, status: boolean, code: number }
Runs a command and returns the result.
type HttpRequestOptions = {
Url: string,
Method: string?,
Headers: { [string]: string }?,
Body: string?,
RobloxAuth: boolean?,
RobloxApiKey: boolean?,
RobloxCsrf: boolean?,
}
type HttpRequestResponse = {
Success: boolean,
StatusCode: number,
StatusMessage: string,
Headers: { [string]: string },
Body: string,
}
remodel.httpRequest(options: HttpRequestOptions): HttpRequestResponse
Sends an http request and returns the result.
Throws if your request is malformed or if there was an issue sending the request. If the request succeeded, but the server did not like it, the response is still returned without throwing.
Options notes:
Methodshould be upper-case, and defaults toGETRobloxAuthwill add aCookieheader with the current Roblox auth cookieRobloxApiKeywill add ax-api-keyheader with the open cloud API keyRobloxCsrfwill automatically retry with thex-csrf-tokenheader if given a csrf challenge.
json.fromString(source: string): any
Decodes a string containing JSON.
Throws on error, like if the input JSON is invalid.
json.toString(value: any): string
Encodes a Lua object as a JSON string. Can only encode Lua primitives like tables, strings, numbers, bools, and nil. Instances cannot be encoded to JSON.
Throws on error, like if the input table cannot be encoded.
json.toStringPretty(value: any, indent?: string = " "): string
Encodes a Lua object as a prettified JSON string. If an indent is passed, will use that for indentation, otherwise will default to two spaces.
Throws on error, like if the input table cannot be encoded.
When interacting with Roblox instances, Remodel doesn't support all value types yet and may throw an error.
Supported types and their Lua equivalents:
String:stringContent:stringBool:booleanFloat64:numberFloat32:numberInt64:numberInt32:number
More types will be added as time goes on, and Remodel will slowly begin to automatically infer correct types in more contexts.
Some of Remodel's APIs access the Roblox web API and need authentication in the form of a .ROBLOSECURITY cookie to access private assets. Auth cookies look like this:
_|WARNING:-DO-NOT-SHARE-THIS.--Sharing-this-will-allow-someone-to-log-in-as-you-and-to-steal-your-ROBUX-and-items.|<actual cookie stuff here>
Auth cookies are very sensitive information! If you're using Remodel on a remote server like Travis CI or GitHub Actions, you should create a throwaway account with limited permissions in a group to ensure your valuable accounts are not compromised!
On Windows, Remodel will attempt to use the cookie from a logged in Roblox Studio session to authenticate all requests.
To give a different auth cookie to Remodel, use the --auth argument:
remodel run foo.lua --auth "$MY_AUTH_COOKIE"
You can also define the REMODEL_AUTH environment variable to avoid passing --auth as an argument.
Remodel is similar to rbxmk:
- Both Remodel and rbxmk use Lua
- Remodel and rbxmk have a similar feature set and use cases
- Remodel is imperative, while rbxmk is declarative
- Remodel emulates Roblox's API, while rbxmk has its own, very unique API
Remodel is available under the terms of the MIT license. See LICENSE.txt for details.