Add DirEnv to Orbital-CLI templates #868

Merged
SakulFlee merged 7 commits from feat/direnv-orbital-cli into main 2026-10-17 23:08:57 +00:00
Owner
No description provided.
Adds the read/write introspection surface that a debug inspector needs.
`Component` is already `Any + Debug`, so values can be read and written
dynamically; what was missing was any way to discover *what* exists.

New on `World`:
- `entities()` / `entity_count()` — iterate live entities. The
  `generations` and `free_indices` fields were private with no accessor,
  so there was no way to enumerate a world at all.
- `component_stores()` — iterate every registered store with its `TypeId`.
  Stores are registered lazily, so this only yields types that have been
  attached at least once. Order is unspecified; sort by type name if you
  need it stable.
- `type_id_of::<C>()` — forward lookup without attaching a component.
- `component_debug()` / `component_debug_string()` — read any component as
  `dyn Debug` by `TypeId`, with no static knowledge of the type.
- `entity_has_component()` / `entity_components()`.
- `set_component_any()` / `insert_component_any()` — write any component by
  `TypeId`. Both return a typed error on a value/type mismatch instead of
  silently doing nothing.

`WorldComponentStorage` gains `component_type_id`, `component_type_name`,
`entity_indices`, `component_debug`, `component_any`, `set_component_any`
and `set_or_insert_component_any`. All are implemented inside the existing
blanket impl for `ComponentStore<T>`, so they need no new bounds and no new
`unsafe`.

`World::component_debug` returns a `ReadComponentHandle`, which holds the
store's read lock and derefs to `dyn Debug` (plus `as_any()` for callers
that know the concrete type). That is what makes it sound to hand out a
value without a concrete lifetime.

Also fixes a latent bug in `ComponentStore::attach`: it pushed a new entry
and overwrote `sparse[entity_id]`, orphaning the previous value in
`dense`/`components`. So `World::attach_component` on an entity that
already had the component silently grew the store. It now replaces in
place.

Two new `ECSError` variants: `ComponentNotAttached` and
`ComponentTypeMismatch`.
Two pieces of data a debug overlay needs that today only exist as a
printed log line, or not at all.

`FrameTimings` (orbital_ecs_bridge) replaces the runtime's private
`TimingAccumulator`. That struct summed the 11 CPU and 3 GPU frame stages
and then reset itself every second before printing, so there was no
history and nothing an overlay could read. The new resource exposes:

- per-stage `last_ms`/`avg_ms`/`min_ms`/`max_ms`, which keep accumulating
  until `clear()` rather than resetting on each print;
- a bounded 240-frame history, per-stage and for whole-frame time;
- `try_log()`, which still emits the existing `info!` TIMING line at most
  once a second.

The one-second log window keeps its own totals, so emitting the summary
never perturbs what an overlay is showing. The log format is unchanged.

min/max are seeded from the first sample of a window rather than starting
at 0.0, which would pin `min_ms` at 0 forever since durations are never
negative. `clear()` zeroes the derived statistics instead of leaving a
stale `avg_ms` behind.

`orbital_core::logging` gains an in-memory ring of the last 1024 records
(`LogLine { level, target, message }`), readable via `log_buffer()` or
`with_log_buffer()`. There was previously no in-memory capture at all:
everything went to stdout and `game-N.log`.

Two fern quirks shaped the implementation:

- A chained `log::Log` sink sees the *decorated* record, because
  `FormatCallback::finish` rebuilds the record with the formatted args. So
  the capture happens in the `format` closure instead, which still gets the
  raw record.
- The level filter had to move from the inner chained dispatch to the outer
  one: fern checks `shallow_enabled` before invoking `format`, so a filter
  on the inner dispatch would let the buffer capture records the log itself
  drops. Filtering is equivalent, and the global max level is now the
  configured one rather than Trace.

The Android logger is not fern-based and is not wrapped, so its buffer
stays empty; that is called out on `log_buffer()`.
Two changes to the Iced bridge, both needed before a debug overlay can be
built on it.

## Generic messages

`IcedState` and `IcedLayerRenderer` are now generic over their message type,
defaulting to `Message`. A panel with real interactions can declare its own
enum instead of encoding everything as `ButtonPressed(String)`.

No bridge-message wrapper is needed: `shell::Bus<M>` is already typed by the
view's message, so `process_events` receives `M` directly and the caller's
messages never have to be packed into a type-erased payload.

`handle_message` takes `&mut World`, so a panel can apply whatever change its
message describes. `M: PartialEq` is required so the close button can be
recognised and hide the panel whatever the message type; the default
implementation still just logs the close.

`IcedUiState` is unchanged and still `HashMap<String, IcedState<Message>>`,
so the CLI template compiles as-is. Because the close button used to be
attached implicitly, `IcedBridgeModule` now applies the two built-ins
explicitly (default button view, `Message::ClosePanel`) to panels declared
through that resource — otherwise generalising the close button would have
silently removed it from every existing panel.

Panels with their own message enum should push an `IcedLayerRenderer<M>`
into `register_overlays` directly, which also avoids the module-ordering
constraint `IcedUiState` imposes.

## One build per frame instead of two

`process_events` (in `update()`, before game systems) and `render` (in
`redraw()`) each built the panel's `UserInterface`, so every frame did two
full `diff` + `layout` passes per panel. Worse, `render` re-read and re-routed
the *same* cloned event list, so every iced event was processed twice per
frame: messages were handled twice and the touch/drag capture bookkeeping ran
twice.

`process_events` now keeps the built interface, and `render` only draws it and
composites. The widget tree `render` used to rebuild was only a second after
the game systems, so a panel is at most one frame stale.

A hidden panel (`is_visible() == false`) is now skipped entirely — no view, no
layout, no draw pass — instead of building a full-window placeholder and
presenting it.

The `Cache` is reclaimed from the previous interface via `into_cache()` before
each rebuild. This is load-bearing: without it the cache would be empty on
every build and scroll offsets, text cursors and hover state would reset each
frame, so the panel would be unusable.

Behaviour change worth knowing about: a message handled in `process_events`
now shows up in the drawn tree on the *next* frame, so button state lands one
frame later than before.
feat(cli): auto-install orbital CLI via direnv and template devshell
Some checks failed
Lint / lint (pull_request) Failing after 2m39s
4646a6622a
The dev-shell shellHook now keeps a project-local `orbital` on PATH in
.cargo/bin (survives direnv reloads, no flake rebuild). Source precedence:
ORBITAL_CLI_PATH, then the local Crates/orbital_cli, then the Forgejo git
repo. Engine checkouts rebuild only when the CLI sources or Cargo.lock are
newer than the installed binary; generated projects install once and can
refresh with `orbital-update`.

`orbital init` now generates a .envrc + flake.nix for every template. The
flake forwards the engine flake's dev shell, so generated projects get the
Rust toolchain, engine system dependencies and the CLI without a local
Orbital checkout or engine compilation.
fix(ecs): use sort_unstable_by_key to satisfy clippy
All checks were successful
Lint / lint (pull_request) Successful in 2m18s
ae2f67d5e6
Clippy 1.98 flags `unnecessary_sort_by` on the entity_components sort, failing lint CI with -D warnings.
SakulFlee deleted branch feat/direnv-orbital-cli 2026-10-17 23:08:57 +00:00
Sign in to join this conversation.
No description provided.