Crate moonshine_object

Expand description

§🌴 Moonshine Object

An extension to Bevy which provides an ergonomic interface for managing complex Entity hierarchies.

Entities are nice. Objects are better! 😎

§Overview

This crate is designed to provide a wrapper for some commonly used operations when working with entities in Bevy.

It is often required for various systems to be able to traverse complex entity hierarchies. This is especially true for initialization code when various components need to reference various entities within a hierarchy of entities.

For example, consider a system which reacts to a flying bird by flapping its wings:

use bevy::prelude::*;

#[derive(Component)]
struct Bird;

#[derive(Component)]
struct Flying;

fn setup_bird(
    query: Query<Entity, (With<Bird>, Added<Flying>)>,
    children_query: Query<&Children>,
    name: Query<&Name>,
    mut commands: Commands
) {
    for entity in query.iter() {
        if let Ok(children) = children_query.get(entity) {
            for child in children.iter() {
                if let Ok(name) = name.get(child) {
                    if name.as_str() == "Wings" {
                        if let Ok(wings) = children_query.get(child) {
                            for wing in wings.iter() {
                                // TODO: Flap! Flap!
                            }
                        }
                    }
                }
            }
        }
    }
}

Although, this code is intentionally verbose to show the hierarchy complexity, this crate tries to make these situations more ergonomic by introducing Object<T>.

It behaves like an Entity or Instance<T> with some extra features:

use bevy::prelude::*;
use moonshine_object::prelude::*;

#[derive(Component)]
struct Bird;

#[derive(Component)]
struct Flying;

fn setup_bird(birds: Objects<Bird, Added<Flying>>, mut commands: Commands) {
    for bird in birds.iter() {
        if let Some(wings) = bird.find_by_path("./Wings") {
            for wing in wings.children() {
                // TODO: Flap! Flap!
            }
        }
    }
}

§Features

Less boilerplate when dealing with complex entity hierarchies
Full type safety enforced through Kind semantics
No macros! No registration!

§Usage

§`Objects<T>`

Use Objects<T> as a system parameter to access all Object<T> instances.

This SystemParam is designed to be used like a Query:

use bevy::prelude::*;
use moonshine_object::prelude::*;

#[derive(Component)]
struct Bird;

fn update_birds(birds: Objects<Bird>) {
    for bird in birds.iter() {
        // ...
    }
}

Like a Query, you may also use a QueryFilter:

use bevy::prelude::*;
use moonshine_object::prelude::*;

#[derive(Component)]
struct Bird;

#[derive(Component)]
struct Flying;

fn update_flying_birds(birds: Objects<Bird, With<Flying>>) {
    for bird in birds.iter() {
        // ...
    }
}

Internally, Objects<T> is just a thin wrapper around some common queries:

Query<Instance<T>>
Query<&ChildOf> / Query<&Children>
Query<&Name>

§`Object<T>`

Each Object<T> is a reference to an Entity with type, name, and hierarchy information. This provides a convenient way to pass this data between functions:

use bevy::prelude::*;
use moonshine_object::prelude::*;

#[derive(Component)]
struct Bird;

#[derive(Component)]
struct Flying;

fn update_flying_birds(birds: Objects<Bird, With<Flying>>) {
    for bird in birds.iter() {
        flap_wings(bird);
    }
}

fn flap_wings(bird: Object<Bird>) {
    if let Some(wings) = bird.find_by_path("./Wings") {
        for wing in wings.children() {
            // TODO: Flap! Flap!
        }
    }
}

⚠️ Unlike an Entity or Instance<T>, Object<T> has a non-static lifetime and may not be used as a Query term.

§Casting

Like Instance<T>, any Object<T> may be be cast into an Object<U> if T implements CastInto<U>.

You may implement this trait for your own kinds using the kind macro:

use bevy::prelude::*;
use moonshine_kind::prelude::*;
use moonshine_object::prelude::*;

#[derive(Component)]
struct Bird;

struct Creature;

// Every Bird is a Creature by definition:
impl Kind for Creature {
    type Filter = (With<Bird>, /* ... */);
}

// Therefore, all birds may safely be cast into creatures:
impl CastInto<Creature> for Bird {}

// Birds can chirp.
fn chirp(bird: Object<Bird>) {
    // TODO: Chirp!
}

// Creatures can find food.
fn find_food(creature: Object<Creature>) {
    // TODO: Find food!
}

// Birds chirp when they get hungry.
fn handle_hunger(bird: Object<Bird>) {
    chirp(bird);
    find_food(bird.cast_into()); // Safe! :)
}

Any Object<T> is safely convertible to Object<Any>.

§Support

Please post an issue for any bugs, questions, or suggestions.

You may also contact me on the official Bevy Discord server as @Zeenobit.

Modules§

prelude: Prelude module to import all necessary traits and types for working with objects.

Structs§

Any: Represents the kind of any Entity.
Object: Represents an Entity of Kind T with hierarchy and name information.
ObjectRef: Similar to EntityRef with the benefits of Object<T>.
ObjectWorldRef: Similar to an ObjectRef, but accessible via World.
Objects: A SystemParam similar to Query which provides Object<T> access for its items.
Tag: A generic, cheap, and mostly unique identifier.
Tags: A collection of tags.

Enums§

TagFilter: A filter which may be used to test a set of tags for a match.

Traits§

CastInto: A trait which allows safe casting from one Kind to another.
GetObject: Trait used to access an ObjectWorldRef from World.
Kind: A type which represents the kind of an Entity.
ObjectHierarchy: Object methods related to hierarchy traversal.
ObjectName: Object methods related to naming.
ObjectRebind: Object methods related to rebinding and casting.
ObjectTags: Object methods related to accessing Tags.

Type Aliases§

RootObjects: Ergonomic type alias for all Objects of Kind T without a parent.