API reference

EntityPath Object

Path-based entity lookup using Named for segment names and TransformParent for hierarchy.
Lookup walks the TransformParent reverse-edge index that the DataModel maintains synchronously (registered as a linked entity attribute in AppSystemActivity / AppSystemService), so paths resolve in the same frame an entity's components are written — no tick required.
Cost: an entire relative path resolves in one JNI call into DataModel.findByPath, which walks the segments inside C++ using the reverse-edge index and the per-attribute string store. Per-segment work is O(siblings-at-this-parent) native string compares; total cost approaches O(depth) for typical low-fan-out scene graphs. For absolute paths the first segment is resolved by a Kotlin-side root scan (EntityPath.findRoot) and the rest are walked natively.
Names are not guaranteed unique within a parent. When two siblings share a name, lookup returns the child with the lowest entity id (deterministic). At the root, a one-shot warning is logged the first time a collision is observed at a given name; intermediate-segment collisions are resolved silently for performance.

Signature

object EntityPath

Properties

SEPARATOR : String
[Get]
Signature 
const val SEPARATOR: String

Methods

childOf ( parent , name )
Returns the direct child of parent whose Named.name equals name, or null.
Signature 
fun childOf(parent: Entity, name: String): Entity?
Parameters
parent: Entity
name: String
Returns
Entity?
find ( path , dataModel )
Resolve a path against dataModel.
Absolute paths begin with / and resolve from a root (an entity that has Named but no TransformParent, or whose TransformParent.entity is Entity.Companion.nullEntity). Relative paths have no leading / and are not supported on this entry point — use EntityPath.findRelative instead.
Signature 
fun find(path: String, dataModel: DataModel? = EntityContext.getDataModel()): Entity?
Parameters
path: String
dataModel: DataModel?
Returns
Entity?
findRelative ( start , path )
Resolve path relative to start. The first segment names a direct child of start.
Signature 
fun findRelative(start: Entity, path: String): Entity?
Parameters
start: Entity
path: String
Returns
Entity?
pathOf ( entity )
The absolute path of entity obtained by walking up TransformParent and joining Named.name values. Returns null if any ancestor (including entity) lacks Named, if entity is Entity.Companion.nullEntity, or if any ancestor's name cannot be losslessly encoded as a path segment — i.e. is empty or contains EntityPath.SEPARATOR. The latter would alias to a different entity (or none) when fed back through EntityPath.find, so refusing to encode is the only safe behavior.
Signature 
fun pathOf(entity: Entity): String?
Parameters
entity: Entity
Returns
String?
Nav Logo
English (US)
© 2026 Meta