Event System

Next2D Player uses a three-phase event flow mechanism similar to the W3C DOM event model.

EventDispatcher

The base class for all event-capable objects.

addEventListener(type, listener, useCapture, priority)

Registers an event listener.

const { PointerEvent } = next2d.events;

displayObject.addEventListener(PointerEvent.POINTER_DOWN, (event) => {
    console.log("Pointer pressed");
});

// Receive in capture phase
displayObject.addEventListener(PointerEvent.POINTER_DOWN, handler, true);

// Specify priority
displayObject.addEventListener(PointerEvent.POINTER_DOWN, handler, false, 10);

removeEventListener(type, listener, useCapture)

Removes an event listener.

displayObject.removeEventListener(PointerEvent.POINTER_DOWN, handler);

removeAllEventListener(type, useCapture)

Removes all event listeners of a specific type.

displayObject.removeAllEventListener(PointerEvent.POINTER_DOWN);

hasEventListener(type)

Checks if a listener of the specified type is registered.

if (displayObject.hasEventListener(PointerEvent.POINTER_DOWN)) {
    console.log("Pointer down listener is registered");
}

willTrigger(type)

Checks if this object or any ancestor has a listener for the event type.

if (displayObject.willTrigger(PointerEvent.POINTER_DOWN)) {
    console.log("This object or an ancestor has a listener");
}

dispatchEvent(event)

Dispatches an event.

const { Event } = next2d.events;

const event = new Event("customEvent");
displayObject.dispatchEvent(event);

Event Class

Properties

Property	Type	Description
type	String	Event type
target	Object	Event source
currentTarget	Object	Current listener target
eventPhase	Number	Event phase
bubbles	Boolean	Whether bubbles

Methods

Method	Description
stopPropagation()	Stop propagation
stopImmediatePropagation()	Stop propagation immediately

Standard Event Types

Display List Related

Event	Description
added	Added to DisplayObjectContainer
addedToStage	Added to Stage
removed	Removed from DisplayObjectContainer
removedFromStage	Removed from Stage

sprite.addEventListener("addedToStage", (event) => {
    console.log("Added to stage");
});

Timeline Related

Event	Description
enterFrame	Occurs each frame
frameConstructed	Frame construction complete
exitFrame	When leaving frame

movieClip.addEventListener("enterFrame", (event) => {
    // Processing executed every frame
    updatePosition();
});

Load Related

Event	Description
complete	Load complete
progress	Load progress
ioError	IO error
httpStatus	HTTP status received

const { Loader } = next2d.display;
const { URLRequest } = next2d.net;

const loader = new Loader();

// Loading with async/await
await loader.load(new URLRequest("animation.json"));
const content = loader.content;
stage.addChild(content);

// Using progress events
loader.contentLoaderInfo.addEventListener("progress", (event) => {
    const percent = (event.bytesLoaded / event.bytesTotal) * 100;
    console.log(`${percent}% loaded`);
});

Pointer Events

PointerEvent handles pointer device interactions (mouse, pen, touch) in a unified way.

Event	Constant	Description
pointerDown	PointerEvent.POINTER_DOWN	Button press started
pointerUp	PointerEvent.POINTER_UP	Button released
pointerMove	PointerEvent.POINTER_MOVE	Pointer coordinates changed
pointerOver	PointerEvent.POINTER_OVER	Pointer entered hit test boundary
pointerOut	PointerEvent.POINTER_OUT	Pointer left hit test boundary
pointerLeave	PointerEvent.POINTER_LEAVE	Pointer left element area
pointerCancel	PointerEvent.POINTER_CANCEL	Pointer interaction canceled
doubleClick	PointerEvent.DOUBLE_CLICK	Double-click/tap occurred

const { PointerEvent } = next2d.events;

sprite.addEventListener(PointerEvent.POINTER_DOWN, (event) => {
    console.log("Pointer down:", event.localX, event.localY);
});

sprite.addEventListener(PointerEvent.POINTER_MOVE, (event) => {
    console.log("Pointer move:", event.stageX, event.stageY);
});

sprite.addEventListener(PointerEvent.DOUBLE_CLICK, (event) => {
    console.log("Double click");
});

Keyboard Events

Event	Constant	Description
keyDown	KeyboardEvent.KEY_DOWN	Key pressed
keyUp	KeyboardEvent.KEY_UP	Key released

const { KeyboardEvent } = next2d.events;

stage.addEventListener(KeyboardEvent.KEY_DOWN, (event) => {
    console.log("Key code:", event.keyCode);

    switch (event.keyCode) {
        case 37: // Left arrow
            player.x -= 10;
            break;
        case 39: // Right arrow
            player.x += 10;
            break;
    }
});

Focus Events

Event	Constant	Description
focusIn	FocusEvent.FOCUS_IN	Element received focus
focusOut	FocusEvent.FOCUS_OUT	Element lost focus

const { FocusEvent } = next2d.events;

textField.addEventListener(FocusEvent.FOCUS_IN, (event) => {
    console.log("Received focus");
});

Wheel Events

Event	Constant	Description
wheel	WheelEvent.WHEEL	Mouse wheel rotated

const { WheelEvent } = next2d.events;

stage.addEventListener(WheelEvent.WHEEL, (event) => {
    console.log("Wheel rotated");
});

Video Events

Event	Constant	Description
play	VideoEvent.PLAY	Play requested
playing	VideoEvent.PLAYING	Playback started
pause	VideoEvent.PAUSE	Paused
seek	VideoEvent.SEEK	Seek operation

Job Events

Events for Tween animations.

Event	Constant	Description
update	JobEvent.UPDATE	Property updated
stop	JobEvent.STOP	Job stopped

Custom Events

const { Event } = next2d.events;

// Define custom event
const customEvent = new Event("gameOver", true, true);

// Dispatch event
gameManager.dispatchEvent(customEvent);

// Listen to event
gameManager.addEventListener("gameOver", (event) => {
    showGameOverScreen();
});

Event Propagation

Events propagate in three phases:

1. Capture phase: From root to target (eventPhase = 1)
2. Target phase: Processed at target (eventPhase = 2)
3. Bubbling phase: From target to root (eventPhase = 3)

const { PointerEvent } = next2d.events;

// Process in capture phase
parent.addEventListener(PointerEvent.POINTER_DOWN, handler, true);

// Process in bubbling phase (default)
child.addEventListener(PointerEvent.POINTER_DOWN, handler, false);

Related

• DisplayObject
• MovieClip