@web-engine-dev/hierarchy

Parent-child relationships and propagation for web-engine-dev. Provides a hierarchical structure for entities with automatic propagation of transforms and other inherited properties.

Features

• Parent-Child Relationships: Set, get, and manage entity hierarchies
• Hierarchy Traversal: Depth-first and breadth-first iteration
• Ancestor/Descendant Queries: Query family relationships
• Detach/Reparent: Move entities between hierarchy branches
• Depth Tracking: Automatic depth calculation

Installation

npm install @web-engine-dev/hierarchy
# or
pnpm add @web-engine-dev/hierarchy

Quick Start

import { createHierarchy } from '@web-engine-dev/hierarchy';

const hierarchy = createHierarchy();

// Create parent-child relationships
hierarchy.setParent(child, parent);
hierarchy.setParent(grandchild, child);

// Query relationships
const parent = hierarchy.getParent(child);
const children = hierarchy.getChildren(parent);
const ancestors = hierarchy.getAncestors(grandchild);
const descendants = hierarchy.getDescendants(parent);

// Check relationships
hierarchy.hasParent(entity);
hierarchy.hasChildren(entity);
hierarchy.isAncestorOf(ancestor, descendant);

// Get depth
const depth = hierarchy.getDepth(entity); // 0 = root

API Reference

Hierarchy

Method	Description
setParent(child, p)	Set parent of child (null to remove)
getParent(entity)	Get parent entity or null
getChildren(entity)	Get array of child entities
hasParent(entity)	Check if entity has parent
hasChildren(entity)	Check if entity has children
getDepth(entity)	Get depth in hierarchy (0 = root)
getRoots()	Get all root entities
getAncestors(e)	Get ancestors from parent to root
getDescendants(e)	Get all descendants
traverse(e, visitor)	Walk hierarchy calling visitor
detach(entity)	Detach subtree to become independent

Traversal

// Depth-first traversal
hierarchy.traverse(
  root,
  (entity, depth) => {
    console.log(`Entity at depth ${depth}`);
    return true; // Continue traversal
  },
  { order: 'depth-first', direction: 'down' }
);

// Breadth-first traversal
hierarchy.traverse(root, visitor, {
  order: 'breadth-first',
  direction: 'down',
});

// Upward traversal
hierarchy.traverse(leaf, visitor, { direction: 'up' });

Use Cases

Scene Graph

// Create scene hierarchy
hierarchy.setParent(mesh, node);
hierarchy.setParent(node, scene);

// Propagate transforms
for (const descendant of hierarchy.getDescendants(node)) {
  updateWorldTransform(descendant);
}

UI Layout

// Parent layout contains children
hierarchy.setParent(button, panel);
hierarchy.setParent(text, button);

// Update layout from root
hierarchy.traverse(root, (entity) => {
  calculateLayout(entity);
  return true;
});