Search Unity

Runtime authoring in projects using ECS for Unity

March 22, 2023 in Engine & platform | 12 min. read
Runtime authoring in projects using ECS for Unity | Hero image
Runtime authoring in projects using ECS for Unity | Hero image
Share

Is this article helpful for you?

Thank you for your feedback!

ECS for Unity introduces a clean separation between Authoring Data and Runtime Data. Through the baking process, a majority of your GameObjects are transformed into Entities – a different data representation that has nothing in common with its GameObject source. To help you manage this new duality of data and build a better authoring experience on top of it, we are introducing a pattern called Data Modes.

This post aims to familiarize you with the ins and outs of this new pattern to help you make the most of new Editor workflows specific to projects using ECS for Unity.

The basics

To ensure we’re all on the same page, here are some essential terms:

  1. Authoring Data is anything that you modify while you iterate on your game. This is data saved on disk and version controlled. Authoring Data is transformed into Runtime Data when running or building the game. Scenes, prefabs, animation curves, and VFX graphs are all examples of Authoring Data.
  2. Runtime Data is anything that is part of the simulation while the game is running, either in Play mode in the Editor or in a built game. Runtime Data is never transformed into Authoring Data and is lost when the game stops running or you exit Play mode. Entities are examples of Runtime Data.

Historically in Unity, GameObjects have always been special in that they act as both Authoring and Runtime Data. GameObjects are what you use to assemble and configure scenes (authoring), but they are also what the simulation modifies while the game is running (runtime). We can’t determine with certainty which modifications were made by the game and which were made by you via the Editor, so this is why you’re not able to retain the modifications you make to your GameObjects while in Play mode.

In projects using ECS for Unity, this is no longer always the case. GameObjects can take the role of pure Authoring Data and be baked into Entities for increased runtime performance. This makes it easier to expose both the Authoring Data and the Runtime Data at the same time, since they now have distinct forms. In turn, this enables you to modify both or either, regardless of Editor mode or game state.

Data Modes

In a project using ECS for Unity, your Authoring Data has different types, structures, and properties than your Runtime Data. This means it’s impossible for the simulation to modify your Authoring Data – it doesn’t know or care about it. In fact, that representation of your data doesn’t even exist while the game is running. You should then be able to make modifications to your Authoring Data while the game is running – there’s no risk of corrupting your work anymore.

You also need the ability to decide which mode of your data is the most important to you at any given moment, depending on the context or task. Ideally, you would be able to go back and forth seamlessly.

With all of that in mind, we came up with the Data Modes pattern. It allows you to decide what representation of your data you interact with while making it extra clear what will happen to the modifications you make during Play mode.

There are three Data Modes: authoring, runtime, and mixed. Authoring and runtime are self-explanatory – you see either Authoring Data only or Runtime Data only. Mixed mode is more interesting, and truly shines when you are working on level design during Play mode. When you are in mixed mode, you see Authoring Data as much as possible. But wherever the runtime has taken over, you’ll see Runtime Data instead. In this mode, you can see a mix of authoring and runtime fields in the Inspector or a mix of GameObjects and Entities in the Entities Hierarchy. More on those two windows later.

The main components of the Data Modes pattern are: non-destructive Play mode authoring and live properties.

Non-destructive Play mode authoring

With a clear separation between Authoring and Runtime Data, it is possible for you to safely author your scene in Play mode. If you inspect an object and explicitly place its inspector in authoring mode, the modifications you make will be applied to your scene while in Play mode. The scene will be marked as “dirty” and you can save it exactly like you would if you weren’t in Play mode. Exiting Play mode will not undo any of the work you did.

This separation of Authoring and Runtime Data applies only to GameObjects inside subscenes, as they are being baked into their distinct runtime representation: Entities. GameObjects outside of subscenes do not benefit from this separation and serve as their own runtime representation, like GameObjects always did in Unity. In the context of Data Modes, a pure GameObject is considered a runtime-only concept during Play mode.

Live properties

Live properties appear in the Inspector in mixed mode while running the game. They exist on top of normal fields in a GameObject inspector and have some interesting properties.

First, they change the value you would see in a field if the inspector was in authoring mode. Instead, it displays the current value of the corresponding Runtime Data field. This is very important: what a live property shows you is taken directly from the Entity’s component data. It’s also worth noting that this is a two-way binding. If you edit this field, the changes will be pushed directly to the ECS data and be immediately apparent in the Game view while never going through your Scene file on disk.

Second, they have an orange bar as a clear visual indicator. The orange bar is a core concept: whenever you see it, you are dealing with Runtime Data and nothing you do to this data will survive exiting Play mode.

Live properties only apply to fields where a binding can be established. There needs to be a one-to-one relationship between the corresponding fields in Authoring Data and in Runtime Data.

The Transform fields have orange bars:  they are displaying Runtime Data. | The Cartesian Grid on Cube fields do not have the orange bar: they are displaying Authoring Data.
The Transform fields have orange bars: they are displaying Runtime Data. | The Cartesian Grid on Cube fields do not have the orange bar: they are displaying Authoring Data.

Workflow

The Data Mode switch

When using Entities, your main interaction with Data Modes comes through the Data Mode switch. It’s the circle above your Inspector window and the Entities Hierarchy window. Its state tells you – at a glance – what mode a window is currently in.

Depiction of the circles that appear above your Inspector and Entities Hierarchy windows that tell you – at a glance – what mode a window is currently in.

If you click the Data Mode switch, you will notice a fourth option called “Automatic” in the dropdown list. This is not a mode, but an option for the switch itself. It means that you enable Unity to control what mode your window should be in based on context (explained later in this post). If you explicitly select a mode from the list, you will effectively lock the mode for that window until you select automatic again. The locked state is represented on the icon by an underline.

Alternate depiction of the circles that appear above your Inspector and Entities Hierarchy windows that tell you – at a glance – what mode a window is currently in.

The orange bars

Orange bars appear in windows with the runtime or authoring Data Modes. These bars always mean that they are associated with Runtime Data. In the Inspector, they identify fields whose values will be reverted when exiting Play mode (see “Live properties” above). In the Entities Hierarchy, they identify GameObjects outside of subscenes and Entities (see “Non-destructive Play mode authoring” above).

When a window is in runtime mode, everything has an orange bar because you don’t have access to any Authoring Data in this mode. The intent is that, if you see orange, you automatically know that changes you make are temporary. These orange bars are a more localized version of what many developers use to remind themselves to not make changes: Play mode tint.

Orange bars in the Entities Hierarchy, in mixed mode
Orange bars in the Entities Hierarchy, in mixed mode
Orange bars in the Inspector, in runtime mode
Orange bars in the Inspector, in runtime mode

The Inspector window

The Inspector window is the most simple case. When you inspect a GameObject or Entity that has a counterpart in the opposite mode, you can toggle between authoring mode or runtime mode.

A couple of caveats worth noting:

  • Outside of Play mode, the runtime representation of your data is read-only.
  • Pure Entities and GameObjects don’t have an authoring representation in Play mode.

When its Data Mode switch is set to automatic, the Inspector window will try to respect whatever data mode the Entities Hierarchy is in, and fall back to showing you Authoring Data in edit mode and mixed data in Play mode.

The Entities Hierarchy window

The Entities Hierarchy window behaves mostly like the normal scene hierarchy in authoring mode. You see GameObjects, scenes, and subscenes, you can go into prefab isolation, etc. This is the default in edit mode.

In runtime mode, you see Entities, scenes, subscenes, and GameObjects outside of subscenes.

When its Data Mode switch is set to automatic, the Entities Hierarchy window will prioritize showing you Authoring Data in edit mode and mixed data in Play mode.

Conclusion

The Data Modes pattern can help you more easily manage the duality of data associated with the separation of Authoring Data and Runtime Data. Two key components of this pattern, Non-destructive Play mode authoring and live properties, make it possible to interact with both Authoring Data and Runtime Data simultaneously, enabling safe authoring in Play mode and real-time updates to Entity component data. This provides an improved authoring experience for projects using ECS for Unity.

For more information, check out this talk from GDC 2022. Some of the UX has since been updated, but the fundamental principles remain valid. As a bonus, this video showcases other tools to help you on your game-making journey with ECS for Unity.

If you want to discuss more about ECS for Unity, visit us in the forums. Be sure to watch for new technical blogs from other Unity developers as part of the ongoing Tech from the Trenches series.

March 22, 2023 in Engine & platform | 12 min. read

Is this article helpful for you?

Thank you for your feedback!

Related Posts