WorldObject

Subclass hook that produces the concrete dependency resolver the host hands to a component's resolveDependencies. The World hosts a resolver scoped to siblings only; a WorldObject hosts one that also exposes cross-tier lookups against the parent world.

Engine-internal — never called by user code.

Hook for subclasses to intercept errors thrown by a component's onDestroy during AbstractComponentHost.removeAllComponents. Default behaviour is to log and swallow — a single bad component must not prevent the rest of the host's components from being torn down. Subclasses may override to route errors through their own reporting channel.

Routes an update-phase throw from one of this object's components to the parent World's error channel — a WorldObject has no reporter of its own, so it delegates. The shared per-component dispatch loop in AbstractComponentHost calls this; the symmetric WorldObject._handleComponentDestroyError handles onDestroy.

Drives every enabled component through one update phase, isolating each invocation so a single throwing component can't abort the rest of the host's components (or the wider tick). The host-level AbstractComponentHost.enabled gate short-circuits the whole phase before any component is touched; a per-component enabled === false skips that one; a component that doesn't implement the optional hook is skipped at a single property read. The cached dependencies are threaded in as the trailing argument.

Failures are routed to AbstractComponentHost._reportPhaseError, which each host kind implements to reach its error-reporting channel.

Attaches child beneath this object — the mirror of WorldObject.setParent, reading naturally when the parent is what you have in hand. Equivalent to child.setParent(this, options), including the default of preserving the child's world transform.

Adds a new component to the host object. Throws if a component with the specified key already exists. Calls onAdded() on the component once registered with its host.

Adds a new component to the host object using a factory function. Internally produces the new component using the factory function, then calls addComponent() with the result.

The advantage of using this method over addComponent() is that the factory function is provided with the host.

Adds a new set of components to the host object. Throws if a component with the specified key already exists. Calls onAdded() on each component after they are all registered with the host, rather than one by one. This is important for components that may want to reference each other during the addition phase via host.getComponent() or similar methods.

It is recommended to use this method rather than addComponent() in situations like initialization of a new host object.

Adds a new set of components to the host object based on an input map of component keys to factory functions. Behavious is equivalent to addComponents() using the key and output of each factory function.

Marks the object as destroyed. This does not immediately remove it from the world or destroy its components — the world must tick at least once for that to happen.

If called during a World.update tick, the object is removed at the end of that tick. If the object has not yet had its onUpdate called during the same tick (e.g. it was destroyed by a component or by an earlier object in the iteration), its onUpdate is skipped — destroyed objects do not get one final tick.

Calling destroy on an already-marked or already-cleaned object is a no-op.

Destruction cascades to the subtree: every * descendant is marked too, so a child can never outlive the parent it is pinned to. Each marked object is swept (and has its onDestroy run) independently by the world, honouring the same deferred timing.

Gets a component from the host object using the key it was registered with. Throws if the component does not exist. Performs an efficient lookup on a local Map instance.

Gets a component from the host object using its type. Throws if no component of the type exists, or if more than one component of the type exists — in the multi-match case, getComponentByType deliberately does not pick one for you. Use ComponentHost.getComponentsByType when you genuinely expect multiple matches, or look the component up by its string key.

Performs an O(n) lookup once per type initially, then caches the resolved key for O(1) lookups on subsequent calls. The cache is invalidated whenever a component is removed.

Gets every component on the host of the given type, in the order they were originally registered. Returns an empty array if no components match.

Unlike ComponentHost.getComponentByType, this method never throws on multiplicity — it is the explicit "I expect more than one" accessor.

Gets a reference to the host object that this component is attached to. Required for the compiler to be able to resolve the type of the host object correctly in some internal function calls (e.g. when resolving the type of the host object from a factory function).

Gets a component from the host object using the key it was registered with. Returns null if the component does not exist, rather than throwing an error. Useful for referencing transient or optional components without manually handling errors.

Gets a component from the host object using its type. Returns null if the component does not exist or if more than one component of the type is registered (i.e. the lookup is ambiguous) — the nullable variant collapses both "not found" and "ambiguous" into a single null. Use ComponentHost.getComponentsByType when you need to distinguish them.

Checks if the host object has a component with the specified key.

Checks if the host object has a component with the specified type.

Maps a point expressed in this object's local space into world space, threading the full ancestry: the point is taken through this object's own scale → rotate → translate (relative to its parent) and then up through every ancestor. (0, 0) always maps to the host's WorldObject.worldPosition, and a local point "10 units along +x" lands wherever the host is facing in the world, scaled by the host's and every ancestor's scale. For a root object this is just the host's own scale → rotate → translate.

Pairs with WorldObject.worldToLocal — round-tripping a point through both methods is the identity (modulo floating-point error).

Allocates a fresh Point per call so callers can mutate the result without affecting host state.

Lifecycle hook called when this object is actually removed from the world. Idempotent — repeat invocations are no-ops, so callers can fire it defensively without worrying about double-cleanup of components.

Detaches the object from its parent so the parent's WorldObject.children list never holds a cleaned object. Children of this object are not touched here: WorldObject.destroy already marked the whole subtree, so each child receives its own onDestroy (and detaches itself) during the same world sweep.

Drives the onPostUpdate phase across this object's components. Called by the World during the post-update pass of each tick. Skips components whose enabled is explicitly false, and components that do not implement the optional hook.

Drives the onPreUpdate phase across this object's components. Called by the World during the pre-update pass of each tick. Skips components whose enabled is explicitly false, and components that do not implement the optional hook.

Drives the onUpdate phase across this object's components. Called by the World during the main update pass of each tick. Skips components whose enabled is explicitly false.

Removes all components from the host object. Typically called internally when the lifecycle of the host object is terminated. Differs from individually removing components in that it first calls onDestroy() on each component, then removes references from the host object in a separate step. This allows cleaner teardown of components that may reference each other.

Detaches child from this object, returning it to the world root. Equivalent to child.setParent(null, options) — but a no-op (rather than a re-rooting) if child is not actually a child of this object, so it is safe to call defensively.

Removes a component from the host object and returns it, so callers can keep inspecting the detached component (or move it to another host). Care should be taken when manually removing components, as methods like getComponent() will throw if components do not exist. Removal is idempotent: removing a key that does not exist (already removed, or never present) is a no-op that returns null.

The component's onDestroy runs while it is still registered (so it can reach its siblings during teardown); a throw from onDestroy is routed to the host's error channel rather than propagating, and the component is removed from the host either way.

Removes several components in one batch, mirroring the four addComponents* variants on the add side. Unlike calling ComponentHost.removeComponent in a loop, this runs every targeted component's onDestroy first and only then deletes them — so two interdependent components can still reach each other during teardown, the same guarantee ComponentHost.removeAllComponents provides, scoped to the named subset. Unknown keys are skipped silently.

Re-homes this object in the transform hierarchy, making parent its new parent (or detaching it to become a root when parent is null). The parent's WorldObject.children list and this object's WorldObject.parent are updated together so the two never disagree.

By default the object's world transform is preserved — its local position/rotation/scale are recomputed so it does not visibly move (see SetParentOptions.keepWorldTransform to opt out and keep the local transform instead).

Maps a point expressed in world space into this object's local coordinate system — the inverse of WorldObject.localToWorld, threading the full ancestry in reverse (root-ward ancestors first, then this object). This is the primitive that hit-tests and other shape-vs-world queries are built on: convert the world point to local, then ask the local-space shape (a Polygon, a Circle, ...) whether it contains it — and because it accounts for ancestry, the query is correct even for a parented object whose shape is defined in local space.

Axes with zero WorldObject.scale are left untouched on that axis (rather than dividing by zero); a fully zero-scaled object collapses to a point and containment against it is undefined either way, so this is just the cheaper of two equally-degenerate behaviours.

Allocates a fresh Point per call.