Struct Hierarchy

pub struct Hierarchy<P> { /* private fields */ }

Scene graph type hierarchy.

Will use the given generic type P as the component type that provides parenting links. The internal structure is kept in sync with the Tracked events for that component type.

Will send modification events on the internal EventChannel. Note that Removed events do not indicate that the Parent component was removed from the component storage, just that the Entity will no longer be considered to be a part of the Hierarchy. This is because the user may wish to either remove only the component, or the complete Entity, or something completely different. When an Entity that is a parent gets removed from the hierarchy, the full tree of children below it will also be removed from the hierarchy.

Any cycles in the hierarchy will cause Undefined Behavior.

Implementations

impl<P> Hierarchy<P>

pub fn new(reader_id: ReaderId<ComponentEvent>) -> Self

where P: Component, P::Storage: Tracked,

Create a new hierarchy object.

pub fn all(&self) -> &[Entity]

Get all entities that contain parents, in sorted order, where parents are guaranteed to be before their children.

Note: This does not include entities that are parents.

Examples found in repository

examples/sort.rs (line 55)

fn main() {
    let mut world = World::new();
    let mut dispatcher = DispatcherBuilder::new()
        .with(
            HierarchySystem::<Parent>::new(&mut world),
            "hierarchy_system",
            &[],
        )
        .build();
    dispatcher.setup(&mut world);

    let _e0 = world.create_entity().build();
    let e1 = world.create_entity().build();
    let e2 = world.create_entity().build();
    let e3 = world.create_entity().build();
    let e4 = world.create_entity().build();
    let e5 = world.create_entity().build();
    let _e6 = world.create_entity().build();
    let _e7 = world.create_entity().build();
    let _e8 = world.create_entity().build();
    let _e9 = world.create_entity().build();

    {
        let mut parents = world.write_storage::<Parent>();
        parents.insert(e1, Parent { entity: e5 }).unwrap();
        parents.insert(e3, Parent { entity: e1 }).unwrap();
        parents.insert(e4, Parent { entity: e5 }).unwrap();
        parents.insert(e5, Parent { entity: e2 }).unwrap();
    }

    dispatcher.dispatch(&mut world);

    {
        let parents = world.read_storage::<Parent>();
        for entity in world.read_resource::<Hierarchy<Parent>>().all() {
            let formatted = parents
                .get(*entity)
                .map(|parent| format!("{:?}", parent.entity))
                .unwrap_or(format!("None"));
            println!("{:?}: {}", entity, formatted);
        }
    }
}

pub fn children(&self, entity: Entity) -> &[Entity]

Get the immediate children of a specific entity.

pub fn all_children(&self, entity: Entity) -> BitSet

Get all children of this entity recursively as a BitSet

This does not include the parent entity you pass in.

pub fn all_children_iter(&self, entity: Entity) -> SubHierarchyIterator<'_, P>

Returns an iterator over all of the recursive children of this entity.

This does not include the parent entity you pass in. Parents are guaranteed to be prior to their children.

pub fn parent(&self, entity: Entity) -> Option<Entity>

Get the parent of a specific entity

pub fn track(&mut self) -> ReaderId<HierarchyEvent>

Get a token for tracking the modification events from the hierarchy

pub fn changed(&self) -> &EventChannel<HierarchyEvent>

Get the EventChannel for the modification events for reading

pub fn maintain(&mut self, data: ParentData<'_, P>)

where P: Component + Parent, P::Storage: Tracked,

Maintain the hierarchy, usually only called by HierarchySystem.