Install Unity 2020.1.17f1 if you do not have it already
Go to "Installs" on the left side of Unity Hub pop-up window
Click "Add" and choose 2020.1.17f1
Once 2020.1.17f1 is downloaded, click on the three vertical dots menu (kebab menu) in the top right corner to add platform modules depending on your development and target platforms (OSX/Linux/Windows)
Include iOS Build Support if you plan on completing the AR Foundation section of this gitbook
Go to "Projects" in Unity Hub and click the down arrow to the right of "New" in the top left corner of the window to select 2020.1.17f1 and create a new 3D project, "Asteroids 3D XR Multiplayer"
Once you're in Unity, navigate to Package Manager from "Window"
Within PackageManager find the little "gear" icon and select Advanced Project Settings
Check the box next to Enable Preview Packages and also Show Dependencies at the bottom of the window
This will allow you to view the preview packages that are included included in the package manifest
Outside of the Unity Editor, navigate to your project folder (wherever you saved it locally) and open manifest.json (inside the Packages folder) with Visual Studio code or your choice of editor
These are all the packages that are currently included in your project
We are now going to manually add a new package, the Hybrid Rendering package
Add the following line to the manifest somewhere between the curly braces and save:
For the duration of this gitbook, we will almost exclusively be adding packages through the manifest
We now have an ECS project set up
created a new project
added hybrid renderer to the manifest
Sub Scene setup
First, some background:
Unity has no plans to sunset GameObject/MonoBehaviour functionality given how incredibly powerful and mature their workflows are. That's why Unity built tools and workflows for developers to support GameObject workflows while also utilizing DOTS (a sorta 2-in-1, you can use both!).
One such workflow is the use of "Sub Scenes." Unity gives you the ability to split your scene into several Sub Scenes, which you use to partition various GameObjects and Entities. When a Sub Scene window is open (a.k.a. 'editable'),it operates in "GameObject world." When a Sub Scene window is closed, it operates in "Entity-performant world" (so to speak).
How is this helpful? Here's an example: Visual artists can build GameObject assets in Sub Scenes, as long as they have the Sub Scene window open in Editor. When done editing, the visual artist closes the Sub Scene window, which triggers the conversion of these GameObjects into Entities. The Entities can be streamed in and out as needed. The conversion-to-entities allows for enormous environments (as demo'd in the Megacity walkthrough below). If all those entities had been game objects, it would absolutely destroy the performance of a normal authoring scene.
This is how it works: This conversion of GameObjects into Entities within a Sub Scene takes place either when (1) you hit Play in Editor while the Sub Scene is open at the time, or when (2) you close the Sub Scene from its Inspector.
The conversion process itself shouldn't take long at all, even for massive scale environments like the Megacity demo.
Right click on the Hierarchy window and choose "New Sub Scene" > "Empty Scene"
Name this Scene "ConvertedSubScene"
This will automatically create a new folder with the parent scene name
This will also automatically create a new folder called "SceneDependencyCache" which is used by Unity to help load/unload Sub Scenes
Select "ConvertedSubScene" in Hierarchy
Check out the settings in the Inspector
"Auto Load Scene" is selected true by default, which means this Sub Scene will automatically load its Entities when the scene is loaded
Double click on "ConvertedSubScene" and hit the play button
Notice there are no cameras in the Sub Scene so nothing renders
Return to "SampleScene" and hit the play button
Notice that the skybox renders because a camera is present
Adding a Sub Scene to the scene and naming it "ConvertedSubScene"
You can see how Unity is able to handle both GameObjects and Entities at runtime without adding a single Entity, Component, or System. The GameObject camera functions as expected even with a Sub Scene loaded into the scene.
Navigate to "Window" > "Analysis" > "Entity Debugger"
This window will be used to see the Entity, Components and Systems we are setting up
Click through the 5 entities and notice how their components and values are shown in the Inspector
Think of the current 5 entities as autogenerated Unity.Entities "boiler plate" for our current scene / SubScene setup
If you do not have 5 entities it is likely because your ConvertedSubScene is open which means it has not converted its GameObjects into entities
Navigate to the SampleScene, which closes the ConvertedSubScene
Still not working? Try saving, then reimporting the ConvertedSubScene by clicking "Reimport" in Inspector when ConvertedSubScene is selected in the Hierarchy
Not seeing 5 entities?
If you don't see all 5 entities, it's likely because Unity has not fully re-loaded yet. Your ConvertedSubScene might still be open, which means it has not converted its GameObjects into entities. To fix this, navigate to the SampleScene, which closes the ConvertedSubScene.
Still not working?
1) Try reimporting:
Try hitting save, then reimporting the ConvertedSubScene by clicking "Reimport" in Inspector when ConvertedSubScene is selected in the Hierarchy.
2) Try unchecking the box next to ConvertedSubScene in Hierarchy:
This checkbox toggles whether the Sub Scene is open for editing.
Here There be Dragons:
The Unity Editor can sometimes freeze up on your when reimporting assets with the Entity Debugger open. It eventually clears, but the delay can be upwards of a minute.
Setting up the Entity Debugger
We now are able to navigate Entities, Systems, Archetypes and see their associated data in the Inspector.
We now have a Sub Scene loading into our scene
We created a Sub Scene "ConvertedSubScene" in the Hierarchy
Opened the Entity Debugger and set "Show Inactive Systems" to true
Initializing game settings
First, some background:
To use Unity’s DOTS technology, you need to create entities, components and systems
The process that "converts" GameObjects (authoring data) and generates entities and components (runtime data) is called conversion.
This process is the preferred way of authoring ECS data
It is a fundamental part of DOTS, and not something temporary
Conversion is only about data, there is no conversion process for code
The overall workflow looks like this:
The Unity Editor is a user interface to work with authoring data
The conversion from authoring data to runtime data happens in the Unity Editor
The runtime (e.g. the game) should only ever have to deal with runtime data
Authoring data and runtime data are optimized for wildly different goals.
Authoring data is optimized for flexibility
Human understandability and editability
Version control (mergeability, no duplication)
Runtime data is optimized for performance
Loading time and streaming
A key observation is that nothing requires a 1:1 mapping between GameObjects and entities.
A single GameObject can turn into a set of entities, e.g. procedural generation
Multiple GameObjects can be aggregated into a single entity, e.g. LOD baking
Some GameObjects might have no purpose at runtime, e.g. level editing markers
The same can be said about components. A conversion system can read from any amount of Unity components and add any amount of ECS components to any amount of entities.
All those concepts get explained in further detail in the rest of this document, but it's useful to introduce some vocabulary beforehand.
A regular Unity scene, containing GameObjects, destined to be converted to runtime data.
A simple GameObject component that references an authoring scene and will either load the authoring scene (when the SubScene is in edit mode), or stream in the converted entity scene (when the SubScene is closed).
The result of converting an authoring scene. Because entity scenes are the output of an asset import, they are stored in the Library folder. Entity scenes can be made of multiple sections, and each of those can be independently loaded.