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.

childOf ( parent , name )	Returns the direct child of EntityPath.childOf whose Named.name equals EntityPath.childOf, or null. Signature fun childOf(parent: Entity, name: String): Entity? Parameters `parent: Entity` `name: String` Returns `Entity?`
find ( path , dataModel )	Resolve a path against EntityPath.find. 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 EntityPath.findRelative relative to EntityPath.findRelative. The first segment names a direct child of EntityPath.findRelative. Signature fun findRelative(start: Entity, path: String): Entity? Parameters `start: Entity` `path: String` Returns `Entity?`
pathOf ( entity )	The absolute path of EntityPath.pathOf obtained by walking up TransformParent and joining Named.name values. Returns null if any ancestor (including EntityPath.pathOf) lacks Named, if EntityPath.pathOf 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?`

EntityPath Object

Signature

Properties

Methods