voxel-framework 0.10.0

A reusable voxel engine framework built on Bevy
Documentation
# Author-defined retained HUD

`VoxelHudPlugin` is an explicit, game-neutral presentation plugin. Your game
registers retained element definitions in `HudRegistry` and publishes
screen-ready values in `HudValueSet`; the framework does not decide what an id
means or query gameplay state on your behalf.

The plugin is non-generic, has no Cargo feature, and is not included in
`UiPlugin`, `VoxelCorePlugin<V>`, or `VoxelPlugin<V>`:

```rust
use bevy::prelude::*;
use voxel_framework::prelude::*;

App::new()
    .add_plugins(DefaultPlugins)
    .add_plugins(VoxelHudPlugin);
```

It may also run headlessly with `MinimalPlugins`. An empty registry is valid.

## Register definitions

Definitions are ordinary Rust data. The supported retained presentations are
text, continuous bar, fixed or value-bound icon, and bounded repeated segments.
Placement supports nine screen anchors, pixel offsets, stack direction, and
stable signed ordering.

```rust
fn register_hud(mut registry: ResMut<HudRegistry>) {
    registry
        .register(HudElementDefinition::new(
            "sample.text",
            HudPresentation::Text(HudText::new("sample.text.value").prefix("Text: ")),
        ))
        .expect("sample.text should be unique and valid");

    registry
        .register(
            HudElementDefinition::new(
                "sample.bar",
                HudPresentation::Bar(HudBar::new("sample.bar.value")),
            )
            .placement(HudPlacement::new(HudAnchor::TopCenter))
            .fallback(HudScalar::new(0.0, 0.0, 1.0).unwrap()),
        )
        .expect("sample.bar should be unique and valid");

    registry
        .register(HudElementDefinition::new(
            "sample.icon",
            HudPresentation::Icon(HudIcon::bound("sample.icon.value")),
        ))
        .expect("sample.icon should be unique and valid");

    registry
        .register(HudElementDefinition::new(
            "sample.segments",
            HudPresentation::Segments(HudSegments::new("sample.segments.value", 5)),
        ))
        .expect("sample.segments should be unique and valid");
}
```

Use `register` when duplicates are mistakes. Use `insert_or_replace` only when
definition replacement is intentional. Equal replacements are no-ops, while
real changes advance the registry revision and reconcile the existing retained
tree.

## Publish values

`HudValue` is a closed presentation vocabulary: `Text`, validated `Scalar`,
`Count`, `Bool`, and owned icon asset path. It is deliberately not a gameplay
model. Convert domain state into these values in systems owned by your game.

Use `set_hud_value` when you want both real-change detection and a
`HudValueChanged` message:

```rust
use bevy::ecs::message::MessageWriter;

fn publish_values(
    mut values: ResMut<HudValueSet>,
    mut changed: MessageWriter<HudValueChanged>,
) {
    set_hud_value("sample.text.value", "alpha", &mut values, &mut changed);
    set_hud_value(
        "sample.bar.value",
        HudScalar::new(0.5, 0.0, 1.0).unwrap(),
        &mut values,
        &mut changed,
    );
    set_hud_value(
        "sample.icon.value",
        HudValue::icon("icons/sample.png"),
        &mut values,
        &mut changed,
    );
    set_hud_value("sample.segments.value", 3_u32, &mut values, &mut changed);
}
```

The helper does not emit a message for an equal value. `remove_hud_value`
likewise emits only when a value existed. Direct `HudValueSet` operations remain
available when messages are unnecessary.

## Scheduling and retained updates

Register definitions during `Startup`; `VoxelHudPlugin` reconciles and renders
them during `PostStartup`. Put dynamic publication systems in
`HudSystemSet::Publish` when values must reach retained UI state in the same
`Update`:

```rust
app.add_systems(Startup, register_hud).add_systems(
    Update,
    publish_values.in_set(HudSystemSet::Publish),
);
```

The public order is `Publish` → `Reconcile` → deferred-command barrier →
`Render`. Definitions and theme revisions trigger structural reconciliation;
value updates change only affected presentation components. Unchanged frames do
not rebuild element trees, and each element keeps its root entity identity.

## Fallbacks and diagnostics

Missing values, incompatible kinds, invalid scalars, excessive segment counts,
and unavailable image assets never panic. By default the affected element is
hidden. A definition may provide a compatible `.fallback(...)` value instead.
Resolution failures emit `HudDiagnostic` when the active failure state changes,
rather than repeating the same diagnostic every frame.

Image paths are owned author data. The renderer resolves them only when an
`AssetServer` is present. With `MinimalPlugins`, icon paths remain inspectable
values but no asset I/O occurs and the icon resolves to its safe hidden state.

## Inspection

`HudRegistry::snapshot()` and `HudValueSet::snapshot()` return deterministic,
id-ordered snapshots. Use them for tests, diagnostics, and tools. They do not
define a file format, persistence contract, configuration language, or JSON
schema.

## Coexistence and migration

`VoxelHudPlugin` does not replace `UiPlugin` or any custom Bevy UI. They can be
composed side by side:

```rust
app.add_plugins((UiPlugin, VoxelHudPlugin));
```

To migrate an existing overlay incrementally:

1. Keep the overlay and its game-owned queries unchanged.
2. Register one equivalent neutral HUD definition.
3. Move that overlay's presentation-ready output into a game-owned publisher in
   `HudSystemSet::Publish`.
4. Remove the old UI entity only after the retained element is verified.
5. Repeat element by element.

The framework intentionally provides no automatic stats/effects/content bridge,
player discovery, thresholds, rules, interactions, vertical presets, arbitrary
layout language, animation system, or JSON/YAML configuration. Those choices
belong to the consuming game.

## Headless example

The bundled example registers and updates all four presentation kinds across
multiple frames, then prints deterministic values without opening a window or
reading assets:

```sh
cargo run --example hud
cargo run --no-default-features --example hud
```

See [`examples/hud.rs`](../examples/hud.rs) for the complete source.