Function: pickNode()

pickNode(root, point, tolerance?): NodeBox | null

Defined in: runtime/node-picking.ts:167

The topmost node whose hit region contains point (viewport space, y-up, origin at the viewport centre), or null. Children paint over their parent and later siblings over earlier ones, so the walk tests children last-to-first before falling back to the node itself.

Skips fully transparent nodes — a scene built with spawn delays keeps not-yet-visible nodes in the tree at opacity: 0, and those must not be selectable. A node that clips (or pushes a camera, which clips to its viewport) confines its subtree: a point outside its box cannot hit anything inside it. The scene root is never returned; it is the stage, not a selectable node.

The hit region is Node.hitTestSelf — the rotated layout box by default, narrowed to the declared outline for shapes. A click in the corner of a rect's box selects it; a click in the empty notch of a star's box does not.

tolerance is grab-slop in scene units, applied outward from the ink. A host passes its zoom-corrected pixel slop so the grab area stays constant on screen. It is what makes thin shapes reachable.

Cost: renderMatrix walks to the root per node, making a pick O(depth²). Scene trees here are shallow (tens of nodes, depth < 10), so this is fine at pointer rate. If it ever matters, thread the parent's accumulated matrix down through the walk instead of recomputing — a change confined to this file.

Parameters

root

Node

point

Vector2

tolerance?

number = 0

Returns

NodeBox | null