feat(debug_ui): performance, ECS inspector and console panels #878

Merged
SakulFlee merged 1 commit from feat/debug-ui-panels-v2 into main 2026-10-19 01:01:53 +00:00
Owner

A new orbital_debug_ui crate providing three floating Iced panels over
the game render, toggled with F1:

  • Performance — FPS, TDT and CDT, then every stage of
    FrameTimings as last/avg/min/max. This is the data that used to exist
    only as the once-a-second TIMING log line.
  • ECS — an entity-first tree: live entities, expandable to the
    component types each one holds and their current values. The world is
    flat, since nothing in the engine uses Parent/Children, so there is
    no scene-graph shape to show.
  • Console — the tail of the new log ring, filterable by level.

Each panel is a pure fn(&World) -> Element, which is the model
orbital_iced already uses, so there is no snapshot to keep in sync and no
per-panel program state.

The panels are registered as IcedLayerRenderer<DebugMessage> pushed
straight into register_overlays, rather than through IcedUiState.
That keeps their message enum out of the application's own panel
messages — a library should not force its messages on its users — and
avoids the module-ordering constraint IcedUiState implies.

Panel visibility lives in the DebugUiState resource and is checked by
each panel's view, not via IcedState::set_visible: the toggle is a key
press handled by an ECS system, so the renderer's own copy of the state
would never see it. A hidden panel renders a two-widget blank tree, which
still fills the window (the runtime builds one full-window
UserInterface per panel) but costs almost nothing to build.

The ECS tree is capped at 200 rows. A world can hold hundreds of
thousands of entities, and the tree is rebuilt every frame, so
materialising a row per entity would stall the render loop long before
the list was scrolled. Component values are truncated to 200 characters
for the same reason.

Release builds compile the module out entirely unless
allow_in_release(true) is set, so a shipped game pays neither the build
cost nor the per-frame panel cost.

The edge-detection state for the toggle lives in DebugUiState rather
than its own resource: the ECS has no IntoSystem impl taking two
ResMut parameters, so a toggle system cannot update two resources.

The all-in-one template's hand-rolled FPS HUD is removed — that is what
the Performance panel is for — and DebugUiModule is added to it and to
the multi_module example.

Also fixes a clippy lint in entity_components' sort from the ECS
introspection change.

A new `orbital_debug_ui` crate providing three floating Iced panels over the game render, toggled with F1: - **Performance** — FPS, TDT and CDT, then every stage of `FrameTimings` as last/avg/min/max. This is the data that used to exist only as the once-a-second `TIMING` log line. - **ECS** — an entity-first tree: live entities, expandable to the component types each one holds and their current values. The world is flat, since nothing in the engine uses `Parent`/`Children`, so there is no scene-graph shape to show. - **Console** — the tail of the new log ring, filterable by level. Each panel is a pure `fn(&World) -> Element`, which is the model `orbital_iced` already uses, so there is no snapshot to keep in sync and no per-panel program state. The panels are registered as `IcedLayerRenderer<DebugMessage>` pushed straight into `register_overlays`, rather than through `IcedUiState`. That keeps their message enum out of the application's own panel messages — a library should not force its messages on its users — and avoids the module-ordering constraint `IcedUiState` implies. Panel visibility lives in the `DebugUiState` resource and is checked by each panel's view, not via `IcedState::set_visible`: the toggle is a key press handled by an ECS system, so the renderer's own copy of the state would never see it. A hidden panel renders a two-widget blank tree, which still fills the window (the runtime builds one full-window `UserInterface` per panel) but costs almost nothing to build. The ECS tree is capped at 200 rows. A world can hold hundreds of thousands of entities, and the tree is rebuilt every frame, so materialising a row per entity would stall the render loop long before the list was scrolled. Component values are truncated to 200 characters for the same reason. Release builds compile the module out entirely unless `allow_in_release(true)` is set, so a shipped game pays neither the build cost nor the per-frame panel cost. The edge-detection state for the toggle lives in `DebugUiState` rather than its own resource: the ECS has no `IntoSystem` impl taking two `ResMut` parameters, so a toggle system cannot update two resources. The all-in-one template's hand-rolled FPS HUD is removed — that is what the Performance panel is for — and `DebugUiModule` is added to it and to the `multi_module` example. Also fixes a clippy lint in `entity_components`' sort from the ECS introspection change.
feat(debug_ui): performance, ECS inspector and console panels
All checks were successful
Lint / lint (pull_request) Successful in 16m31s
7d2d52d470
A new `orbital_debug_ui` crate providing three floating Iced panels over
the game render, toggled with F1:

- **Performance** — FPS, TDT and CDT, then every stage of
  `FrameTimings` as last/avg/min/max. This is the data that used to exist
  only as the once-a-second `TIMING` log line.
- **ECS** — an entity-first tree: live entities, expandable to the
  component types each one holds and their current values. The world is
  flat, since nothing in the engine uses `Parent`/`Children`, so there is
  no scene-graph shape to show.
- **Console** — the tail of the new log ring, filterable by level.

Each panel is a pure `fn(&World) -> Element`, which is the model
`orbital_iced` already uses, so there is no snapshot to keep in sync and no
per-panel program state.

The panels are registered as `IcedLayerRenderer<DebugMessage>` pushed
straight into `register_overlays`, rather than through `IcedUiState`.
That keeps their message enum out of the application's own panel
messages — a library should not force its messages on its users — and
avoids the module-ordering constraint `IcedUiState` implies.

Panel visibility lives in the `DebugUiState` resource and is checked by
each panel's view, not via `IcedState::set_visible`: the toggle is a key
press handled by an ECS system, so the renderer's own copy of the state
would never see it. A hidden panel renders a two-widget blank tree, which
still fills the window (the runtime builds one full-window
`UserInterface` per panel) but costs almost nothing to build.

The ECS tree is capped at 200 rows. A world can hold hundreds of
thousands of entities, and the tree is rebuilt every frame, so
materialising a row per entity would stall the render loop long before
the list was scrolled. Component values are truncated to 200 characters
for the same reason.

Release builds compile the module out entirely unless
`allow_in_release(true)` is set, so a shipped game pays neither the build
cost nor the per-frame panel cost.

The edge-detection state for the toggle lives in `DebugUiState` rather
than its own resource: the ECS has no `IntoSystem` impl taking two
`ResMut` parameters, so a toggle system cannot update two resources.

The all-in-one template's hand-rolled FPS HUD is removed — that is what
the Performance panel is for — and `DebugUiModule` is added to it and to
the `multi_module` example.

Also fixes a clippy lint in `entity_components`' sort from the ECS
introspection change.
SakulFlee deleted branch feat/debug-ui-panels-v2 2026-10-19 01:02:04 +00:00
Sign in to join this conversation.
No description provided.