scene.find

The single entity-discovery tool. It reads the flat live population, so it reaches runtime clones, temporary entities, and detached roots — the entities a hierarchy walk from a scene root silently misses.

Pick a search axis (each a list, so many candidates resolve in one call):

• name — name terms, matched as substrings by default (muzzle, flash).
• component — entities carrying any of the named components (Light, Camera).
• attribute — entities whose attribute name holds value (team = red).

Multiple axes = union; each hit reports which criterion matched, so you learn the right wording.

Modifiers:

• substring (default true) — case-insensitive name-part matching, so "muzzle" reaches muzzle_light_ent_620d…. Set false for exact.
• includeInternal (default false) — entities marked internal are excluded unless you opt in.
• roots — top-level entities only. maxDepth — cap the hierarchy depth.
• under — only descendants of these entities (by name or id). ancestorsOf — only ancestors of these.
• additive (default false) — search only the active scene, or set true to also search loaded overlay (additive) scenes.
• limit — cap the returned matches; total still reports the full count.

Projections — include

By default a hit says which entity matched. include makes the query answer the question outright, so you inspect a set in one call instead of querying and then interrogating each entity. include is a list of the projections below: under set to a room with include naming transform and componentValues returns every entity in the room with its placement and its live component values.

Projection	Adds to every match
transform	position = { x, y, z } (world), rotation = { x, y, z, w } (world quaternion), eulerAngles = { x, y, z } (degrees), scale = { x, y, z } (local), each an array
componentValues	componentValues: each component's live field values, keyed by component name
attributes	attributes: the entity's attributes as { name = value }
scriptComponents	scriptComponents: every script-component instance the live entity carries, as { type, identity, instance }

The transform vectors are arrays, the vector shape the scene and entityOps tools take and report, so a projected position passes straight to entityOps.transform. Read them by index: position[1], position[2] and position[3] are x, y and z, while an entity proxy holds the same value keyed x, y, z.

Every match already carries components, the names of its components, without include; their live values are the componentValues projection. Nothing else is added unless include names it. An unrecognised projection is an error listing the accepted ones and naming the one to write instead (include = { "components" } points at componentValues and scriptComponents, "position" at transform). Projections read the live entity, so a component added in the same frame reports its values here even though the entity census has not caught up.

Returns { matches, total, truncated, searchedAxes }, each match a { id, name, parent, depth, components, layer, matched } with the FULL canonical id and name, plus whatever include asked for.

Writing the query under its parameter name

The tool's one parameter is named query, so the search fields can be written under that name or beside it, and both spell the same search: a name of ground with include naming transform reads the same inside query as beside it.

A field written both inside query and beside it is refused, naming the field.