Feedback request: Envisioning new ways to debug in DOTS

[KjartanK_Unity]

We’ve been hard at work designing and building the tools for how you navigate, inspect, and debug the data behind your DOTS-based game. We wanted to share some of that work with you here to start gathering some feedback on how it might impact your work. These features are in various stages of development so you may see feedback addressed either in the initial release or in a follow-up iteration. We’ll also be more active in the future posting about our plans for Editor workflows around DOTS.

For us to best apply your feedback, it would be helpful if you can share motivations or goals behind what you’re trying to accomplish when you need a particular piece of information or the ability to perform a certain action.

Systems Window

We’ve heard and read a lot of feedback about how we visualize the Systems you have running and we’d like to take a first step towards addressing some of that. Some of the first things we’ve heard and are looking to address include clarity around what type (standard, group, command buffer) a System is, easier to read and distinguish query types, and lack of visualization of scheduling dependencies.

Our design goals for this window include (1) giving you a clear view of the order in which Systems are running in your World and why, (2) better visualizing what a System is doing in terms of queries it runs, and (3) clearer indication of what component types make up a query. We’ve shared some mockups of various states below.

Separating this information into a separate window also allows for more flexibility in how relationships to other information are shown, including for example which Systems have queries matching an Entity.

Please share your thoughts on how this redesign of how you see your Systems affects your workflow, what value it brings, and what improvements you’d like to see moving forward.

To address one potential question, this is the first step in creating a better experience for all of the information and workflows that you today find in the Entity Debugger. We’ll eventually be removing the Entity Debugger, but not until we have full feature parity and confidence that the new tools are more usable and useful.

Entities Window

We’ve heard your concerns about the lack of ability to browse through your Entities, so we’ve tried to bring a familiar perspective on your runtime data by putting together a view of the Entities in a World as a transform hierarchy (we’re also exploring giving you the ability to group and organize by other components). We’re looking to make some improvements to how you search and filter in such a data-heavy environment as well.

Our design goals here are to (1) give you an Entity-first view into your World, (2) allow you to navigate your data in a way familiar to you as a Unity user (via transform hierarchy), and (3) to start showing you relationships that your runtime data (Entities) has with the authoring data (GameObjects) that created it and the Systems that act on it.

For the Entities window, we’re interested to hear what value you think this will bring to your workflows, what you could imagine using it for, and if there are any other ways you mentally organize the Entities in your game. Additionally, are there any opportunities to build on this that this inspires?

Thank you for reading and sharing your feedback! As mentioned, we’ll share more in the future to gather more feedback on other tools and workflows we’re crafting to improve your DOTS working experience.

[Kender]

Wow, awesome!

I hope there’ll be no negative time displayed for slow systems. Even if it takes 3600+ seconds to run. No good system will run this long, but if one does, I need to see it in order to fix. And would’ve been awesome if the systems that wait for something weren’t reporting they are taking this time, butt the slow systems that make everyone wait, were taking and reporting it instead.

Entities window is also amazing. I’ll be able to tag different groups of entities and filter them by tag! Show me everything trading-related! Now — everything ai-related!

Will the entities be editable via the inspector?

[TLRMatthew]

Will the Systems window be able to display sync points as well? Being able to see where sync points are being triggered without opening up and deciphering the Profiler (and even better, WHY the sync point was created) would be an amazing workflow improvement!

[Arowx]

Cool just what I was asking for in the API thread yesterday…

If this provided CPU usage and Memory Bandwidth usage % as well as a system throttling mechanism* then we could fine tune our systems for optimal performance.

• Thread limits and/or ms per frame heuristics and/or memory bandwidth priority or percentage limits.

[JakHussain]

Selecting entities in the scene view is a big deal for a lot of workflows. I’m sure you guys are already aware of the open source solution someone made over a year ago and it’s still supported. Selection of an entity in the scene view to highlight it in the entity window and vice versa is a must for production readiness.

And as others have said, editing entities in the inspector during play mode. @tertle was first to discover how this could be hacked into working as of Entities 0.8 but exposing this by default would do wonders for iteration time.

[Smilediver_1]

Please add some way to visualize dependencies between entities as graphs. For example, let say you have this:

struct Parent: IComponentData {
    [EntityParentField] // this marks that field is used as entity's parent
    public Entity Parent;
}

and you have Entity 2 with this component pointing to Entity 1. This could be shown in a graph like this:

+--------+
|Entity 1|
+--------+
    |
    |   +--------+
    |   |Entity 2|
    |   +--------+
    +-->|Parent  |
        +--------+

[JesOb]

Few notes:

• Make full featured Inspector for entities:

• With ComponentDrawers, FieldDrawers, PropertyDrawers (to show computed data in inspector) and ArchetypeDrawers(QueryDrawers). Last one will be very useful for drawing domain model e.g. mob entity in game with entire it state that is actually spread across many components and may be even entities. It is ok to see data from one component in few ArchetypeDrawers simultaneously. May be even draw all matching Archetype drawers on top of inspector following ComponentDrawes. And add switch to show or hide ArchetypeDrawers in inspector.

• Entities can be composed from pretty big amount of components related to different systems so we need to be able to filter them in inspector. And allow to create named filters for fast workflow.

• Mode to show all components of Entity (and all data inside) in inspector, not only public one and be able to edit it (it is just data overall) Additionally mode that show alignment and empty spaces inside components, size of each component in bytes and size of entity. Is essential for performance optimizations in DOTS. May be in this view show cache line size on platforms i.e. 32 or 64 bytes and now component fit it.

• Entity can have pretty big amount of components and monitor space is finite so please make Entity inspector simple dont use empty lines where it is not necessary. e.g.:

• sort tag compoennts to be first and in one wrapped line.

• make component with single field ‘Value’ to not show field name and just show ComponentName following actual value e.g.

• Make able to switch to raw view (may be even description view and layout view) per component not only entire inspector. May be just if we have few drawers for component in project allow us to select default one and switch between them in inspector (may be by clicking component icon) . Then we can by our self create few drawers for Description, Layout and another useful info about component. Switch View for all components in inspector. e.g. we can switch inspector to DescriptionView and instead of component data will see description of every component following it name. It will greatly help understand what each component is for and why it on my entity.

• Make IBufferElementData you know reorderable

• Entities window

• Get rid of duplication in hierarchy
  

• 4 pillars to work with big data (probably millions of entities)

• Pillars:

• Sorting

• Filtering

• Grouping (SubGrouing)

• CustomTree

• Make able us to sort entities by different criteria, filter them in any way we want, and group by our rules that we can define e.g. @Smilediver proposal.

• Allow to save any sort and filter criteria for fast workflow, and may be even define in code so it will appear for every team member.

• Custom Tree is tool for us to make custom tree like view of entities as plugin to entities window not as separate windows where we need to do all manually. May be custom tree will be compound from already sorted, filtered and pre grouped set of entities.

• Systems Windows looks nice can not add anything for now

• Authoring link

• Actually dont want to have separate hierarchy and Entities window but dont know how to avoid this for now so it is just note. May be someone have ideas.

• Want to have conversion on the fly. For now we have to open SubScene for editing and entities get removed replacing with GameObjects. Looks bad. Want game objects to be just like editor data representation but actual view to be rendered from entities. So I open subscene for edit. Start change some props in GO, system convert this on the fly into existing entity and I can see changed data in entity and actual changes in scene view. So GameObject will be just another way to change entity data, create and destroy them (primary way for Authoring). So MeshRenderer on Converted GO will not actually added to rendering, it converted to entity and entity added to rendering. Same with Physics and others.

• One more time Please make GO Authoring to be tool only for changing actual entity data.

[Arowx]

Will we also need some kind of system entities flow graph or in/out entity data?

And links between entity types and systems that use them?

[JesOb]

We often have workflow to run game (enter play mode), tune GameObjects and then copy good tuned data back to editing stage. There is request for it to work for a decade. Developers just use some assets from store, to do this, or some hand crafted tools.

With DOTS conversion workflow this become even harder to get changes back to Authoring representation.

So we need some way to convert data back to authoring.

[jdtec]

Good to see debugging getting some more attention!

1. Click to select entities in scene and display data in the inspector, so what @JakHussain said. Also, strongly agree with @JesOb point about being efficient with space for showing the component data and not wasting lines. It struck me already that it’s not displayed that efficiently when using the Entity debugger.

2. Editable data for entities in the inspector, like others have requested.

3. Debug draw and log functions working from bursted jobs without having to rewrite or wrap them. (within minutes of me posting this I see @xoofx has posted saying the new burst has “partial support for Debug.Log” which is great.

[JakHussain]

@jdtec touches on a great point with drawing debug lines in ecs! Another huge workflow necessity!

[Roycon]

Could we get support for custom worlds which are not updated via the built in ways?
I’m updating my worlds manually with World.Update and the Systems window is blank for those worlds

[calabi]

I’ll just add my tiny feedback it would be great to be able to see the Systems and enable or disable them in the editor before the program is run.

[KjartanK_Unity]

Thanks for this first set of responses! I want to summarize what I’ve read so far and ask a couple of clarifying questions:

First, on the Systems window:

• You’d like to see the Systems being scheduled without having to enter play mode
• You want it to support a custom World manually ticked via World.Update
• In order to optimize, you want to be alerted to Systems triggering sync points as well as the cause of those sync points
• Also to optimize, you’d like Systems to accurately report excessively long execution times (no negative times) and if one System is waiting for something else to finish you’d prefer that “something else” to be the reporter of that wait time rather than the waiting System

Next, the Entities window and browsing Entities:

• In general it seems the ability presented here to browse the Entities in your World will be helpful
• This needs to have robust filtering, sorting, and customizable grouping functionality (fortunately this is on our requirements list)
• @Arowx you asked about “links between entity types and systems that use them,” do you mean the ability to select an Entity and see Systems with matching queries (or select a System and see Entities matching its queries), or do you mean something else?
• @Smilediver_1 mentioned you’d like to visualize Entity dependencies as a graph; why would you prefer a graph over a hierarchical tree-view for the use case you presented? Do you have additional use cases where a hierarchical tree-view may not be sufficient?
• You need to be able to select an Entity directly in the scene view

Now, there’s inspecting Entities:

• You want a fully-featured Entity inspector including a few things:

• Customized component inspectors

• “Debug” mode (both full inspector and component-by-component)

• Entities can have a lot of data on them, so you want to be able to navigate that data and you want us to economically use the space (the suggestion of components with only a ‘Value’ field is an interesting one)

Then, iterating during play mode:

• Before summarizing these items I want to set some context of our hypothesis:

• We believe there are two primary cases for editing data during play mode: iterating on/experimenting with content and debugging data/functionality.

• For the first, we think those are changes you want to make and potentially keep, and they are changes that you want to work with the authoring format of your data for (for familiarity, especially for people filling designer or artist roles)

• For the second, we think you need to have fine-tuned control of the runtime data and you want to work with what the runtime Systems see but that you don’t need to keep most changes.

• That said, our goal is to create an experience where the optimal workflow for iterating on your content is through your familiar authoring-format data and the best workflow for diving in and debugging or figuring out how something works is by having access to your runtime data.

• The biggest concern with editing runtime data is that those changes are even less permanent than editing GameObjects during play mode in classic Unity today because even a change to authoring data during runtime could cause a re-conversion and erase your runtime data changes. Because of that, we want you to be able to edit your runtime data directly, but we want you to be aware of the risks.

• On to the feedback:

• You need to be able to edit Entity data directly

• @JesOb said “please make GO authoring to be tool for only changing actual Entity data,” can you clarify what you meant here?

Finally, there were some things related specifically to profiling and debugging that I wanted to separate out:

• You want more specific Systems profiling with things like CPU usage, memory bandwidth usage, and more
• You want to see a component’s data layout and the size it uses so you can optimize it
• You need to draw debug lines and send debug logs

Thank you for the great feedback so far! Please keep it coming and let me know if you feel I’ve missed or misunderstood anything.

[brunocoimbra]

@KjartanK_Unity

@Smilediver_1 mentioned you’d like to visualize Entity dependencies as a graph; why would you prefer a graph over a hierarchical tree-view for the use case you presented? Do you have additional use cases where a hierarchical tree-view may not be sufficient?

Hierarchical tree-view is good for parent-child relationships, but in DOTS I usually think of my data as I would when structuring a database, so having a visualization similar to a database relationship diagram would be a dream becoming true.

[DreamingImLatios]

This is more of a complaint of the current Entity Debugger, but I figured I would post it here.

So I add the TransformSystemGroup to multiple ComponentSystemGroups through code. It is important that I use the same instance of the group because of how change filtering works. The actual gameplay works fine, but the Entity Debugger complains about it.

[Arowx]

@KjartanK_Unity

@Arowx you asked about “links between entity types and systems that use them,” do you mean the ability to select an Entity and see Systems with matching queries (or select a System and see Entities matching its queries), or do you mean something else?

Imagine I want to be able to :
Track data through the systems maybe I’ve built or purchased a set of complex systems but there is a bug in the data. I can’t find a bug in the system that “finds the bug”, how do I quickly back track the data to find the system that created the buggy data?

I’m hitting performance problems due to memory bandwidth limits but it’s only happening as occasional glitchy FPS drops. I need to be able to see the systems memory and CPU bandwidth utilisation and also work out where the log jam of data is being generated e.g. I find the glitches are in a generic movement update system that just adds two vectors but then need to backtrack to find out what systems generated the extra load.

[Kolyasisan]

One thing that would help tremendously IMO is the ability to select entities in the scene view. Even if it were to be based on raycasting against colliders or meshes (naturally), it would still help nicely, especially alongside the entity window.

[Arowx]

Please note when I refer to Bandwidth it’s not just RAM bandwidth or PCI GPU bandwidth, as modern CPUs and GPUs have several layers of memory caches each one has bandwidth limits before the next cache is needed and the performance of operations drop. e.g.

Notice the data access range and the latency in clock cycles. If you could highlight how the bandwidth of our DOTS processes and entity pools fit into these latency steps it could be very helpful to developers, although it might be complex to do as it’s very hardware dependent.

Also don’t forget code takes up memory and cycling systems through cores uses up memory bandwidth. So in theory a DOTS systems with high system counts even with relatively small entity pools could hit performance issues due to code bandwidth. So there might be sweat spots for code size and data size on target hardware that your system should help developers find…

[JesOb]

@KjartanK_Unity

• Before summarizing these items I want to set some context of our hypothesis:

• The biggest concern with editing runtime data is that those changes are even less permanent than editing GameObjects during play mode in classic Unity today because even a change to authoring data during runtime could cause a re-conversion and erase your runtime data changes. Because of that, we want you to be able to edit your runtime data directly, but we want you to be aware of the risks.

• @JesOb said “please make GO authoring to be tool for only changing actual Entity data,” can you clarify what you meant here?

It looks like you already have something like this in bold text. It is mostly about get rid of middle state and go right from authoring components to Entity representation.

So RigidBody MonoBehaviour will never create body in PhysX it will be converted to entity with Unity.Physics component right away. Same with MeshRenderer and others. So we will never see Mesh Renderer rendered through old system we will author MeshRenderer but it will be converted inplace into entity and rendered with HybridRendering right in Editor.

This is base idea that GameObject authoring is just for authoring but under the hood everything will be converted inplace and work through entities. So we will see our Authoring data in Hierarchy and converted Runtime data in Entities while editing.

P.S. It is not about editing but I have actually dont want to have [GenerateAuthoring] attribute. Actually want to be able to add IDataComponent to GameObject may be through MonoBehaviourContainer, so in code I have the only data type and methods that can author it without dealing with 2 similar data type one struct and one MonoBehaviour and convertion to each other in editor scripts.

Conversion is good thing for complex systems but overcomplicated for simple ones.