DOTS Project Setup

Compared to creating a classic Unity project, a few additional steps are required for a DOTS project.

Package installation

Note

In all following steps, check each package's documentation to determine which versions of Unity are compatible with the package.

Starting with Unity 2020.1, the DOTS packages are not listed in the package manager, even when preview packages are enabled. There are two alternative options to install those packages:

  • You can use "Add package from git URL..." under the + menu at the top left of the package manager to add packages either by name (such as com.unity.entities), or by git URL (but this option isn't available for DOTS packages). Note that it might take a few moments before the package starts installing.
  • Alternatively, you can add DOTS packages by directly editing the Packages\manifest.json file in your project. This file requires not only the package name but also a version which can be found by looking at the documentation of each package (such as "com.unity.entities" : "x.x.x-preview.x").
Note

The use of a Git URL instead of just a name in the Package Manager requires having the git command line tools installed.

Follow the link for more information about installing hidden packages.

Check the overview of the currently available DOTS packages.

The recommended set of core packages to be added to a DOTS project is:

Domain Reload

In most DOTS projects, you'll want to avoid the slow Domain Reload that occurs upon entering playmode. To do this, under the "Edit > Project Settings > Editor" menu, check the "Enter Play Mode Options" checkbox but leave the "Reload Domain" and "Reload Scene" boxes unchecked. Keep in mind that you must be mindful of your use of static fields and static event handlers when Domain Reloads are disabled.

Standalone Builds

Making standalone builds of DOTS projects requires installing the corresponding platform package for each of your target platforms:

After installing the platform packages you need, create a "Classic Build Configuration" asset for each platform (via the "Assets > Create > Build" menu). The properties of that asset will contain a "Scene List", which is the only way of adding subscenes to a standalone project. Make sure you add at least one scene or that the "Build Current Scene" checkbox is toggled on.

Warning

Do not use the Build and Run menu "File > Build and Run" to build DOTS projects. It might work in some cases but this approach is not supported. You must build your project using the Build or Build and Run buttons at the top of the Build Configuration Asset Inspector window.

In particular, entity subscenes are not included in builds made via the Build and Run menu and will fail to load with the following error message showing up in a development build: "Could not open <path>/<guid>.entityheader for read".)

In order to connect the editor to a player and have the changes made to the authoring GameObjects synchronized, a Live Link Build has to be created. Simply add the "Live Link" component to the build configuration (and apply the changes).

The build configuration can now be selected in the Live Link menu (right of the Play/Pause/Stop buttons) via "Start Live Link ...". Make sure only one editor is running on the host machine, as having multiple editors running will confuse the player.