1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

//! # hecs-hierarchy
//!
//! [![Cargo](https://img.shields.io/crates/v/hecs-hierarchy.svg)](https://crates.io/crates/hecs-hierarchy)
//! [![Documentation](https://docs.rs/hecs-hierarchy/badge.svg)](https://docs.rs/hecs-hierarchy)
//! [![LICENSE](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE-MIT)
//!
//! Hierarchy implementation for hecs ECS.
//!
//! ## Features
//! - [X] Iterate children of parent
//! - [X] Lookup parent of child
//! - [X] Traverse hierarchy depth first
//! - [X] Traverse hierarchy breadth first
//! - [X] Traverse ancestors
//! - [X] Detach child from hierarchy
//! - [ ] Reverse iteration
//! - [ ] Sorting
//! - [ ] (Optional) associated data to relation
//!
//! ## Getting Started
//!
//! Include both `hecs` and `hecs-hierarchy` as dependencies in your `Cargo.toml`.
//!
//! `hecs-hierarchy` does not re-export `hecs`
//!
//! ```toml
//! [dependencies]
//! hecs = 0.10
//! hecs-hierarchy = 0.12
//! ```
//!
//! ## Motivation
//!
//! An ECS is a fantastic design principle for designing software which allows a
//! data oriented design. Most of the time, the ECS is flat with maybe a few
//! components referencing each other via `Entity` ids.  Sometimes however, the need
//! to create and manage proper, well behaved graphs, arises.
//!
//! This is were hecs-hierarchy comes in and gives the ability to manage directed
//! graphs that can connect entities. This is very useful when developing a UI
//! library using the ECS design pattern, or purely for grouping entities together
//! from the same model.
//!
//! ## Usage
//!
//! Import the [Hierarchy](crate::Hierarchy) trait which extends [hecs::World](hecs::World)
//!
//! The trait [Hierarchy](crate::Hierarchy) extends [hecs::World](hecs::World) with functions for
//! manipulating and iterating the hierarchy tree.
//!
//! The hierarchy uses a marker type which makes it possible for a single entity to belong to
//! several hierarchy trees.
//!
//! See the [documentation](https://docs.rs/hecs-hierarchy), more specifically the
//! [Hierarchy](https://docs.rs/hecs-hierarchy/0.1.7/hecs_hierarchy/trait.Hierarchy.html)
//! trait
//!
//! Example usage:
//! ```
//! use hecs_hierarchy::*;
//!
//! // Marker type which allows several hierarchies.
//! struct Tree;
//!
//! let mut world = hecs::World::default();
//!
//! // Create a root entity, there can be several.
//! let root = world.spawn(("Root",));
//!
//! // Create a loose entity
//! let child = world.spawn(("Child 1",));
//!
//! // Attaches the child to a parent, in this case `root`
//! world.attach::<Tree>(child, root).unwrap();
//!
//! // Iterate children
//! println!("Iterating children:");
//! for child in world.children::<Tree>(root) {
//!     let name = world.get::<&&str>(child).unwrap();
//!     println!("  Child: {:?} {}", child, *name);
//! }
//!
//! // Add a grandchild
//! world.attach_new::<Tree, _>(child, ("Grandchild",)).unwrap();
//!
//! // Iterate recursively
//! println!("Iterating descendants recursively:");
//! for descendant in world.descendants_depth_first::<Tree>(root) {
//!     let name = world.get::<&&str>(descendant).unwrap();
//!     println!("  Descendant: {:?} {}", descendant, *name)
//! }
//!
//! // Detach `child` and `grandchild`
//! world.detach::<Tree>(child).unwrap();
//!
//! let child2 = world.attach_new::<Tree, _>(root, ("Child 2",)).unwrap();
//!
//! // Reattach as a child of `child2`
//! world.attach::<Tree>(child, child2).unwrap();
//!
//! world.attach_new::<Tree, _>(root, ("Child 3",)).unwrap();
//!
//! // Hierarchy now looks like this:
//! // Root
//! // |-------- Child 3
//! // |-------- Child 2
//! //           |-------- Child 1
//! //                     |-------- Grandchild
//!
//! // Iterate recursively
//! println!("Iterating descendants recursively:");
//! for descendant in world.descendants_depth_first::<Tree>(root) {
//!     let name = world.get::<&&str>(descendant).unwrap();
//!     println!("  Descendant: {:?} {}", descendant, *name)
//! }
//!
//! ```
//!
//! ## Inspiration
//!
//! This project is heavily inspired by `Shipyard`'s hierarchy implementation and
//! exposes a similar API.
//!
//! - [shipyard-hierarchy](https://github.com/dakom/shipyard-hierarchy)

mod builder;
mod builder_clone;
mod components;
mod hierarchy;
mod iter;

pub use builder::*;
pub use builder_clone::*;
pub use components::*;
pub use hierarchy::*;
pub use iter::*;

pub use hecs_schedule::Error;