A system for maintaining parent-child relationships on entities. More...

#include <hierarchy.h>

Public Types
using	PC = ParentConnection< HTag >

Public Member Functions
	HierarchySystem (entt::registry &reg)

	HierarchySystem (const HierarchySystem &)=delete

HierarchySystem &	operator= (const HierarchySystem &)=delete

Position	set_parent (entt::entity child, entt::entity parent, std::optional< Position > position=std::nullopt)
	Set the parent of a child entity.

std::optional< PC >	unparent (entt::entity child)
	Remove a child from its parent.

std::optional< Position >	set_child_position (entt::entity child, Position position)
	Change the position of a child among its siblings.

std::optional< Position >	order_child_before (entt::entity child, entt::entity before)
	Move a child to the position before a sibling.

size_t	size () const
	The number of non-root nodes in the hierarchy (i.e. entities with a parent).

entt::entity	parent_of (entt::entity node) const
	Returns the parent of `node`, or `entt::null` if the node is a root or not in the hierarchy.

std::optional< Position >	position_of (entt::entity node) const
	Returns the sibling position of `node`, or `std::nullopt` if not in the hierarchy.

std::optional< PC >	get_connection (entt::entity node) const
	Returns the full ParentConnection for `node`, or `std::nullopt` if not in the hierarchy.

size_t	child_count (entt::entity parent) const
	Returns the number of children of a given node.

std::optional< Position >	last_child_position (entt::entity parent) const
	Returns the position of the last child, or `std::nullopt` if there are no children.

Generator< NodeEntry >	children (entt::entity parent, SiblingOrder order) const
	Visit each child of a given node.

Generator< NodeEntry >	ancestors (entt::entity node) const
	Returns a generator which yields the ancestors of a given node.

auto	traverse (entt::entity root, SiblingOrder order) const
	Returns a Traversal of the hierarchy rooted at `root`.

Generator< NodeEntry >	traverse_dfs (entt::entity root, SiblingOrder sibling_order=SiblingOrder::Forward, DfsOrder recursion_order=DfsOrder::ShallowFirst) const
	Convenience: flatten a depth-first traversal into a generator.

TreePath	path (entt::entity node) const
	Returns the path from the root to the given node.

entt::entity	deepest_common_ancestor (entt::entity node_a, entt::entity node_b) const
	Returns the deepest common ancestor of two nodes.

bool	is_ancestor_of (entt::entity ancestor, entt::entity descendant) const
	Returns `true` if `ancestor` is a strict ancestor of `descendant`.

Public Attributes
entt::sigh< void(entt::entity, PC)>	on_added
	Emitted after a child is added to the hierarchy. Args: (child, new_connection).

entt::sigh< void(entt::entity, PC)>	on_removed
	Emitted after a child is removed from the hierarchy. Args: (child, old_connection).

entt::sigh< void(entt::entity, PC, PC)>	on_changed
	Emitted after a child's parent or position changes. Args: (child, old_connection, new_connection).

Detailed Description

template<typename HTag>
struct entttree::HierarchySystem< HTag >

A system for maintaining parent-child relationships on entities.

The source of truth for a parent-child relationship is a ParentConnection<HTag> component which lives on the child entity. This component also contains a Position field which determines the relative order of siblings. A sorted cache is maintained which maps parents to their children; this is updated whenever a parent-child connection is changed. For this reason, it is invalid to edit the ParentConnection component outside of this system.

Root nodes (those without parents) do not have a ParentConnection component.

Multiple independent hierarchies can coexist on the same entity by using different tag types for HTag.

Template Parameters

HTag	A tag type that distinguishes this hierarchy from others on the same registry (e.g. `struct RenderH {};`).

Definition at line 37 of file hierarchy.h.

Member Typedef Documentation

◆ PC

template<typename HTag >

using entttree::HierarchySystem< HTag >::PC = ParentConnection<HTag>

Definition at line 39 of file hierarchy.h.

Constructor & Destructor Documentation

◆ HierarchySystem()

template<typename HTag >

entttree::HierarchySystem< HTag >::HierarchySystem ( entt::registry & reg )

inlineexplicit

Definition at line 56 of file hierarchy.h.

Member Function Documentation

◆ ancestors()

template<typename HTag >

Generator< NodeEntry > entttree::HierarchySystem< HTag >::ancestors ( entt::entity node ) const

inline

Returns a generator which yields the ancestors of a given node.

The first element yielded is the node itself (unless it has no ParentConnection), and the last element is the root. Each yielded NodeEntry has node_id set to the current ancestor and parent_id set to the next ancestor up the hierarchy. When the root is yielded its parent_id will be entt::null.

Definition at line 379 of file hierarchy.h.

◆ child_count()

template<typename HTag >

size_t entttree::HierarchySystem< HTag >::child_count ( entt::entity parent ) const

inline

Returns the number of children of a given node.

If the node is not in the hierarchy, the count is implicitly zero.

Definition at line 324 of file hierarchy.h.

References entttree::HierarchySystem< HTag >::size().

Referenced by entttree::BoundsSystem< HTag, T, N, BTag, XTag >::remove_intrinsic_bounds().

◆ children()

template<typename HTag >

Generator< NodeEntry > entttree::HierarchySystem< HTag >::children	(	entt::entity	parent,
		SiblingOrder	order
	)		const

inline

Visit each child of a given node.

It is valid to remove (but not add) children during iteration when the sibling order is backward. Otherwise, changes to the hierarchy will invalidate the iterator.

Definition at line 351 of file hierarchy.h.

Referenced by entttree::HierarchySystem< HTag >::last_child_position(), entttree::HierarchySystem< HTag >::order_child_before(), entttree::HierarchySystem< HTag >::set_child_position(), entttree::HierarchySystem< HTag >::set_parent(), and entttree::HierarchySystem< HTag >::traverse().

◆ deepest_common_ancestor()

template<typename HTag >

entt::entity entttree::HierarchySystem< HTag >::deepest_common_ancestor	(	entt::entity	node_a,
		entt::entity	node_b
	)		const

inline

Returns the deepest common ancestor of two nodes.

Returns: The common ancestor entity, or entt::null if the nodes are not in the same tree.

Definition at line 446 of file hierarchy.h.

References entttree::HierarchySystem< HTag >::path(), and entttree::HierarchySystem< HTag >::size().

◆ get_connection()

template<typename HTag >

std::optional< PC > entttree::HierarchySystem< HTag >::get_connection ( entt::entity node ) const

inline

Returns the full ParentConnection for node, or std::nullopt if not in the hierarchy.

Definition at line 313 of file hierarchy.h.

◆ is_ancestor_of()

template<typename HTag >

bool entttree::HierarchySystem< HTag >::is_ancestor_of	(	entt::entity	ancestor,
		entt::entity	descendant
	)		const

inline

Returns true if ancestor is a strict ancestor of descendant.

Definition at line 466 of file hierarchy.h.

References entttree::and.

◆ last_child_position()

template<typename HTag >

std::optional< Position > entttree::HierarchySystem< HTag >::last_child_position ( entt::entity parent ) const

inline

Returns the position of the last child, or std::nullopt if there are no children.

Definition at line 331 of file hierarchy.h.

References entttree::HierarchySystem< HTag >::children().

◆ order_child_before()

template<typename HTag >

std::optional< Position > entttree::HierarchySystem< HTag >::order_child_before	(	entt::entity	child,
		entt::entity	before
	)

inline

Move a child to the position before a sibling.

The sibling must belong to the same parent; if it doesn't, the child is moved to the end of its parent.

Returns the new position if changed, nullopt otherwise.

Definition at line 232 of file hierarchy.h.

References entttree::and, entttree::HierarchySystem< HTag >::children(), entttree::ChildEntry::eid, and entttree::HierarchySystem< HTag >::on_changed.

◆ parent_of()

template<typename HTag >

entt::entity entttree::HierarchySystem< HTag >::parent_of ( entt::entity node ) const

inline

Returns the parent of node, or entt::null if the node is a root or not in the hierarchy.

Definition at line 300 of file hierarchy.h.

Referenced by entttree::TransformSystem< HTag, T, N, XTag >::object_to_world(), entttree::BoundsSystem< HTag, T, N, BTag, XTag >::remove_intrinsic_bounds(), and entttree::HierarchySystem< HTag >::traverse().

◆ path()

template<typename HTag >

TreePath entttree::HierarchySystem< HTag >::path ( entt::entity node ) const

inline

Returns the path from the root to the given node.

The first element of the path is the root, and the last element is the node itself.

Definition at line 428 of file hierarchy.h.

References entttree::and.

Referenced by entttree::HierarchySystem< HTag >::deepest_common_ancestor(), and entttree::TransformSystem< HTag, T, N, XTag >::xf_between().

◆ position_of()

template<typename HTag >

std::optional< Position > entttree::HierarchySystem< HTag >::position_of ( entt::entity node ) const

inline

Returns the sibling position of node, or std::nullopt if not in the hierarchy.

Definition at line 306 of file hierarchy.h.

Referenced by entttree::HierarchySystem< HTag >::traverse().

◆ set_child_position()

template<typename HTag >

std::optional< Position > entttree::HierarchySystem< HTag >::set_child_position	(	entt::entity	child,
		Position	position
	)

inline

Change the position of a child among its siblings.

Returns the new position if changed, nullopt if unchanged.

Definition at line 189 of file hierarchy.h.

References entttree::HierarchySystem< HTag >::children(), entttree::ChildEntry::eid, entttree::HierarchySystem< HTag >::on_changed, and entttree::ChildEntry::position.

◆ set_parent()

template<typename HTag >

Position entttree::HierarchySystem< HTag >::set_parent	(	entt::entity	child,
		entt::entity	parent,
		std::optional< Position >	position = `std::nullopt`
	)

inline

Set the parent of a child entity.

If the child already has a parent, it is reparented. If no position is given, the child is placed at the end of its new parent's children.

Returns the actual position used (may be deduplicated).

Definition at line 74 of file hierarchy.h.

References entttree::and, entttree::HierarchySystem< HTag >::children(), entttree::ChildEntry::eid, entttree::HierarchySystem< HTag >::on_added, entttree::HierarchySystem< HTag >::on_changed, entttree::ChildEntry::position, and entttree::HierarchySystem< HTag >::size().

◆ size()

template<typename HTag >

size_t entttree::HierarchySystem< HTag >::size ( ) const

inline

The number of non-root nodes in the hierarchy (i.e. entities with a parent).

Definition at line 295 of file hierarchy.h.

References entttree::HierarchySystem< HTag >::size().

Referenced by entttree::HierarchySystem< HTag >::child_count(), entttree::HierarchySystem< HTag >::deepest_common_ancestor(), entttree::HierarchySystem< HTag >::set_parent(), entttree::HierarchySystem< HTag >::size(), and entttree::TransformSystem< HTag, T, N, XTag >::xf_between().

◆ traverse()

template<typename HTag >

auto entttree::HierarchySystem< HTag >::traverse	(	entt::entity	root,
		SiblingOrder	order
	)		const

inline

Returns a Traversal of the hierarchy rooted at root.

The returned Traversal can be composed with adaptors from the walk namespace and then flattened with walk::dfs() or walk::bfs().

Definition at line 396 of file hierarchy.h.

References entttree::HierarchySystem< HTag >::children(), entttree::make_traversal(), entttree::NodeEntry::node_id, entttree::HierarchySystem< HTag >::parent_of(), and entttree::HierarchySystem< HTag >::position_of().

Referenced by entttree::BoundsSystem< HTag, T, N, BTag, XTag >::traverse(), entttree::TransformSystem< HTag, T, N, XTag >::traverse(), and entttree::HierarchySystem< HTag >::traverse_dfs().

◆ traverse_dfs()

template<typename HTag >

Generator< NodeEntry > entttree::HierarchySystem< HTag >::traverse_dfs	(	entt::entity	root,
		SiblingOrder	sibling_order = `SiblingOrder::Forward`,
		DfsOrder	recursion_order = `DfsOrder::ShallowFirst`
	)		const

inline

Convenience: flatten a depth-first traversal into a generator.

Definition at line 411 of file hierarchy.h.

References entttree::HierarchySystem< HTag >::traverse().

◆ unparent()

template<typename HTag >

std::optional< PC > entttree::HierarchySystem< HTag >::unparent ( entt::entity child )

inline

Remove a child from its parent.

Returns the old ParentConnection if the child was in the hierarchy.

Definition at line 170 of file hierarchy.h.

References entttree::HierarchySystem< HTag >::on_removed.

Member Data Documentation

◆ on_added

template<typename HTag >

entt::sigh<void(entt::entity, PC)> entttree::HierarchySystem< HTag >::on_added

Emitted after a child is added to the hierarchy. Args: (child, new_connection).

Definition at line 46 of file hierarchy.h.

Referenced by entttree::HierarchySystem< HTag >::set_parent().

◆ on_changed

template<typename HTag >

entt::sigh<void(entt::entity, PC, PC)> entttree::HierarchySystem< HTag >::on_changed

Emitted after a child's parent or position changes. Args: (child, old_connection, new_connection).

Definition at line 50 of file hierarchy.h.

Referenced by entttree::HierarchySystem< HTag >::order_child_before(), entttree::HierarchySystem< HTag >::set_child_position(), and entttree::HierarchySystem< HTag >::set_parent().

◆ on_removed

template<typename HTag >

entt::sigh<void(entt::entity, PC)> entttree::HierarchySystem< HTag >::on_removed

Emitted after a child is removed from the hierarchy. Args: (child, old_connection).

Definition at line 48 of file hierarchy.h.

Referenced by entttree::HierarchySystem< HTag >::unparent().

The documentation for this struct was generated from the following file:

include/entttree/hierarchy.h

Public Types

Public Member Functions

Public Attributes

Detailed Description

Member Typedef Documentation

◆ PC

Constructor & Destructor Documentation

◆ HierarchySystem()

Member Function Documentation

◆ ancestors()

◆ child_count()

◆ children()

◆ deepest_common_ancestor()

◆ get_connection()

◆ is_ancestor_of()

◆ last_child_position()

◆ order_child_before()

◆ parent_of()

◆ path()

◆ position_of()

◆ set_child_position()

◆ set_parent()

◆ size()

◆ traverse()

◆ traverse_dfs()

◆ unparent()

Member Data Documentation

◆ on_added

◆ on_changed

◆ on_removed