Proposal: Introduce a unified dependency/query system for nodes, contexts, and managers

[GuilhermeF03]

Problem

The engine currently provides multiple ways to access dependencies:

• NodeRef
• path-based node lookups
• group queries
• manager<T>() for global services
• Context.resolve() for scoped data

Each mechanism solves a similar problem but uses a different API and mental model, leading to inconsistent dependency access across gameplay code.

Common tasks include:

• accessing parent/child nodes
• resolving nodes in the scene tree
• retrieving nodes from groups
• accessing scoped context data
• retrieving global managers

As the engine grows, this fragmentation can lead to inconsistent patterns, duplicated logic, and overuse of path lookups or global services.

---

Proposal

Introduce a unified dependency/query API for nodes and behaviors.

The goal is to provide a consistent way to access runtime dependencies across the engine.

Example:

val player by ancestor<Player>()
val sprite by child<Sprite2D>()
val camera by tree<Camera2D>()
val enemies by group<Enemy>("enemies")
val rules by context<GameRules>()
val save by manager<SaveManager>()

Goals

• typed queries instead of string paths
• consistent dependency access patterns
• ergonomic delegated properties
• support for optional/required dependencies
• compatibility with existing systems (NodeRef, contexts, managers)

---

Alternatives

Existing systems partially address this:

• NodeRef — explicit node references
• manual traversal — parent/child navigation
• groups — collections of nodes
• managers — global services
• contexts — scoped dependency injection

However, these approaches are separate and do not provide a single consistent dependency model.

---

Goal

Provide a unified dependency/query layer that improves consistency, ergonomics, and maintainability when accessing dependencies in nodes and behaviors.

---