Unity Packages Life Cycle
By now, you’ve noticed a plan for Unity involving packages, which has been steadily moving forward. The story kicked off with the ProBuilder announcement, and we’ve since followed up by introducing features of the Package Manager and improved Unity Project Management. Now, let’s dive a little deeper into the story.
Packages, what are they?
Packages will be everything. In the future, we expect to carve apart Unity into many pieces, each of which you will be able to update, experiment with and modify. All our new features are already planned to be delivered in this way: Scriptable Render Pipelines, Entity Component System (ECS), CineMachine, and so on.
Additionally, much of what lives in GitHub repos (NavMesh, Recorder, …), extensions ( GUI system, Networking, Timeline, etc.), and various Unity developed Asset Store packages will now be migrated into packages.
We are dogfooding our own tech, and once the system feels solid and robust, we will open the door for Asset Store publishers as well as general users to get in on the packages story in the future.
The main benefits of moving to packages revolve around speed, modularity and customer choice, and we aim to achieve this by making them:
- Referenceable or Embeddable
- Referenced, without needing to explicitly move/add files
- Embeddable, take a snapshot copy to have direct access to modify
- Access to source repos (where feasible)
- Ability to upstream and downstream changes
- Easy to update
- User interface makes it easy to see choices on versions and compatibility
- Automatic and explicit dependencies
- Clear dependency visibility and automatic dependency resolution
- The ability to add or remove as desired (allowing for dependencies)
How do packages work?
We expect packages to have a set of files that can be “virtually dropped” into your project where they will simply work. They can then be referenced from your game assets and scripts as needed. Each package has a definition file (package.json) that defines the version, lists explicit dependencies on other packages and the earliest version of Unity that supports the package.
Packages may contain:
- Regular assets
How are these different from Asset Store packages?
|Asset Store Package||New Package|
|File||.unitypackage||Git repo or .tgz|
|Location||Imported to Asset Folder||Referenced (or embedded) via Packages folder|
|Dependencies||Manual||Explicit and calculable|
|Removal||Manual / Difficult||Remove Reference or delete embedded directory|
|Updatable||Error prone / Difficult||Easy|
|Forkable||Manual||Easy, source available (when feasible)|
|Full Projects||Difficult to install||Templates from New Project dialog|
Packages Life Cycle
We are aiming to keep the package concept very simple, and fundamentally there are only two real states to consider:
- Preview == Not Production Ready, Use at your own risk.
- Released == Production Ready, fully supported.
One IMPORTANT extra label we apply to specific Released versions is “Verified For XXXX.Y,” indicating that a collection of specific released packages has been tested in one of the Unity release cycles.
This phase is idea genesis, early development, massive re-work, or in the midst of a complete update on a package. This is where development is the rawest, and changes can be significant.
From our point of view, we are exposing the direct development of our systems to the users, who can influence the direction and offer constructive feedback as things are built. In turn, it’s the riskiest place to be in terms of trying things out. You wouldn’t want to rely on a package in preview for your project, unless you’re also ready to fork and maintain things for yourself.
Versions in Preview are expected to precede the major.minor.patch version it lists. For example, this is a sequence you might see:
Some teams may also follow:
Both are acceptable, but the former has the clarity of no missed “Released” versions in between. (Arguably, 0 is by default preview versions, but we aim to be explicit.)
A package that’s had success in preview and shows promise with the users can move to release where it gets all the polish in place. While in release, we expect the Patch version of the package to be mostly updated for bugs and tweaks, with perhaps occasional minor version bumps with small improvements. The important part is to never introduce backwards-incompatible changes during a given major version release, which would require a return to Preview for that new major version.
At this point, we expect a Unity-developed package to have:
- Reasonable test coverage
- 100% API documentation coverage
- Basic user manual documentation
- API reviews for
- Naming conventions
- Security issues
- Upgrade issues
- Passed our package validation tests
- Checks for versioning
- Checks for import errors
Verified For XXXX.Y
Verified For is not a state, but as per Unity Version labels, we may apply to a released package. So a specific package, for example, com.unity.postprocessing at version 2.0.0, could be “Verified for 2018.1” and “Verified for 2018.2” if nothing changed between those releases, and it has passed through the Unity release testing cycle.
The Verified For label is something that can only be attached after a full Unity release testing cycle. What does that mean? Please read on.
Ok, what is a Unity release then?
Now that we explained the lifecycle of packages, let’s dive into what Unity releases will become. Unity will slowly be shedding functionality from the core into separate packaging with clear dependencies on Unity versions as required by the APIs.
As the numbers of packages proliferate, and with each package released individually, it will become harder to test the large combinations of what is available. So we will focus on a clear “verified for XXXX.Y” snapshot set that has been tested in concert for a Unity cycle.
This means, at the start of the Unity cycle, we will have picked the set of released packages we believe are in good standing in their candidacy, in other words, packages that have stabilized and are not under active development. These will be entered together to our builds, offered to Release QA, and tested together for the full cycle.
Timing is crucial on packages joining the set. Effectively, the start of the cycle means we’ve boarded the plane and pushed back from the gate. There’s no room for late additions before the flight takes off. With this rigor, we will test our utmost to ensure that all included packages are compatible with each other within the set. In some cases, we may find an unruly package, and drop it from the final set before release as testing progresses.
Wait, so many packages! That sounds like a lot of confusion!
To help navigate the proliferation of packages, we added the new Package Manager UI to Unity 2018.1. We are still improving and refining this Unity Editor window, but this will help you browse, view information and choose what packages you want to include in your project.
We’re also bringing in Project Templates, which are packages that are structured in useful configurations, which you can find on your Hub or Launcher. Project Templates include relevant packages to get you started in the right way for a given purpose. In the future, we expect Asset Store publishers to create new templates, as well as studios and users themselves.
Of course, every Unity release will still come with a default set of packages that we consider tested, useful and available with any new project created. As stated, one can always opt out of these selections, and still get the general Unity features and functionality you know and love.
It’s an exciting time for Unity in this transition. Our R&D is excited to be aligning ourselves closer to you all, the game developers, and to share more development, features, and choices at a faster pace. I hope you all look forward to the packages to come!
Q: Can two versions of the same package be present in the same project?
No, the project owner must resolve the issue by deciding which one is used and then testing how things work. Unity will add some intelligent automatic conflict resolution similar to NuGet’s. However, it still ultimately boils down to the project owner’s choice.
Q: Can a package be in multiple different states in the Package Manager?
Yes, for example, after a package has been released, a newer Preview version may become available with new features. The Package Manager will list all available known-compatible versions of a package for the editor used.
Q: Can multiple packages affect the same things and potentially cause a conflict?
Yes. We don’t have any examples of that yet, but it is something we do expect to occur.
Q: Can I downgrade a package to a prior version?
Possibly, but this is generally not recommended or supported. We intend to support the semver spec, and trying to step down a major or minor version may cause you to lose functionality, compatibility, and in the worst case scenario, introduce fatal crashes (for example due to utilizing older/non-existent APIs in later versions of Unity). Downgrading to a prior patch release may be safe, but it should be tested individually for your use. (As always, backup before testing.)
Q: Where do packages go in my project?
They’re referenced in the project manifest JSON file, but the actual files are elsewhere on your machine. A new person opening the project on a new machine may invoke a download to get that correct package at the specified version onto their machine to be utilized by the project.
Q: How do you override a package?
We haven’t yet finalized the details and functionality, but the general plan is to have a couple options:
- Embed a package, taking a snapshot of it and laying a copy of those exact files into your project (not in the Assets folder, but in the Packages directory)
- This option is useful for immediate fixes or similar temporary experiments
- The project version takes precedence over the cache
- Clone the source repo, git sub repo/submodule into your project
- Implementation is still in the works but allows you to fork, branch, merge changes coming downstream or even offer fixes upstream
Q: Does Package Manager automatically resolve and download dependencies?
Yes! However, clear conflict resolution display and choice is not yet implemented.
Q: Does upgrading completely replace the previous package?
Effectively yes. The new set of files in the new package version are pointed to, although any changes the package made to the Assets folder would remain. This is an advantage over the old unitypackage, which pushed things into the Assets folder and made it difficult to upgrade.