willow

willow is ThicketScript's 2D module. It is a display tree, in the spirit of Flash and Starling: you build a tree of nodes, set each one's position, scale, rotation and colour, and willow draws the whole tree every frame. You never issue draw calls yourself.

It is built into thicket. List it under systems in thicket.json and import what you need from "willow".

A minimal program

{
    entry: "app.tks",
    systems: ["willow"],
    window: { title: "Hello willow", width: 800, height: 600 },
}

import { Quad } from "willow";

class Hello {
    static main(): void {
        const box: Quad = new Quad(120, 120, Color.hex("#4FA3E0"));
        box.setAnchor(0.5, 0.5);
        box.x = 400;
        box.y = 300;
        engine.root2d.add(box);

        App.onFrame((dt: float): void => {
            box.rotation += Math.PI * dt;
        });
    }
}

A blue square spins in the middle of the window, half a turn per second.

• new Quad(w, h, color) makes a solid rectangle node.
• engine.root2d is the root of the 2D tree. A node is drawn once it is in the tree.
• App.onFrame runs once per drawn frame. dt is the frame time in seconds.

How willow fits

A GPU renderer forgets everything between frames: each frame, every draw has to be issued again. willow keeps a retained tree on top of it. You describe what exists (a sprite here, a label there), and each frame willow walks the tree, works out where everything is, sorts it and turns it into as few GPU draws as it can.

Your game      gameplay, content, rules
willow         the node tree, transforms, draw order, batching, hit testing
thicket        the window, the GPU, input, audio, the ThicketScript runtime

What willow is not:

• Not a widget toolkit. It has no buttons, lists or layout. For those, use willowui, which is built on willow nodes.
• Not a game framework. It does not decide how you structure entities, levels or saves. It draws your tree and routes input to it; the rest is your code.

Where to go next

Start

Getting started

A window, a sprite, and moving it with the keyboard.

Concept

The scene graph

How the tree, the scene, the camera and layers fit together.

Concept

Nodes and transforms

Position, pivot, scale, rotation, alpha, and converting between spaces.

Guide

Sprites and textures

Images, regions, atlases, sprite batches and frame animation.

Guide

Text and fonts

Labels, TTF fonts, pixel fonts, effects and text input.

Guide

Input and hit testing

Clicks, drags, wheel and pinch on nodes, plus keyboard and gamepad.

How-to

Recipes

Short answers to common tasks.

Gotchas

Common pitfalls

Radians, pivots, dispose, hit testing and the other usual surprises.

Guide

Performance

Batching, sprite batches, cached subtrees, tilemaps and culling.

API

Reference

Every willow class, generated from its type declarations.

What is in willow

Area	What you get	Guide
Tree	Node, the scene's world and screen roots, render layers, events	The scene graph
Images	Sprite, SpriteBatch, Texture, TextureRegion, Atlas, AnimationPlayer	Sprites and textures
Text	Text, Font (bundles, TTF, pixel fonts), outline, glow and shadow	Text and fonts
Shapes	Quad, Quad.line, Polygon, Mesh, custom paint	Shapes and meshes
Motion	TweenGroup, node tickers, Transition between screens	Tweens and transitions
Time	onUpdate, onTick, pause, time scale, interpolation	Lifecycle and time
Interaction	Pointer handlers, hit shapes, drag, wheel, pinch, pointer capture	Input and hit testing
World	Camera2D, TileLayer, TilemapViewport, NodeIndex	Camera and layers, Tilemaps
Effects	Particles, filters, masks, lighting, render textures	Effects
Advanced	Rope, DistortionGrid, physics bodies	Rope and distortion, Physics

Without a window

A console program can list willow too. The node tree, transforms, hit shapes, events, NodeIndex, physics and text measuring work with no window or GPU, which is useful for tools, servers and tests. Loading images needs a window. See Running without a window.