Crate jonmo

jonmo - Declarative Signals for Bevy

jonmo provides a way to define reactive signal chains in Bevy using a declarative builder pattern. Signals originate from sources (like component changes, resource changes, or specific entities) and can be transformed (map), combined (combine_with), or deduplicated (dedupe).

The core building block is the Signal trait, representing a value that changes over time. Chains are constructed starting with methods like SignalBuilder::from_component or SignalBuilder::from_resource, followed by combinators like SignalExt::map or [SignalExt::combine_with]. Signal chains must implement Clone to be used with combinators like combine_with or to be cloned into closures.

Finally, a signal chain is activated by calling SignalExt::register, which registers the necessary Bevy systems and returns a [SignalHandle] for potential cleanup. Cleaning up a handle removes all systems created by that specific register call by decrementing reference counts. If systems were shared with other signal chains, cleaning up one handle will only remove those shared systems if their reference count reaches zero.

Execution Model

Internally, jonmo builds and maintains a dependency graph of Bevy systems. Each frame, the JonmoPlugin triggers the execution of this graph starting from the root systems (created via SignalBuilder::from_* methods). It pipes the output (Some(O)) of a parent system as the input (In<O>) to its children using type-erased runners. This traversal continues down each branch until a system returns None (often represented by the [TERMINATE] constant), which halts propagation along that specific path for the current frame.

The signal propagation is managed internally by the JonmoPlugin which should be added to your Bevy App.

Modules

prelude

Commonly used items for working with jonmo signals.

utils

Structs

Combine

Represents a combine node in the signal chain definition. Implements Signal.

ComponentOption

Represents a node that extracts an optional component C from an entity signal. Implements Signal.

Dedupe

Represents a node that filters out consecutive duplicate values. Implements Signal.

Eq

Represents a node that compares the upstream signal’s value for equality with a fixed value. Implements Signal.

Filter

Represents a node that filters values based on a predicate system. Implements Signal.

Flatten

Represents a node that flattens a signal of signals. Implements Signal.

HasComponent

Represents a node that checks if an entity signal contains a specific component C. Implements Signal.

JonmoBuilder

A thin facade over a Bevy Entity enabling the ergonomic registration of reactive systems and children using a declarative builder pattern. Inspired by Dominator’s DomBuilder and Haalka’s NodeBuilder.

JonmoPlugin

The Bevy plugin required for jonmo signals to function.

Map

Represents a map node in the signal chain definition. Implements Signal.

MapBool

MapComponent

Represents a node that extracts a component C from an entity signal. Implements Signal.

MapFalse

Represents a node that maps a false boolean signal value using a system. Implements Signal. Executes the provided system f only when the upstream signal emits false.

MapNone

Represents a node that maps a None signal value using a system. Implements Signal. Executes the provided system none_system only when the upstream signal emits None, passing () via In.

MapOption

Represents a node that maps an Option<T> signal value using different systems for Some and None. Implements Signal. Executes some_system if the upstream emits Some(T), passing T via In. Executes none_system if the upstream emits None, passing () via In.

MapSome

Represents a node that maps a Some(T) signal value using a system. Implements Signal. Executes the provided system some_system only when the upstream signal emits Some(T), passing T via In.

MapTrue

Represents a node that maps a true boolean signal value using a system. Implements Signal. Executes the provided system t only when the upstream signal emits true.

MapVec

A map node in a SignalVec chain.

MutableVec

A mutable vector that tracks changes as VecDiffs and sends them as a batch on flush. This struct is Cloneable, sharing the underlying state.

Neq

Represents a node that compares the upstream signal’s value for inequality with a fixed value. Implements Signal.

Not

Represents a node that applies logical negation to a boolean signal. Implements Signal.

SignalBuilder

Provides static methods for creating new signal chains (source signals).

SignalDebug

Represents a node that adds debug logging to a signal chain. Implements Signal.

Source

Represents a source node in the signal chain definition. Implements Signal.

SourceVec

A source node for a SignalVec chain. Holds the entity ID of the registered source system.

Switch

Represents a node that dynamically switches between signals based on the upstream value. Implements Signal.

Throttle

Represents a node that throttles the upstream signal based on a duration. Implements Signal.

Enums

SignalEither

VecDiff

Describes the changes to a Vec.

Traits

IntoSignalEither

Signal

Represents a value that changes over time and handles internal registration logic.

SignalExt

Extension trait providing combinator methods for types implementing Signal.

SignalVec

Represents a Vec that changes over time, yielding VecDiff<T> and handling registration.

SignalVecExt

Extension trait providing combinator methods for types implementing SignalVec and Clone.

Functions

identity

A generic identity system that takes an input T and returns Some(T). Useful for signal graph nodes that just pass through data.

pipe_signal

register_signal

Helper to register a system, add the [SystemRunner] component, and manage [SignalNodeMetadata].