Scene

The app's scene: its world root, screen root, camera, layers, keys and transitions. Module willow-scene, read without an import.

Scene

class Scene

A scene: its root node, size, focus and key callbacks. Willow declares it, so a host that binds a willow::Scene (the thicket program, or a C++ application) gets the same script type.

Scene: properties

Member	Description
readonly root: Node	The scene's root node.
readonly screenRoot: Node	The scene's screen-space root (engine.screen2d): drawn after the world without the camera, in screen units (the framebuffer, in the units the camera viewport is given in), so a menu or HUD added here does not scroll or zoom. Input reaches it first; only a visible, interactive node takes an event, otherwise the event falls through to the world. Screen-sized things go here; world-sized ones (damage numbers, a name tag that zooms) stay under root. Use node.toScreen(x, y) to place a screen node over a world point.
readonly camera: Camera2D | null	The scene's 2D camera (the same object as engine.camera), or null until a host binds one. World (0, 0) stays at the top-left of the window until the script moves the camera.
readonly index: NodeIndex | null	The scene's tag index: every node that is added with add(node...tags) can be found by name or tag, and a node that is disposed leaves it. Null until a host binds the scene.
readonly width: int	Scene width in logical pixels.
readonly height: int	Scene height in logical pixels.
backgroundColor: int	Background colour as a packed colour int. It is the scene's clear colour; the window shows it.
readonly frameTime: float	Seconds the last frame took.
readonly elapsed: float	Seconds since the scene started.
focus: Node | null	Focused node, or null. An INPUT Text starts IME text input.
readonly LAYER_BACKGROUND: int	Reserved Node.renderLayer convention for backdrop content that sits behind everything. Value: 0. See Node.renderLayer.
readonly LAYER_DEFAULT: int	Reserved Node.renderLayer convention for ordinary world/game content. Value: 64. Leaves room below for backdrops and above for UI. See Node.renderLayer.
readonly LAYER_UI: int	Reserved Node.renderLayer convention for UI/HUD drawn over the world. Value: 192. See Node.renderLayer.
readonly LAYER_OVERLAY: int	Reserved Node.renderLayer convention for topmost overlays (transitions, debug). Value: 255 (willow's max layer). See Node.renderLayer.

Scene: methods

Member	Description
add(child: Node): Node	Adds a child to the scene root. - child: The node to add. - Returns: The added node.
remove(child: Node): Node	Removes a child from the scene root. - child: The node to remove. - Returns: The removed node.
onKeyDown(cb: Function): Function	Registers a callback for every key-down transition, in arrival order. It receives a KeyEvent. - cb: The callback. - Returns: A function that unregisters it.
onKeyUp(cb: Function): Function	Registers a callback for every key-up transition, in arrival order. It receives a KeyEvent. - cb: The callback. - Returns: A function that unregisters it.
onBackgroundClick(cb: Function): Function	Registers a callback invoked when a pointer click lands on the empty scene background (missed all nodes). The callback receives a PointerEvent carrying coordinates, button, and modifiers bitmask matching KeyModifiers.
playTransition(transition: Transition, from: Node, to: Node, fromScreen?: Node, toScreen?: Node): Promise<void>	Plays transition between two nodes of this scene: from leaves, to arrives. Both are normally children of root. While it plays the scene draws every other node as usual and the two subtrees only through the transition. Both are drawn the way the scene draws them (through the camera, with light layers, filters and masks), and the transition composites where to sorts: at its render layer, so a HUD on a higher layer such as LAYER_UI stays on top. The returned promise resolves once, when the transition ends. The scene never removes or disposes either node: from stays in the tree and alive until then, and the caller retires it after the promise resolves. A node disposed while the transition plays ends it. The promise rejects when a transition is already playing or the scene is not backed by a Willow scene. - transition: The effect, for example Transition.fade(0.3). - from: The outgoing node. - to: The incoming node. - fromScreen: Optional: the outgoing side's subtree under screenRoot (its dialogue box, its menu). It is drawn without the camera over from and fades with it; screen nodes outside the pair (a toast, a debug HUD) stay on top, untouched. - toScreen: Optional: the incoming side's subtree under screenRoot. - Returns: A promise that resolves when the transition has ended.
cancelTransition(): boolean	Stops the transition that is playing, at once. Its playTransition promise REJECTS with a string starting CancellationError (it does not resolve: the transition never finished, and a caller that retires from after the promise must not do so on a cancel). The scene lets go of both nodes and touches neither: from stays in the tree and alive, to stays too, and the caller decides what to do with them. A new playTransition may start in the same call stack. Does nothing when no transition is playing. - Returns: true when a transition was playing and is now cancelled, false when there was none.

Scene: static properties

Member	Description
static readonly main: Scene | null	The app's scene, the same object as engine.scene, or null until a host binds one (a console program, willow without a window, has none). Prefer this to engine in library code: a package that names engine needs a window app, one that reads Scene.main loads anywhere.

KeyEvent

class KeyEvent

Payload of Scene.onKeyDown / onKeyUp. keyCode equals the Key.* constant of the physical key; label is the printed character on the current layout and charCode its code point (0 for non-printing keys).

KeyEvent: properties

Member	Description
readonly keyCode: int	The Key.* constant of the physical key.
readonly charCode: int	Code point of the printed character; 0 for non-printing keys.
readonly label: string	The printed character on the current layout.
readonly repeat: boolean	True for an auto-repeat.
readonly shiftKey: boolean	True while Shift is held.
readonly ctrlKey: boolean	True while Ctrl is held.
readonly altKey: boolean	True while Alt is held.
readonly metaKey: boolean	True while Meta (Windows/Command) is held.