YOU Should use Packages. Yes, YOU!

[SCHLEEMPH]

What are packages
Creating Packages
Nest a Package
Version Control
Conclusion

What are packages

A package is an asset that has been converted into a reusable instance. An instance is a copy and placement of something that shares identical underlying data. Conceptually, they are very similar to Blueprints in Unreal or Prefabs in Unity.

Packages can exist across many different places, groups, teams, etc.

Packages have some very special and useful properties like:

• Easily update ALL copies of a package to the latest version (or choose a specific version).
  • This is known commonly as “version control.”
• They can be set to automatically update, so when you publish changes to a package, all other instances will immediately receive those changes.
• You can control which teammates and collaborators have permission to edit or use certain packages.
• And more!

I don’t know how people even make content without packages. As someone who originally developed games off-platform, I have to say that working with packages is an ABSOLUTE MUST for effective development.

In Roblox Studio, package instancing is a fundamental and core aspect of efficient creation. So let’s dive into what that means and make your life as a developer INFINITELY EASIER when iterating on and managing content.

Creating Packages

“Create a ‘crate’ package, place it throughout the scene, update later with a polished asset.”

In this section, we’ll create a packaged asset from scratch to demonstrate how easy it is to set up, iterate, automatically update your instances, and fill an entire scene or world with assets. In this example, a simple crate will serve as our sample concept - but imagine this same process applied to walls, floors, ceilings, lighting, props, equipment, items, and ANYTHING that you have more than one of in your world. Instead of the old workflow, when you needed to update an asset, you’d have to hunt down every single placement of it in the world (or in the Explorer) and manually update properties, textures, etc., it can ALL be done automatically through the use of packages.

1. In a blank world, create a cube that is 6x6x6 studs.
2. Move pivot to the bottom of the part.
3. Name it Crate_A_Part
4. Group the Part into a Model, and name the Model ‘Crate_A’
   • On the Model - set the Primary Part to Crate_A_Part, so the model group will inherit the Part’s pivot (at the bottom of the part).
5. Convert the Crate_A Model to Package
6. Set to auto-update.

Create A Package - Staff Article

1. Next, copy or Duplicate the new package around the scene a few times, give it different locations, positions, and even change the scale of the package.
2. Import a cool crate mesh that is 6x6x6 units [example: rbxassetid://15929906696 ]
   • Name it Crate_A_Mesh.
   • Move the pivot to the bottom of the crate mesh.
3. Move the mesh to the same spot as one of your crate packages
4. Drag the mesh object into the package’s modelGroup.
5. Delete the part (or just make the Crate_A_Part transparent, your choice)
   • Note how the icon changes to indicate that the package has unpublished work.
6. Publish the package, see the crate mesh propagate through the level.

Publish a Package - Staff Article

Nest a Package

“Create a SurfaceAppearance package, nest it inside of a mesh. Show workflow for updating complex nested packages.”

Nesting packages lets you treat packages not just as finished models, but as building blocks for more complicated models. You can create a mesh package, and put a packaged surface appearance on it so you can independently update your textures and they’ll propagate throughout the world on all the meshes with little to no friction.

1. Create a SurfaceAppearance object.
2. Import your textures for your crate, or use the sample textures below:
   • colorMap: rbxassetid://15562221699
   • normalMap: rbxassetid://15562224053
   • roughnessMap: rbxassetid://15562225077
   • metalMap: rbxassetid://15229111004
3. Set up the SurfaceAppearance with the textures, and convert it to a package.
   • Name it “SA_Crate_A”
4. Drag it onto the mesh inside the package, creating a nested package.
   • Because these crates are all instances of the same package, it doesn’t matter which one you drag the SurfaceAppearance into–updating any of them lets you update all of them.
5. Publish update, and see all crates appear with a cool material now. Plus, you can use the same SurfaceAppearance on other packages, change it in one place, and update it everywhere.

Nest a Package - Staff Article

**Note - nesting packages can result in some expected friction behavior. If you modify a package that is nested inside of another package, it causes the parent package to enter a modified state. So manually republishing the parent package is required as well. This is a known pain-point within the system and solutions are being designed for it. So don’t delay adoption of the workflow, solutions are inbound!

Version Control

“My collaborator resized the crate and applied the wrong color to the object. Roll back the clock on this asset to a prior version.”

In this example, I’ve updated the scene so that several more package iterations have been done and published, but I made it so the crate is in a really weird state to simulate what might happen if a collaborator publishes some unintended updates.

1. To roll this asset back to a previous version, right-click the package and select Compare Package Versions.
2. In the top-right corner of the dialogue, cycle from the current version through some of the previous iterations until the viewport shows the result you’re looking for.
3. Close the Compare Packages window.
4. Right-click the package again. Choose Package Details, and then the Versions tab.
5. Select the version you want - in this example it was Version 3 - and check the Restore box.
6. Press Save.

Package Version Control - Staff Article

Conclusion

USE PACKAGES! I DON’T KNOW HOW ANY OF YOU MAKE ANYTHING AT ALL WITHOUT THEM!!!

In all seriousness, packages and their features are an absolutely crucial element of managing complexity and assets on Roblox Studio. They give you instancing, version control features, and more! Packages have tons of new features planned for the future, so you should start using them today.

[PolarisWasInDenial (Polaris)]

Excellent explanation; will definitely make use of this in explaining the functionality of Packages to new developers on my teams!

now just to wait for changes to packages sufficient to make it possible to use Rojo to sync them…

[Daw588]

I would use them, but they are so broken, they often get marked as modified even though I haven’t made any changes to them. Not to mention 2 years ago they have corrupted themselves and I lost all my data. They are definitely better than what they used to be, but they still cause too much trouble for me to use them for certain things

[Dekkonot]

@SCHLEEMPH

I don’t know how people even make content without packages.

Rojo, mostly. And a lot of copy and pasting.

You can use Tags and Attributes for a lot of this stuff too, if packages don’t work for your use case.

[RuizuKun_Dev (Kitsune)]

I’d use it if we can have a Cloud API for downloading, modifying, etc

I want to be able to use this in CI/CD for deployment

[HealthyKarl]

@SCHLEEMPH

Conceptually, they are very similar to Blueprints in Unreal or Prefabs in Unity.

The only difference is that on Roblox they’re on a Cloud. They spam my inventory. Though I like them I will use them.

But I wish that I could have Local Prefabs.

The title of this guide is making it look like as if Packages would be perfect. I don’t even know if Roblox fixed the issue where Packages have to Sync.

 

I almost want to create a Bug Report for Package Links calling the API for non rbxassetid:// URLs. Realizing that they call two things, the package and then some side info for the package.

Because yes, I was trying to use the local asset scheme out of curiosity, but the Package System IS DEEPLY working with the API, but I see potential for PackageLinks to get expanded and have it split up from Cloud and Local.

Prefabs, or in Hammer Editor “Instances”, are so useful, but yet lack so many features. And I believe with each Package update from Roblox, they’re wrapping the Package Feature into a Box. They never ever open the Box ever again. They put the Box in even more Boxes at the end the Core Code of Packages themselves are never seen ever again.

Will we ever get Local Packages, will we ever get the ability to make changes to Packages individually without overriding things, but inheriting updates?

Right now, I could actually create a working simulation of Local Packages I think.

Packages are sorta like Pointers, and one of the cool things that exist are ObjectValues. Referncing an Instance to another. Do they work properly? Yes and no: ObjectValue Instance Problems. Properties that hold an Instance require innovation, RefPropDescriptor

When will it get fixed?

 

Original CFrames? Colorable things that you can see in Studio after changing? The only thing I know is that you can change Attributes, that’s all I don’t even know if there’s more except the Attributes. Attributes don’t do a lot.

A Script that changes the color based on Attributes of a Package may will do the thing, but this is not great. A Script needs to run for the changes to apply. But WE need visual.

Most of these can be done with Plugins but… I am not using UniqueId, that one changes too much. ObjectValue’s and the way they work sound more reliable but there’s a few bugs with it. Soo…

But with Local Packages, I mean Instance LINKED not through local file paths. As a Studio Utility. And yes I’d find it very epic if you can have Local Packages linked through an Instance that is a Cloud Package. That sounds very epic.

[ShinsokuDev]

Packages are trying to accomplish the right thing, they just don’t do it well enough yet. Buggy behavior, lack of features, loss of data, etc.

[C_Corpze (Corpze_TheDeadestOne)]

The post title startled me a little, I feel pointed out.

USE PACKAGES! I DON’T KNOW HOW ANY OF YOU MAKE ANYTHING AT ALL WITHOUT THEM!!!

Well actually, I usually just write a script that automatically replaces every part/object in a game with a model of my choice.

I might consider trying packages because I do agree it seems like a SUPER useful feature.
Though one of the reasons I didn’t use them had to do with that it feels weird to me to have many duplicated assets in a game.

I care a lot about memory and over optimization.
Instead of having many trees and houses, I like to typically just have a bunch of boxes or invisible parts and when a player gets near then I can Clone() a model of a house or a tree where it needs to be.

This also results in a much smaller Roblox place file.
Though I’m not sure whether packages have this same effect.

I’ll definitely look into packages though.
I’ve been looking for an easier way to have scripts and frameworks in ReplicatedStorage and ServerScriptService auto-update.

Is this possible with packages too?

[desserts_yumyum]

@HealthyKarl

Will we ever get Local Packages, will we ever get the ability to make changes to Packages individually without overriding things, but inheriting updates?

hey @HealthyKarl quick clarification here - when you say “local packages”, I think you want these abilities:

1. Continuously receive updates from the “source” package while keeping the customizations you’ve made (right now, packages will require you to pick between receiving an update vs. keeping your modifications).
2. Be able to apply a certain override (e.g. apple tree package with override of apple color from green to red) at the place level to all instances in a place (i.e. “local” to a place)

Is this right? Am i missing anything?
We’re actively working on how we can enable these for packages! Let me know if you have any additional asks here.

[desserts_yumyum]

hey @Daw588 have you run into any of these issues recently? we’re trying to address these quality issues for packages.

[desserts_yumyum]

we’re working on an API that enables you to push content from repos (e.g. Github repos) into the Roblox asset system as packages! we’ll share more

[HealthyKarl]

Current Packages do the following… that I can’t even replace it.

Too much Cloud Involved.

It calls:

• https://develop.roblox.com/v1/assets/?assetIds=
• https://assetdelivery.roblox.com/v1/asset/?id=
• https://apis.roblox.com/asset-permissions-api/v1/assets/check-actions
• /v1/assets/latest-versions

Didn’t expect.

 

<Content name="PackageIdSerialize"><url>rbxasset://test.rbxm</url></Content>

That would result in AssetID 0. But I wanted it Instance based anyways.

My attempt was this, but that’s not what I meant with Local Packages. Even though eventually some might will find it interesting.

My fake local packages… I give it an invalid ID and create my own result

Which was this.

It was difficult to simulate Local Packages, and I made it “file system based”, while I was seeking Instance based.

Thing is I can’t re-replace it Roblox caches what it calls, so yep… But that is a “unstable” yet working Local Package method, just that the steps needed to achieve it break the rest of the features. But it’s proof that it is possible.

 

I meant this:

1. Have a new property that is not PackageId that is the same thing that ObjectValue can hold. A referent.
2. Instead of calling the APIs mentioned above, it will DIRECTLY compare the Referenced Instance and mirror the changes.
3. Changelogs and etc. aren’t needed it can be quick and fast.
4. Every other features from Packages, e.g. different Attributes and etc. should inherit just like Cloud based Packages.

 

@desserts_yumyum

Be able to apply a certain override (e.g. apple tree package with override of apple color from green to red) at the place level to all instances in a place (i.e. “local” to a place)

Thus would be completely new additonal features to customize Packages that would be cool. But local packages are more interesting.

[HealthyKarl]

@HealthyKarl

Right now, I could actually create a working simulation of Local Packages I think.

Local Packages, but it should be instance based:

Here is the simulation:

See how it says:

Published package The_Local_Source_Of_Packages has an older metadata format. Please republish it for better version control related supports.

Since it’s cloud based, thus would be something that the current PackageLink needs to be able to differentiate to give it different behavior.

But that video effectively has demonstrated a Local Version of Packages. The Feature is right infront of us, it just needs to be implemented.

Local Packages would not have version differences. If one wants that, use Cloud Packages. Local Packages serve only for Local purposes and faster and dynamic use while retaining other Package abilities.

[yipiokay]

I’d use it if we can have a Cloud API for downloading, modifying, etc

I want to be able to use this in CI/CD for deployment

Stay tuned, this is in our plans! Thanks for sharing this.

[bluestann]

can you share one or more specific examples of how you would use packages with the cloud? we are working on something along the lines of CI/CD deployment and interested in your use cases to make sure its covered.

[ChiIlDev (ChillDev)]

Wait, so what is the moral of the story? JK, this guide is super useful and detailed

[Maplestorm_0 (Maplestorm)]

@SCHLEEMPH

“Create a ‘crate’ package,

or you could say… “Crate” a package.

i recently found out about what packages actually did, theyre incredibly useful for experiences with multiple places so ill definitely get into them sometime…
this post really shipped packages for me, i think it wrapped the uses up pretty well!

i do mean everything i said though this post is very cool

[foodeggs7 (SubToParcIeDev_onyt)]

I found out what packages are this year it’s really useful since I was working on a game what should get much places and I also use it along with stylesheets modules for systems like admin system and custom leaderboard

If Roblox could add a feature where when you publish a package it automatically publish in live experience without first publiching that place

And maybe a possibility to get an not saved version (I forget always to publish changes when made) to fetch it from the package let’s we say I. PlaceX we have a cube of 6x6x6 as in the example and then in placeY we a decal on it then next time you work on placeX bit you forget to update so we could Click getdecelopmentvetsion and we get how it is in that place what it should update itt automatically on placeY or just love syncing packages I don’t know what my other teamembers think cuz what if you break the package but now if someone will add something it conflict the package another thing could be like how files work if it’s duplicated where you manually choose the version of a file like we say scriptx is edited then overwrite it but idk what does the community think

The b3st option could be a prompt what popup and let’s you publish packages if you edited it if it’s broken you could just click no what if not update maybe you can add a note then

[alexinite (alex)]

this thread should be named “Packages - what are they? Why arent you using them? Who even are you? Do you think you’re better than them? Are you even real?” for clarity

I’ve known about packages for a while but it would be nice to have a “sub-package” system that worked somewhat like a Git branch where when the super (original) package is updated it would not update and instead show you the differences visually and in properties. I think this should be true for packages in general to easily tell what has changed without committing it, but would be especially useful for sub-packages

[RuizuKun_Dev (Kitsune)]

Hello,

For my use case, I’d like the ability to download a Package as a .rbxm (model file) and then use a tool like Lune to insert it into the .rbxl (place file) that we’re deploying to our live game.

It would also be extremely helpful to have the capability to publish updates to the Package. We use Rojo and VS Code, so whenever our asset files are added, removed, or modified, I’d like to automate this process. Ideally, we could use a Lune script to interact with the Package API and publish these changes, possibly as part of a GitHub Action workflow.

The reason for this is to maintain separation of concerns for different asset types. For example, in one game, we have separate workspaces for DEV, Environment, UI, etc., and we use Packages to sync and share assets between these workspaces.

Having access to the Package API for downloading, creating, and updating (publishing) would make this process much easier and more efficient. We would continue using Packages to share assets between workspaces as static backups, to sync in Studio, and to insert the latest updates during runtime.

Adding a Cloud API for these functions would provide an additional layer of automation and improve our workflow significantly.

---

I also acknowledge that nested Packages are buggy so I always avoid it

I’d use Package API to do automated changes within my game, for example a Reusable Base Package, upon change I can use Lune to find all with a given tag then replace them with the newest version