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

Extendable

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

Optional

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

Scripts

Documentation

Tests

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.

Preview

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:

1.0.0-preview

1.0.0-preview.1

1.0.0-preview.2

….

1.0.0

Some teams may also follow:

0.0.1-preview

0.0.2-preview

0.1.0-preview

…

1.0.0

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.)

Released

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 UIto 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.

Going forward

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!

FAQ

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

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.

We’re hoping to integrate the package server with the information about which packages you’ve purchased, so if you own the paid package it will just download automatically, and if you don’t then… it won’t :) For sure we will need to make sure there’s a good UX around all of that.

In the future it is said this will support Asset Store packages – if so, can one select which files from the asset store package to use? Generally one doesn’t want to include example folders from the package that show how it can be implemented (Adventure Creator, Dialogue System and others use this feature) because it would bloat the build.

All the details of exactly how that will work are still to be decided, but we know about that kind of thing. There’s multiple possible options, including e.g. turning Asset Store packages into multiple packages (one for the core asset, one for examples).

Can a package contain prefabs?
If an older version of a package become obsolete, can people still download the old version?
Is there a way to set auto-update to a package?
And can we, like in the asset store, use URI link to open package details in the editor?

A lot of corporations block access to other ports than HTTP, seems the package manager is using 443. This basically prevents them from using 2018.1 and forward, as the Package Manager can’t find any packages and crashes on trying to resolve the manifest. I had to experience that first-hand on a client setup and we had to revert back to 2018.1.0b10, which doesn’t crash.

Any plans to give a fallback option for downloading packages in such limited environments?

The port just shows in the error message Unity throws, maybe it’s just a sideeffect of the actual internal block. You can send me a PM or mail and we can discuss further, it’s a pretty serious issue right now.

If you don’t fully support “multiple versions in same project”, then you MUST fully support “downgrading always works exactly as well as upgrading does”. This isn’t negotiable: we have 30+ years of package managers that show one of these features is always essential (you can pick which one!).

Please don’t pretend that “source control makes it OK”. We already have the problem that by the time you install Asset X, you find you’ve been using incompatible versions of Asset Y for several months and source control is useless: you cannot simply roll-back 3 months of work (deleting it!) in order to satisfy compatibilty. Don’t make this worse, please!

Assuming no local package modification, a package is referenced by name and version.
So, moving backwards or forwards amounts to specifying the target version of the package you want.

That does come with the caveats of compatibility / dependency conflicts. We’ll be aiming to be explicit about the dependencies and version requirements.

Though, as described of your problem – it would highly depend on how backward compatible assets are once you’ve instantiated in the project. Flipping back to an older package would be “easy” though if you were using the newer APIs or assets, that obviously wouldn’t be compatible.

I suppose I can summarize that in the general case (non-forking / non-modifying), choosing to go back to an older package is easy, but there is no guarantees on compatibility.

Since you’ve said that UI System will now be available via package, can it get some love and finally get some new features/fixes? There’s many PR’s on Bitbucket lying there for years and you haven’t accepted any. Scroll Rect takes massive amounts of CPU and seems like the only commits which are accepted are new version tags, that’s all. If you won’t update it just please make it so that we (Users) can manually change the source code.

If I understood it correctly, instead of making a unitypackage file I will be able to share my own creations simply by providing a link (or something like that) of my GitHub repo? GitHub link registered into a website that manages packages?

The future expected options will include:
1) Link to github URL of a repo representing your package
2) publishing to the Unity registry, and offering “com.my-company.my-package” to be picked up and distributed in our package format (not unitypackage)

1. Probably not much, because in practice we _already_ strip out parts of the engine that you are not using (on platforms that support stripping, anyway). If you’re building for a platform like iOS, and you’re not using, say, 2D Physics, then the 2D physics module should not be in your build. There’s even a new API in 2018.1 that lets you find out which engine modules were included in your build and why. So, shipping something as a package rather than ‘built in’ to the engine just means that it changes from ‘included by default, then stripped’ to ‘excluded by default, then included if you add the package’ – the end result doesn’t change much.

2. Yes, the list of packages to use is stored on a per-project basis, not per-install, so you can absolutely have project A that has one list of packages and project B that has a different list.