Packager - Convert Instances to/from data structures

Resources Community Resources
, ,
#1

Get it on GitHub Get it on Wally Get it on Roblox

Packages up an Instance or tree of Instances into a single table. Supports linking of Instance-based properties to their corresponding Instance (as long as the Instance is within the tree being packaged).

Packager can also reconstruct Instances from a tree structure. See the examples (below) or documentation on how to do this.

Packager can generate both flat and tree structures from Instance trees, and produces trees similar to that of rojo’s JSON models. Packages can be converted between flat and structured tree formats.

Under the hood, Packager relies on DumpParser to parse API data and generate structured content. You can supply your own API dump directly, or pass your own DumpParser instance to Packager.new(), or use .fetchFromServer() to automatically fetch the latest API dump (for your current version of Roblox) and construct a new DumpParser which will be used by Packager internally.

:closed_book: Documentation

Documentation is available at https://csqrl.github.io/packager.

:rocket: Quick Start

Packager is available via Wally, GitHub and the Roblox Creator Marketplace.

Wally

# wally.toml

[dependencies]
Packager = "csqrl/packager@0.1.0"

Manual Installation

Grab a copy from the Roblox Creator Marketplace (Toolbox), or download the latest binary from the GitHub repo and drop it into Studio.

:keyboard: Basic Examples

Packaging Up Instances

local Packager = require(script.Parent.Packager)

-- Create a new Packager from the latest Roblox API dump
local packager = Packager.fetchFromServer()

local tree = packager:CreatePackage(workspace.MyModel)
--[[
  {
    Refs = {
      [MyModel<Model>] = "AABBCC",
      [Part<Part>] = "BBCCDD",
    },
    Tree = {
      Name = "MyModel",
      ClassName = "Model",
      Ref = "AABBCC",
      Properties = {
        PrimaryPart = {
          Type = "Ref",
          Value = "BBCCDD",
        },
      },
      Children = {
        {
          Name = "Part",
          ClassName = "Part",
          Ref = "BBCCDD",
          ...,
        },
      },
      Attributes = {
        OwnerId = {
          Type = "number",
          Value = 1233456789,
        },
      },
      Tags = { "Tag1", "Tag2" },
    },
  }
]]

Reconstruction

Reconstruct a package back into its physical Instances:

local rootInstance = packager:BuildFromPackage(tree)

rootInstance.Parent = workspace

BuildFromPackage accepts both flat and tree structures. Tree structures will automatically be flattened internally.

4 Likes