willow family

Presentation bindings from game records to willow nodes, and the pointer and key input bridge.

Import these from gamekit/src/willow (a few are also re-exported by the package root, as noted on each).

15 symbols, 0 of them also in the package root.

Symbol	Summary
WillowBinding	class. Coordinates the WillowBinding presentation resource and its lifetime.
WillowBindingTicket	class. Coordinates the WillowBindingTicket presentation resource and its lifetime.
WillowInputBridge	class. Adapts Willow pointer samples into explicit game-owned input offers.
WillowInputConsumer	enum. Defines the closed willow input consumer value set.
WillowInputFrame	class. Carries WillowInputFrame state across the presentation-to-game boundary.
WillowInputInspection	class. Carries WillowInputInspection state across the presentation-to-game boundary.
WillowInputOwner	class. Carries WillowInputOwner state across the presentation-to-game boundary.
WillowInputTarget	class. Carries WillowInputTarget state across the presentation-to-game boundary.
WillowKeySample	class. Represents the runtime willow key sample value and its explicit state.
WillowPointerPhase	enum. Defines the closed willow pointer phase value set.
WillowPointerSample	class. Represents the runtime willow pointer sample value and its explicit state.
WillowPresentation	class. Coordinates the WillowPresentation presentation resource and its lifetime.
WillowPresentationAdapter	class. Coordinates the WillowPresentationAdapter presentation resource and its lifetime.
WillowPresentationState	class. Coordinates the WillowPresentationState presentation resource and its lifetime.
WillowViewport	class. Represents the runtime willow viewport value and its explicit state.

WillowBinding

import { WillowBinding } from "gamekit/src/willow";
class WillowBinding<T>

Coordinates the WillowBinding presentation resource and its lifetime.

Members

constructor(adapter: any, record: T)

Initializes a willow binding with explicit dependencies.

• adapter: Presentation adapter that creates and synchronizes the Willow node.
• record: Initial game record retained until replacement, pooling, or disposal.

get active(): boolean

Reports whether the binding participates in the next presentation pass.

• Returns: True only in the active lifecycle state.

get detached(): boolean

Reports whether the binding retains a node that has been removed from its parent.

• Returns: True only after detach and before attach or another terminal transition.

get pooled(): boolean

Reports whether the binding retains a detached node but no game record.

• Returns: True only after pool and before reuse or disposal.

get disposed(): boolean

Reports whether the binding has permanently released its node and record.

• Returns: True after dispose; the state never becomes live again.

get generation(): int

Exposes the revision used to invalidate asynchronous tickets.

• Returns: A monotonically increasing revision changed by each lifecycle mutation.

ticket(): WillowBindingTicket<T>

Captures the current generation for guarded asynchronous completion.

• Returns: A ticket that applies callbacks only while this binding remains active at that generation.

detach(): void

Removes the node from Willow while retaining it for a later attach.

• Throws: Error When called on a pooled binding.

attach(): void

Reactivates a detached binding; the next presentation pass reparents its node.

• Throws: Error Unless the binding is detached and not disposed.

pool(): void

Detaches the node, clears the record, and invalidates all outstanding tickets.

reuse(record: T): void

Reactivates a pooled node for a new record and generation.

• record: New record synchronized on the next presentation pass.
• Throws: Error Unless the binding is pooled and not disposed.

replace(record: T): void

Invalidates tickets and disposes the current node before adopting a replacement record.

• record: Replacement record whose node is created on the next presentation pass.
• Throws: Error When the binding is pooled or disposed.

dispose(): void

Permanently releases the record and owned node; repeated calls do nothing.

WillowBindingTicket

import { WillowBindingTicket } from "gamekit/src/willow";
class WillowBindingTicket<T>

Coordinates the WillowBindingTicket presentation resource and its lifetime.

Members

constructor(binding: any, generation: int)

Initializes a willow binding ticket with explicit dependencies.

• binding: Binding consulted when asynchronous work completes.
• generation: Binding revision captured before that work began.

apply(callback: Function): boolean

Guards a deferred node mutation against lifecycle and record changes.

• callback: Function invoked as (node, record) only while the captured generation is live.
• Returns: True when the callback ran; false when the ticket is stale or its binding is inactive.

WillowInputBridge

import { WillowInputBridge } from "gamekit/src/willow";
class WillowInputBridge

Adapts Willow pointer samples into explicit game-owned input offers. Retain one bridge per presentation boundary and register targets in explicit priority order; it never owns a simulation World.

Members

constructor(policy: InputPolicy | null = null)

Initializes WillowInputBridge with explicit dependencies and configuration.

• policy: Optional neutral policy used to build action frames and process focus loss.

register(target: WillowInputTarget): void

Adds a registration and rejects a duplicate live identity.

• target: Target retained until explicitly unregistered.
• Throws: Error When its id or priority is already registered, or its viewport is unknown.

unregister(id: string): boolean

Removes a registration and releases any state it owns.

• id: Target identifier to remove.
• Returns: True when a target was removed; false when no registration matched.

addViewport(viewport: WillowViewport): void

Registers a viewport for pointer projection and overlap selection.

• viewport: Viewport retained until the bridge is released.
• Throws: Error When its id or priority is already registered.

pointer(sample: WillowPointerSample): WillowInputFrame

Routes one pointer sample to the highest eligible target and maintains capture. A DOWN sample captures its selected owner until UP or focus loss, so later samples cannot retarget mid-gesture.

• sample: Willow-normalized pointer fact for this presentation frame.
• Returns: Owner and offers for the selected target plus the neutral button sample.

actionFrame(): ActionFrame | null

Builds a policy-resolved action frame from the core InputMap when a policy is configured.

• Returns: The policy-resolved frame, or null when the bridge has no policy.

focusLost(): ActionFrame | null

Cancels active captures and forwards focus loss to the input policy.

• Returns: The policy's focus-loss frame, or null when no policy is configured.

drainCancelled(): WillowInputOwner[]

Returns and clears the queued cancelled interaction owners.

• Returns: Independent snapshots in cancellation order; a second drain is empty.

inspect(): WillowInputInspection

Builds a copy suitable for diagnostic inspection.

• Returns: Capture snapshots and registered ids that can be retained independently.

WillowInputConsumer

import { WillowInputConsumer } from "gamekit/src/willow";
enum WillowInputConsumer

Defines the closed willow input consumer value set. Store and compare these values directly rather than introducing string aliases;

Member	Meaning
WORLD = "world"	Input is offered to world presentation.
UI = "ui"	Input is offered to ordinary interface controls.
MODAL = "modal"	Input is offered to a blocking interface layer.
TEXT_ENTRY = "text-entry"	Input is offered to editable text controls.
DEBUG = "debug"	Input is offered to diagnostic controls.

WillowInputFrame

import { WillowInputFrame } from "gamekit/src/willow";
class WillowInputFrame

Carries WillowInputFrame state across the presentation-to-game boundary.

Members

owner: WillowInputOwner | null

Pointer capture owner selected for this frame, or null when no target matched.

offers: any[]

Detached interaction offers returned by the selected target.

sample: InputSample

Neutral input sample derived from the Willow pointer event.

constructor(owner: WillowInputOwner | null, offers: any[], sample: InputSample)

Initializes a willow input frame with explicit dependencies.

• owner: Selected pointer capture owner, copied when non-null.
• offers: Interaction offers copied into the frame.
• sample: Neutral input sample for the current presentation frame.

WillowInputInspection

import { WillowInputInspection } from "gamekit/src/willow";
class WillowInputInspection

Carries WillowInputInspection state across the presentation-to-game boundary.

Members

owners: WillowInputOwner[]

Snapshots of active pointer capture owners.

targetIds: string[]

Registered target identifiers in bridge order.

viewportIds: string[]

Registered viewport identifiers in bridge order.

constructor(owners: WillowInputOwner[], targetIds: string[], viewportIds: string[])

Initializes a willow input inspection with explicit dependencies.

• owners: Active capture snapshots prepared by the bridge.
• targetIds: Registered target identifiers.
• viewportIds: Registered viewport identifiers.

WillowInputOwner

import { WillowInputOwner } from "gamekit/src/willow";
class WillowInputOwner

Carries WillowInputOwner state across the presentation-to-game boundary.

Members

pointerId: int

Pointer identifier retained for the full capture lifetime.

targetId: string

Identifier of the target that won capture.

consumer: WillowInputConsumer

Consumer notified for this captured interaction.

screen: Vec2

Most recent pointer position in screen coordinates.

world: Vec2 | null

Most recent camera-projected position, or null outside a viewport.

viewportId: string | null

Viewport used for world projection, or null when none matched.

cancelled: boolean

WillowInputOwner: whether this interaction ended through cancellation.

constructor(pointerId: int, targetId: string, consumer: WillowInputConsumer, screen: Vec2, world: Vec2 | null, viewportId: string | null, cancelled: boolean = false)

Initializes a willow input owner with explicit dependencies.

• pointerId: Pointer identifier whose capture is represented.
• targetId: Identifier of the target that won capture.
• consumer: Recipient for interaction callbacks.
• screen: Pointer position in screen coordinates; copied on construction.
• world: Projected world position, or null; copied when present.
• viewportId: Viewport used for projection, or null.
• cancelled: True when focus loss cancelled the interaction.

copy(): WillowInputOwner

Returns a snapshot with independent coordinate values.

• Returns: A copy retaining the same consumer reference and capture facts.

WillowInputTarget

import { WillowInputTarget } from "gamekit/src/willow";
class WillowInputTarget

Carries WillowInputTarget state across the presentation-to-game boundary.

Members

id: string

Unique identifier used for registration and capture ownership.

consumer: WillowInputConsumer

Consumer that receives interactions selected for this target.

node: any

Willow node whose hit-test ancestry makes a sample eligible; null matches globally.

priority: int

Explicit ordering priority; larger values win conflicts.

viewportId: string | null

Viewport used to project matching pointer coordinates, or null.

constructor(id: string, consumer: WillowInputConsumer, node: any, priority: int, viewportId: string | null = null, offersFor: Function | null = null)

Initializes a willow input target with explicit dependencies.

• id: Non-empty registration and capture identifier.
• consumer: Recipient for interactions selected for the target.
• node: Willow hit-test node, or null to match every sample.
• priority: Selection priority; larger values win.
• viewportId: Optional viewport for world-coordinate projection.
• offersFor: Optional callback returning offers for a newly captured owner.
• Throws: Error When id is empty.

matches(sample: WillowPointerSample): boolean

WillowInputTarget Tests whether the sample is eligible for this target.

• sample: Pointer sample carrying the Willow hit ancestry.
• Returns: True for a global target or when node appears in the hit ancestry.

offers(owner: WillowInputOwner): any[]

Evaluates the optional offer factory for a captured interaction.

• owner: Snapshot passed to the offer factory.
• Returns: A detached offer list, or an empty list when no offers are available.

WillowKeySample

import { WillowKeySample } from "gamekit/src/willow";
class WillowKeySample

Represents the runtime willow key sample value and its explicit state.

Members

control: string

Neutral control name, conventionally Key.<keyCode> for Willow events.

down: boolean

True for key-down and false for key-up.

repeating: boolean

True when Willow marks the key event as an auto-repeat.

constructor(control: string, down: boolean, repeating: boolean = false)

Initializes a willow key sample with explicit dependencies.

• control: Non-empty neutral control name.
• down: True for press and false for release.
• repeating: Whether this is an auto-repeat event.
• Throws: Error When control is empty.

inputSample(): InputSample

Converts the key fact to the neutral input representation.

• Returns: A keyboard sample with value 1 for down or 0 for up.

static fromWillow(event: any, down: boolean): WillowKeySample

Adapts a Willow key event without retaining the event object.

• event: Willow event exposing keyCode and repeat.
• down: True for a key-down callback and false for key-up.
• Returns: A sample named from the Willow key code.

WillowPointerPhase

import { WillowPointerPhase } from "gamekit/src/willow";
enum WillowPointerPhase

Defines the closed willow pointer phase value set. Store and compare these values directly rather than introducing string aliases;

Member	Meaning
DOWN = "down"	The pointer began contact.
MOVE = "move"	The pointer moved while tracked.
UP = "up"	The pointer ended contact.

WillowPointerSample

import { WillowPointerSample } from "gamekit/src/willow";
class WillowPointerSample

Represents the runtime willow pointer sample value and its explicit state.

Members

pointerId: int

Pointer identity used to maintain capture across event phases.

phase: WillowPointerPhase

Current down, move, or up phase.

screen: Vec2

Pointer position in Willow screen coordinates.

button: int

Willow button number associated with the event.

hit: any

Primary Willow hit target, or null when nothing was hit.

hits: any[]

Hit-test ancestry used to select eligible input targets.

constructor(pointerId: int, phase: WillowPointerPhase, screenX: float, screenY: float, button: int = 0, hit: any = null, hits: any[] = [])

Initializes a willow pointer sample with explicit dependencies.

• pointerId: Pointer identity retained through capture.
• phase: Current pointer event phase.
• screenX: Horizontal screen coordinate.
• screenY: Vertical screen coordinate.
• button: Willow button number.
• hit: Primary hit target, inserted into hits when absent.
• hits: Hit ancestry copied into the sample.

static fromWillow(event: any, phase: WillowPointerPhase, hits: any[] = []): WillowPointerSample

Adapts Willow pointer coordinates, button, and target without retaining the event.

• event: Willow event exposing screenX, screenY, button, and target. The screen position is kept raw, because the bridge converts it to world through the viewport camera exactly once.
• phase: Phase assigned by the callback that received the event.
• hits: Hit ancestry supplied by the game integration.
• Returns: A pointer-zero sample containing copies of the supplied hit list.

inputSample(): InputSample

Converts the pointer button phase to the neutral input representation.

• Returns: A device-specific button sample with value 0 on up and 1 otherwise.

WillowPresentation

import { WillowPresentation } from "gamekit/src/willow";
class WillowPresentation<T>

Coordinates the WillowPresentation presentation resource and its lifetime.

Members

constructor(adapter: WillowPresentationAdapter<T>, record: T)

Initializes a willow presentation with explicit dependencies.

• adapter: Adapter that owns bindings and presentation passes.
• record: Initial game record represented by the component.

onAttach(owner: Entity): void

Creates, reattaches, or reuses the binding when the component enters an entity.

• owner: Entity receiving the component; ownership itself remains with the ECS.

onDetach(owner: Entity): void

Detaches the Willow node while preserving it for a later entity transfer.

• owner: Entity releasing the component.

onDispose(owner: Entity): void

Permanently disposes the binding when the owning entity is torn down.

• owner: Entity whose component lifetime has ended.

replace(record: T): void

Replaces the game record and invalidates any node created for the previous record.

• record: Record to present on the next adapter pass.

ticket(): WillowBindingTicket<T>

Captures the attached binding generation for guarded asynchronous work.

• Returns: A ticket tied to the current record and lifecycle revision.
• Throws: Error Before the component has attached to an entity.

WillowPresentationAdapter

import { WillowPresentationAdapter } from "gamekit/src/willow";
class WillowPresentationAdapter<T>

Coordinates the WillowPresentationAdapter presentation resource and its lifetime.

Members

constructor(createNode: Function, readState: Function, syncNode: Function | null = null)

Initializes a willow presentation adapter with explicit dependencies.

• createNode: Factory called with a record when an active binding has no node.
• readState: Callback returning transform and parent state for each presented record.
• syncNode: Optional callback for content synchronization after transform state is copied.

get disposed(): boolean

Reports whether all bindings have been disposed and future binds are forbidden.

• Returns: True after the first call to dispose.

bind(record: T): WillowBinding<T>

Associates supplied records with the caller's presentation factory.

• record: Game record retained by the new binding.
• Returns: An active binding whose node is created at the next presentation boundary.
• Throws: Error After the adapter has been disposed.

present(): void

Presents a snapshot of current bindings and then forgets disposed entries.

dispose(): void

WillowPresentationAdapter Releases retained resources and makes later use invalid.

• Throws: Error When the supplied value violates this operation’s preconditions.

WillowPresentationState

import { WillowPresentationState } from "gamekit/src/willow";
class WillowPresentationState

Coordinates the WillowPresentationState presentation resource and its lifetime.

Members

parent: any

Willow container that should own the presented node.

x: float = 0.0

Horizontal position in parent coordinates.

y: float = 0.0

Vertical position in parent coordinates.

rotation: float = 0.0

Node rotation forwarded to Willow.

scaleX: float = 1.0

Horizontal scale factor; defaults to 1.

scaleY: float = 1.0

Vertical scale factor; defaults to 1.

pivotX: float = 0.0

Horizontal transform pivot in node coordinates.

pivotY: float = 0.0

Vertical transform pivot in node coordinates.

skewX: float = 0.0

Horizontal skew forwarded to Willow.

skewY: float = 0.0

Vertical skew forwarded to Willow.

alpha: float = 1.0

Opacity forwarded to Willow; defaults to fully opaque.

visible: boolean = true

Whether Willow should render the node.

zOrder: int = 0

Sibling ordering value forwarded to Willow.

constructor(parent: any)

Initializes a willow presentation state with explicit dependencies.

• parent: Willow container that receives the node during presentation.

WillowViewport

import { WillowViewport } from "gamekit/src/willow";
class WillowViewport

Represents the runtime willow viewport value and its explicit state.

Members

id: string

Unique identifier referenced by input targets and capture owners.

screen: Rect

Screen-space rectangle in which this viewport participates.

camera: Camera2D

Camera used to project matching screen coordinates into world space.

priority: int

Explicit ordering priority; larger values win conflicts.

constructor(id: string, screen: Rect, camera: Camera2D, priority: int)

Initializes a willow viewport with explicit dependencies.

• id: Non-empty viewport identifier.
• screen: Screen-space bounds copied into the viewport.
• camera: Camera retained for coordinate projection.
• priority: Selection priority; larger values win overlaps.
• Throws: Error When id is empty.

contains(point: Vec2): boolean

Tests a point against the inclusive screen-space bounds.

• point: Screen-space coordinate to test.
• Returns: True when both coordinates lie on or inside the rectangle edges.