Crate bevy_mod_config 

A modular configuration framework for Bevy applications, decoupling configuration access and change detection from management utilities like persistence and UI.

Getting started

First, decide which Managers you want. Managers extend the framework with extra capabilities for your config fields, such as saving and loading from a file (manager::Serde) or showing a live editor panel in your game (manager::Egui). Multiple managers can be composed as a tuple; use () if you don’t need any yet.

Declare your chosen managers as a type alias — you will pass it consistently to every init_config call. For example, to use both a JSON serializer and an egui editor:

pub type ManagerType = (bevy_mod_config::manager::serde::Json, bevy_mod_config::manager::Egui);

Now we can define the configuration data model as required. Multiple configuration roots are supported, so each plugin can define its own configuration with #[derive(Config)]:

use bevy_mod_config::Config;

#[derive(Config)]
struct VideoSettings {
    width:       u32,
    height:      u32,
    orientation: Orientation,
}

#[derive(Config)]
#[config(expose(read))] // it is usually useful to expose the read type for enums
enum Orientation {
    Landscape,
    Portrait,
}

Refer ot the documentation of Config for more customization.

Next, add it to the Bevy app during startup, referencing the ManagerType we just defined:

use bevy_mod_config::AppExt;

struct VideoPlugin;

impl Plugin for VideoPlugin {
    fn build(&self, app: &mut App) { app.init_config::<ManagerType, VideoSettings>("video"); }
}

Now we can access the configuration data in systems with ReadConfig. ReadConfig gives us the “read” type of each field instead of the original type, so we have to match the enum on the read type we exposed earlier:

use bevy_mod_config::ReadConfig;

fn display_system(settings: ReadConfig<VideoSettings>) {
    let settings = settings.read();
    match settings.orientation {
        OrientationRead::Landscape => display_landscape(),
        OrientationRead::Portrait => display_portrait(),
    }
}

Note that ReadConfig must use the same type as the one passed to init_config.

Use ReadConfigChange instead to observe changes. This change detection is on a per-configuration-root basis.

use bevy_mod_config::ReadConfigChange;

fn resize_system(mut settings: ReadConfigChange<VideoSettings>) {
    if settings.consume_change() {
        let settings = settings.read();
        resize_window(settings.width, settings.height);
    }
}

Now that we have configuration data defined, we can use managers for persistence, loading and more. See the documentation of each manager module for examples.

What’s next

• See Manager for implementing your own behavior on configuration data.
• See ConfigField for implementing your own field types.

A manager can only be used when all config fields in the app implement ConfigFieldFor for that manager, If you are writing a reusable plugin for other crates, you should accept a generic manager type parameter M:

struct MyPlugin<M>(PhantomData<M>);
impl<M: Manager + Default> Plugin for MyPlugin<M>
where
    MyConf: ConfigFieldFor<M>,
{
    fn build(&self, app: &mut App) { app.init_config::<M, MyConf>("my_module"); }
}

#[derive(Config)]
struct MyConf {
    // ...
}

Re-exports

pub use impls::BareField;

pub use manager::Manager;

Modules

impls

Exports the metadata structs for foreign scalar types.

manager

Utilities for config management.

Macros

impl_scalar_config_field

Implements ConfigField for a scalar (non-composite) type.

Structs

ChildNodeList

Lists the child nodes of a config field node.

ChildNodeOf

Marks an entity as a child node of a config field.

ConditionalRelevance

If a node entity has this component, it is conditionally “irrelevant” based on the state of another entity.

ConfigNode

Marks an entity as a config field node.

EnumDiscriminantMetadata

Metadata type for enum discriminants.

EnumDiscriminantWrapper

A ConfigField implementation that wraps an EnumDiscriminant implementor.

EnumFieldMetadata

Metadata type for fields whose type is a Config-derived enum.

FieldGeneration

Tracks the number of changes to a config field.

ReadConfig

Access to a tree of config fields from a root config type C that was passed into App::init_config.

ReadConfigChange

Access to a tree of config fields from a root config type C, and maintains a local state to track changes since the last check.

RootNode

Marks an entity as a root config node.

ScalarData

Stores the typed data of a scalar config field.

ScalarField

Marks an entity as a scalar config field.

ScalarMetadata

Stores the metadata of a scalar config field.

SpawnContext

Context information of the config field from its referrers.

StructMetadata

Metadata type for ConfigField implementors derived from Config.

Traits

AppExt

Extension trait for App to initialize config systems.

ConfigField

Field types that can be used in a Config struct/enum.

ConfigFieldFor

Determines how a ConfigField implementor interacts with a Manager type.

EnumDiscriminant

Implemented by the discriminant type generated by crate::Config when derived for enums.

QueryLike

A Query-like type that extracts component data from an entity, allowing a large query to be mapped to a subset of its requests.

SpawnHandle

The spawn handle of a config node.

Functions

init_config_node

Initializes a newly spawned config node entity with the required components from the context.

Derive Macros

Config

Derives ConfigField on a struct or enum, allowing it to be embedded in another ConfigField struct/enum or passed into init_config.