Packages

To optimize asset management across your entire team or across multiple projects, you can convert single assets or asset hierarchies into packages and reuse them in multiple experiences. When a package is updated, you or your team members can update specific copies to the most current version, update all copies across an experience, or set specific copies to auto update. Packages also include a configuration mechanism that lets package creators and editors include options to customize a package's behavior.

Creating Packages

You can create a package from any single object or any single parent and children branch of objects. When you create a package for a single object, it's recommended to add that object to a Model grouping first so that you can add, remove, or scale objects within the package later without breaking the package.

  1. In the Explorer window, right-click the desired object or parent of object, then select Convert to Package from the contextual menu.

    The contextual menu that display when you right-click an object in the Explorer window. The Convert to Package menu item is highlighted.
  2. In the contextual window, fill in the requested details. In particular, if you're working in a group, set Ownership to the desired group in which you have permission to create/edit group experiences.

  3. Click the Submit button.

  4. Once complete, a "chain link" symbol over the object's icon identifies it as a package. Additionally, you'll see a new PackageLink object parented to the object.

    The default icon for a model.
    Standard Model
    The icon for a packaged model.
    Packaged Model
    A close up view of a chandelier package in the Explorer window with its PackageLink child highlighted.
    PackageLink child on package

Inserting Packages

To insert a package which doesn't already exist in the current place, you must initially insert it from the Toolbox under these guidelines:

  • From InventoryMy Packages for packages that you've published or obtained from the Creator Store.
  • From CreationsGroup Packages for packages published by members of your group (including yourself).
A close up view of the Toolbox with both the Inventory tab and the assets dropdown menu highlighted.
Toolbox → Inventory → My Packages
A close up view of the Toolbox with the Creations tab highlighted.
Toolbox → Creations → Group Packages

Once you've inserted a package into a place's data model, it appears in the Packages folder of the Asset Manager and remains there even if you later delete all copies of it. However, when you publish the place, the folder will update to reflect only packages used within the place.

The Asset Manager window with a few example packages.
Packages in Asset Manager

Modifying Packages

You can edit packages and their children just like other objects. On the first edit that modifies a package instance, an alert dialog appears, providing advanced notice that a modified package cannot be updated through any means and must be reverted to undo a series of edits.

The pop-up notice that you cannot update a modified package until you publish or revert your changes.

Most edits will flag the package as modified, although the following changes are not considered package modifications:

EditModifies Package
Changing the name of the root node.no
Changing the position or rotation of the root node of a package that is a BasePart, Model, or GuiObject.no
Changing the Enabled property of a root node GuiObject such as a ScreenGui, SurfaceGui, or BillboardGui.no
Changing a part reference of a Weld inside the package that references an instance outside of the package.no

Once modified, packages with unpublished changes are marked with a yellow dot in the Explorer hierarchy.

A close up view of a packaged model in the Explorer window. The yellow dot that signifies the package includes unpublished changes displays to the left of the package's name.

Adding or Updating Configurations

You can include instance attributes at the root of a package to customize its behavior, for example the max speed of a packaged vehicle or the debounce time for a packaged button.

When you publish a package, the current set of attributes/values will become the package's default configurations. On any given copy of a package, configurations are shown in bold italics and those attribute values can be changed on a per-instance basis. When package copies are updated, modified configuration values will be preserved, while other attributes will be updated to the latest default value.

The Attributes section of the Properties window. Two properties are highlighted as having their default values while two other italicized properties are highlighted to show they have been configured.

Nested Packages

You can nest packages inside of other packages to maintain and collaborate on complex hierarchies, such as a series of vehicle mechanics which can be modified independently of the vehicle's parent package.

A close up view of a packaged car model in the Explorer window. The package's hierarchy is expanded to show that it includes children that are also packages.

Package Scripts

Each script within an unmodified package is read-only and shows a notification on the top with a hyperlink to unlock the script.

A script tab with a yellow notification that you can click to modifiy the script that's within an unmodified package.

Clicking the hyperlink:

  • Flags the package as modified regardless of whether you edit the script.
  • Removes the notification/hyperlink from other scripts within the package.

Once the package is published and moved to an unmodified state, the scripts under it become read-only with a hyperlink to modify.

Publishing Package Changes

You can publish a modified package (marked with a yellow dot) to make those modifications available to other copies of the package throughout the place and across all experiences. Note that it's not required to publish a modified package before publishing a place (the modified version will be saved along with the place for future iteration).

To publish changes to a package:

  1. In the Explorer window, right-click the modified copy (marked with a yellow dot) and select Publish to Package.

    The contextual menu that display when you right-click an object in the Explorer window. The Publish to Package menu item is highlighted.
  2. For package copies set to automatically update, Studio will immediately pull in the updated version. Other copies will be marked with a green sync icon next to the name and you can individually update or mass-update them as needed.

    A close up view of a packaged chandelier model in the Explorer window. The green sync icon to the right of the package's name is highlighted.

Updating Outdated Copies

You can update outdated package copies to the most recent version, or you can continue to use the older version.

To update one or more package copies to the latest version:

  1. In the Explorer window, locate outdated copies by the green sync icon next to their name.

    A close up view of a packaged chandelier model in the Explorer window. The green sync icon to the right of the package's name is highlighted.
  2. Right-click a single outdated copy and select Get Latest Package from the contextual menu, or select multiple copies (at least one of them modified), right-click, and select Get Latest For Selected Packages.

Mass Updates

Extensive use of packages may result in many package copies across multiple places in an experience. In addition to individual syncing and automatic updates, you can update all copies of a package through mass updating.

  1. (Recommended) Close other Studio instances with any of the experience's places open; this prevents another unsaved instance of a place from potentially overwriting your updates.

  2. In the Explorer window, right-click the desired package and select Update All from the contextual menu.

  3. In the popup window, below the version/date details, check All to select all places in the experience, or select only the specific places to apply the mass update.

    A close up view of some settings in the pop-up window. The Version/Date and All radio button are highlighted.
  4. Click the Update button.

Automatic Updates

To make syncing easier, you can enable a package copy to update automatically whenever a newer version is published and when it exists inside an open Studio session.

  1. In the Explorer window, expand the package's hierarchy tree and select its PackageLink object.

    A close up view of a packaged chandelier model in the Explorer window. The PackageLink object is highlighted.
  2. In the Properties window, enable the AutoUpdate property. This property only applies to the highest level parent package in a hierarchy of nested packages, meaning automatic updates will only occur when the parent package is updated.

Sharing and Access Levels

If desired, you can share packages with friends or grant access to specific user roles within your group.

  1. In the Explorer, Toolbox, or Asset Manager, right-click the desired package and select Package Details from the contextual menu.

  2. In the popup window, select Permissions in the left column to reveal sharing/access options for either group-owned or user-owned packages.

    • For a group-owned package, expand the roles tree by clicking the next to the group's icon, then choose a permission level for each role. Selection boxes that are faded/disabled indicate that the permission is already configured for that role and it cannot be changed from this window.

      A close up view of some settings in the pop-up window. The arrow icon next to the group icon and the member Edit dropdown menu are highlighted.
      PermissionDescription
      EditMembers of the role will be able to use, view, and edit the current and previous package versions, including publishing changes to it. Granting edit access to a role from this window only grants access to the specific package.
      No AccessMembers of the role will not have access to any new versions of the package, although they will retain access to the current and previous versions.
    • For a user-owned package, search for a friend through the search field, click their avatar/username, and choose a permission level.

      A friend tile with the Edit dropdown menu highlighted.
      PermissionDescription
      Use & ViewThe user will be able to use and view (but not edit) the current and previous package versions. Once you provide a user with this ability, you cannot revoke access to a copy they already inserted into their experience; revoking access will prevent re-insertion or package updates, but package copies in their data model will remain intact.
      EditThe user will be able to use, view, and edit the current and previous package versions, including publishing changes to it.

Reverting Package Changes

Instead of undoing an entire series of package changes one by one, you can revert unpublished changes in one action, restore a package to a previous version, or revert changes to specific configurations.

Reverting Unpublished Changes

To undo an entire series of unpublished changes:

  1. In the Explorer window, locate modified copies by the yellow dot next to their name.

  2. Right-click a single modified copy and select Undo Changes to Package from the contextual menu, or select multiple copies (at least one of them modified), right-click, and select Undo Changes to Selected Packages.

Restoring to Version

To restore a package to a previously published version:

  1. In the Explorer window, Toolbox, or Asset Manager, right-click the desired package and select Package Details from the contextual menu.

  2. In the pop-up window, select Versions in the left column. The currently published version and previously published versions appear (V1, V2, …) along with the date/time they were published.

  3. Click the checkmark next to the version you want to restore and click Submit.

    The pop-up window for a chandelier asset. It displays multiple versions.

Reverting Configurations

To revert any configuration attribute to its default, select the Reset option from the gear menu in the Attributes section of the Properties window.

The Attributes section of the Properties window. The gear menu is expanded and the Reset menu item is highlighted.

Comparing Package Versions

When a package has multiple versions, you can compare changes between versions using the diff viewer, which is helpful for reviewing package updates, comparing your local changes against the latest version, and checking the content of past versions before restoring.

The tool has a package hierarchy menu that indicates all added, removed, or modified instances between versions using corresponding icons, with the following tabs available:

  • Visual Overview shows the visual differences of the 3D rendering under different camera positions. It's the default view for packages with a 3D object (models, parts) as the root object, and it's currently only available for the root object.

    An example of the Visual Overview tab in the diff viewer. One version of a building displays on the left-hand side, and another on the right-hand side.
  • Properties shows changes of properties and attributes. It's the default view for packages with a non-3D object (scripts, lights, 2D objects) as the root object, and it's available for all instances in a package.

    An example of the Properties tab in the diff viewer. Modified properties in different versions are highlighted.
  • Script shows line-by-line script differences. It's available for packages containing scripts, regardless of whether the script is the root object or not.

    An example of the Script tab in the diff viewer. Modified script lines in different versions are highlighted.

To compare package versions:

  1. In the Explorer window, right-click the target package.

  2. Select Compare Package Versions from the context menu.

  3. On the Diff Viewer window, by default, you can compare changes between your local copy and the latest version. You can also select any two versions to compare using the dropdown menu.

    A close up view of an example diff viewer. The compare settings are highlighted.
  4. After selecting versions:

    • To compare the visual renderings of the root model, if applicable, select the Visual Overview tab and adjust the camera control for your desired angle. Controls are synchronized across views:

      • Pan the camera using left mouse clicks.
      • Rotate the camera using right mouse clicks.
      • Zoom in and out the camera with the mouse wheel.
      • Recenter using the keyboard shortcut -F.
    • To compare properties and attributes of an instance, select the instance and the Properties tab.

    • To compare script differences, if applicable, select any script to open the Script tab for line-by-line changes between your selected versions, similar to source control applications.

Alternatively, you can open the script diff tool directly in the Explorer window.

  1. Right-click the target package, which must either be a script or contain scripts.
  2. Select View Script Changes from the context menu.
  3. In the Diff Result tab that opens, compare all changes of the selected script between the current package copy and the latest published or local version.