Crate i_cant_believe_its_not_bsn 

i-cant-believe-its-not-bsn

Ergonomic ways to spawn Bevy entity hierarchies.

Eagerly waiting for BSN? Really wish you could spawn hierarchies with less boilerplate? Just want to define some reusable widget types for bevy_ui in code?

This crate is here to help!

Helper Components

You can use the helper component WithChild, and its iterator sibling, WithChildren, to embed hierarchy information in normal bundles.

Just add it as a component holding the bundle you want to use to spawn the child, and you’re off to the races. A component hook will see that this component has been added, extract the data from your WithChild component, and then move it into a child, cleaning itself up as it goes.

These helper components are extremely useful when you just want to insert a tree of entities declaratively.

The Template Macro

Alternatively you can use the template!() macro, which is very similar to the proposed bsn syntax. Arbitrary data can be passed into the macro using normal rust blocks. The macro returns portable Template values, which can be spliced into other templates using @{ ... }.

Not only is the macro declarative and composable, it also supports basic incrementalization (doing partial updates to the ecs rather than rebuilding from scratch). Building the same macro multiple times with commands.build(template) does only the work necessary to bring the ecs into alignment with the template.

Macros

push_fragment

Used internally. See template!().

push_item

Used internally. See template!().

template

This is a declarative template macro for Bevy!

Structs

BuildTemplateCommand

A command for building a template. The shorthand for this is CommandsTemplateExt::build. See [BuildTemplate::build] for more documentation.

Fragment

A fragment is a tree of bundles with optional names. It implements Prototype and can be stored or used as a Box<dyn Prototype>.

Maybe

A component that when added to an entity, will be removed from the entity and replaced with its contents if Some.

Receipt

Receipts contain hints about the previous outcome of building a particular prototype.

WithChild

A component that, when added to an entity, will add a child entity with the given bundle.

WithChildren

A component that, when added to an entity, will add a child entity with the given bundle.

Traits

CommandsTemplateExt

Prototype

A prototype is the type-erased trait form of a Fragment contained within a Template. It has a name, and can be inserted into the world multiple times, updating it’s previous value each time.

WorldTemplateExt

Type Aliases

Template

A template is an ordered collection of heterogenous prototypes, which can be inserted into the world. Returned by the [template] macro.