Adding a watch mode in the debugger for a subset of entities

[benbrimeyer]

I did a bit of hacking to see how easy it would be to add a watch mode to Matter and got far enough that it felt warranted to add a feature request here to get more feedback.

Problem

Often when working on a particular feature within a game, I'll want to observe component state changes as my systems interact with entities. This can be hard to do when my games become complex with many many component types. My goal in this case is to observe changes on an "entity level" but the current debugger is better suited for "component level" indexing when trying to drill down to a specific entity.

A master list of all entities would not be very helpful and I usually only want to observe specific entities while developing the new feature before moving on.

Proposed solution

Introduce a "watch filter" in the world inspect panel to make it easy to access specific entities-of-interest when developing features. Defining "entities of interest" can differ from project-to-project or even day-to-day within the same project so it makes sense to offer more public debugger callback functions to inject project-specific behavior for this case.

⚠️ The following a proof of concept I hacked together, I'm not married to this for the actual implementation. Open to feedback/alternatives of course!

RobloxStudioBeta_dvExWzIBLd.mp4

The following demo works by exposing two callback functions on the debugger class:

queryForWatchedEntities

This callback function receives a world from debugger.debugWorld and allows the project to define which subset of entities we should watch. This expects a query as a callback since an entity-aware callback would be re-implementing a query, but I'm open to an alternative callback here that would receive an entityId instead of world if desired.

In the demo video, I've set the watch filter to only filter entities that match a query(Model) world query.

Example:

debugger.queryForWatchedEntities = function(world)
    return world:query(component.Watch)
end

labelForWatchedEntities

This is an optional callback and does not need to be defined with the previous callback. This callback provides a better developer UX when navigating an otherwise name-less list of entities to help pinpoint which entity we want to inspect. We expect this value to return some sort of string based on the given entity. We could recommend users to append a field on their previous Watch entity used in the queryForWatchedEntities callback or they could use any other method to label these entities as they'd like.

In the demo video, I've used the Model's datamodel name as the label.

debugger.labelForWatchedEntities = function(entityId)
    return world:get(entityId, component.Watch).name
end