To keep assets organized and reusable across your team or across multiple projects, group your instances and convert them into reusable packages. Packages make the overall process of building worlds faster and more ergonomic, but they also help with consistency, deduplication, collaboration, and versioning:
- Easily update all copies of a package to the latest version (or only update specific copies).
- Set packages to automatically update whenever there's a new version.
- Give collaborators Edit or Use permissions to the contents of a package.
- View the full version history for a package, compare versions, and restore old versions.
The most efficient workflow is to create a package, share it with any collaborators, and set it to auto-update. And you don't have to wait for a model to be "done" before using it in a package. Even if the package is a placeholder on top of a simple shape, you can use it to greybox your environment and then have the placeholder copies automatically update as you publish more detailed versions.
Creating Packages
You can create a package from any single object or any single parent and children branch of objects. If you want to create a package for a single object, we recommend adding it to a Model grouping first so that you can add, remove, or scale instance within the package later without breaking the package.
In the Explorer window or 3D viewport, right-click the desired object and select Convert to Package.
In the new window, fill in the package details. In particular, if you're working in a group, set Ownership to the appropriate group in which you have permission to create/edit group experiences.
Ownership transfers are not supported by the asset system, so carefully consider the owner when creating a package.
Click Submit.
After the conversion completes, the object receives a "chain link" symbol in the Explorer window to identify it as a package. Additionally, you can see a new PackageLink object parented to the object.
(Optional) Select the PackageLink object and enable AutoUpdate in the Properties window. Note how the icon changes to indicate that the package is set to automatically update.
Don't delete or move the PackageLink instance! Doing so for any package copy converts the copy back into a normal object and loses package capabilities such as ability to update when there's a new version.
Inserting Packages
To insert a package that doesn't already exist in the current place, you must initially insert it from the Toolbox:
- From Inventory → My Packages for packages that you've published to or obtained from the Creator Store, as well as packages that a friend owns and has given you permissions to use.
- From Creations → Group Packages for packages published by members of your group (including yourself).
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.
Be careful when inserting assets that you didn't create into your experiences, as they can contain malicious scripts. Save your experience first and then investigate any scripts within unfamiliar assets so that you can easily revert back to the place version.
Publishing Package Changes
You can publish any changes you make to a package as a new version to make them 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 is saved along with the place for future iteration).
To publish changes to a package:
In the Explorer window or 3D viewport, right-click the modified copy and select Publish to Package.
If a package copy has auto-update turned on, it immediately pulls in the updated version when you open the place that contains them. Other copies get a white dot on the package icon that indicates an update is available. You can individually update or mass-update them as needed.
(Optional) Add a description of your changes:
- Right-click the package and select Package Details.
- In the Asset Configuration window, select Versions.
- Under your most-recent change, select Add.
- Describe your changes and click Submit.
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:
In the Explorer window, locate outdated copies by the white dot on the package icon. You can also select the outdated copy in the 3D viewport, but it might be harder to find this way.
Right-click the outdated copy and select Get Latest Package. You can also select multiple packages, right-click, and 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.
(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.
In the Explorer window or 3D viewport, right-click the desired package and select Update All.
Choose all places in the experience or some subset of places and click Update.
To prevent unintended overwrites, mass updating does not affect modified versions of a package. After the mass update completes, Studio displays a warning with the number of packages that it did not update, if any.
Mass updating packages automatically saves the selected places but does not publish them.
Automatic Updates
To make syncing easier, you can set a package copy to update automatically whenever a newer version is published. Auto-update of the package copies will take place when a place is opened in Studio.
In the Explorer window, expand the package's hierarchy tree and select its PackageLink object.
In the Properties window, enable the AutoUpdate property. If you have nested packages, this property only applies to the highest-level parent package, meaning automatic updates only occur when the parent package is updated.
Automatic updating does not apply to modified package copies. Once you modify a package instance, its AutoUpdate property becomes disabled and is ignored.
Sharing and Access Levels
If desired, you can share packages with friends or grant access to specific user roles within your group.
In the Explorer, Toolbox, or Asset Manager, right-click the desired package and select Package Details.
In the Asset Configuration window, select Permissions.
For a group-owned package, expand the roles tree. Then choose a permission level for each role. Selection boxes that are disabled indicate that the permission is already configured for that role and cannot be changed from this window.
Permission Description Edit Members of the role can 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 Access Members of the role do not have access to any new versions of the package, although they retain access to the current version inserted into the place. For a user-owned package, search for friends through the search field, click their username, and choose a permission level.
Permission Description Use & View The user can 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 prevents reinsertion or package updates, but package copies in their data model remain intact. Edit The user can use, view, and edit the current and previous package versions, including publishing changes to it.
Modifying Packages
You can edit packages and their children just like other objects. Modifying packages disables auto-update until you publish or revert the changes.
Most edits flag the package as modified, although the following changes are not considered package modifications:
- Changing the name of the root node.
- Changing the Enabled property of a root node GuiObject such as a ScreenGui, SurfaceGui, or BillboardGui.
- Changing a part reference of a Weld inside the package that references an instance outside of the package.
Once modified, packages with unpublished changes get a modified icon in the Explorer window:
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.
Currently the only way to handle configuration values is to add scripts in the package which read and apply behavior based on the configuration at runtime.
If you simply want to update the default values for configurations, you can change those attribute values and republish the package (the package will not be flagged as modified in this case). If you want to publish other modifications but not change the default configuration values, you should publish on a package without any value changes, or revert the configurations to their defaults before you publish.
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. This example shows a car package that contains four copies of the same wheel package:
If you modify a nested package, both the nested package and the parent package are considered as modified. You must publish changes to any nested package before you're allowed to publish changes to its parent package, since publishing the parent would mark it as current/unmodified and conflict with the nested package's modifications.
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.
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.
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:
In the Explorer window, locate modified copies by the exclamation point next to their names. You can also select modified copies in the 3D viewport, which might be easier.
Right-click a single modified copy and select Undo Changes to Package, 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:
In the Explorer window, 3D viewport, Toolbox, or Asset Manager, right-click the desired package and select Package Details.
In the Asset Configuration window, select Versions. The window displays details for each published version, including the date and time of publication, along with any descriptions of the changes.
Click the checkmark next to the version you want to restore and click Submit.
Reverting changes to a package does not reset the configuration to the default. See Reverting Configuration.
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.
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.
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.
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.
To compare package versions:
In the Explorer window or 3D viewport, right-click the target package and select Compare Package Versions.
By default, the window compares changes between your local copy and the latest version. Use the two dropdown menus to compare different versions.
Some older versions might be incompatible with the package diff tool.
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.
This tool only allows you to compare script changes between the current version and the latest published or local version, without indicating the collaborators who made the change.
Alternatively, you can open the script diff tool directly:
- In the Explorer window or 3D viewport, right-click the target package, which must either be a script or contain scripts, and select View Script Changes.
- In the diff tab that opens, compare all changes of the selected script between the current package copy and the latest published or local version.