Roblox Packages – Reusable Game Assets
Roblox Packages – Reusable Game Assets
Roblox packages allow you to create object hierarchies once and re-use them in as many games as you’d like. The primary advantage of this workflow is that you can keep packages in sync by updating any copy within any game to the most current version.
Packages can be easily recognized in the Explorer hierarchy by the “chain link” symbol in the lower-right corner of the icon:
Model
Converting Objects to Packages
All reusable objects can be converted to packages. Note that if the intended package contains 3D elements, you should group them into a Model and set the PrimaryPart.
To convert an object into a package:
- In the Explorer window, right-click the object and select Convert to Package….
- In the dialog window, fill in the requested details.
- Click the Publish button.
- Once published, you’ll see a new PackageLink object parented to the object.
Accessing Packages
Published packages can be accessed from either the Toolbox or Game Explorer.
Toolbox
Any time you publish a package, it is added to the My Packages sorting in the Toolbox. This serves as a consolidated space to find and insert a package into any place in any game.
Game Explorer
Packages that are used within any place in a game also appear in the Packages folder of the Game Explorer window.
Right-clicking any package in the Game Explorer provides the following options:
| Option | Description |
|---|---|
| Insert | Adds a copy of the most recent published version of the package under the current selection (or the workspace if nothing else is selected). Double-clicking the package object has the same effect. |
| View on Website | Opens up your browser to the package's asset page. |
| Copy ID to Clipboard | Copies the asset ID of the package to the clipboard. |
Publishing/Syncing Packages
Packaged objects can be edited just like any other object. Those with unpublished changes are marked with an orange dot in the Explorer window.
Publishing Restrictions
Be mindful that you cannot publish an overall place if it contains packages with unpublished changes. For package copies in this state, you have these options:
- Publish the changed copy as the most recent version as outlined in Publishing Changes below.
- Undo the changes which were made to the copy. This can be done via the usual Undo shortcut/button or by right-clicking the package and selecting Undo Changes to Package from the context menu.
- Delete the changed copy entirely.
Nested Packages
When working with nested packages, for instance a packaged script inside a packaged model, note the following:
- If you edit and publish a child (nested) package, the parent package will be marked as changed and you'll need to re-publish it.
- If you edit and publish a parent package, any child (nested) packages within it will not be marked as changed and therefore will not need to be re-published.
- Nested packages cannot be auto-updated because that occurrence would cause its parent package to become modified.
Change Exceptions
Note that if the object is a Model or GUI object, changes to position or rotation do not count as changing the package. This lets you use several copies of the same object in different positions and orientations.
Publishing Changes
To publish changes to a package and make them available to other package copies:
- In the Explorer window, right-click the changed copy and select Publish Changes to Package.
- If prompted to publish the changes, click the Publish button.
- Once completed, outdated copies of the package will be marked with a green sync icon indicating that a newer version is available.
Syncing Outdated Copies
Outdated package copies marked with a 
icon can be updated to the most recent version, or you can continue to use the older version. To update to the latest version:
- In the Explorer window, right-click the package copy and select Get Latest Package.
- If prompted, click the Get Latest button. This will update the package copy to the most recent version.
Syncing Multiple Copies
To sync multiple outdated copies at once, select all of them in the Explorer window, right-click, and choose Get Latest For Selected Packages from the context menu. Alternatively, you may set multiple copies to update automatically as outlined below.
Auto-Updating Copies
To make syncing easier, a package copy can be set to auto-update whenever a newer version is published:
- Select the package copy and expand its hierarchy tree in the Explorer window.
- Select its PackageLink object.
- Enable the AutoUpdate property in the Properties window.
All package copies set to automatically update will be live-swapped after you publish an update to another copy in Studio, as well as when a place containing outdated copies is loaded.
Mass-Updating Packages
In addition to the above methods, packages can be updated on a game-wide scale:
- Open the Game Explorer window and expand the Packages folder.
- Right-click the desired package object and select Update All from the context menu.
- In the popup window, select the places within the game for which the mass update should apply. When ready, click the Update button.
Comparing Script Changes
When a converted package object contains scripts — or the script itself is a package — you can compare differences line-by-line against the most recently published version. This can help you decide whether to update as well as explore what else in the game may need edits to make the update compatible.
To compare script changes:
- In the Explorer window, right-click an outdated package copy (look for the sync icon). Remember that the package must either be a script or contain packaged scripts!
- Select View Script Changes….
- In the Diff Result tab that opens, you can compare all of the changes between the current package copy and the latest published version, similar to source control applications.
