onmessage API

All input events use the builtin addEventListener("message", callback) function.

Event Structure

Every message event follows this structure:

event: {
  data: {
    type: string; // The event type
    payload: any; // Event-specific data
  }
}

Basic Usage Example

main.ts

let canvas;

addEventListener("message", ({ data }) => {
  const { type, payload } = data;

  if (type === "oncanvas") {
    canvas = payload.canvas;
  } else if (type === "onkeydown") {
    const { key } = payload;
  } else if (type === "onkeyup") {
    const { key } = payload;
  }
});

Event Types

Different event types are identified through the type propery of the message event. This determines the event as well as what the payload will look like.

oncanvas: Provides the OffscreenCanvas and rendering context for drawing along with sessionId and pixel ratio info.
onresize: Triggered when the canvas is resized, providing updated dimensions and pixel ratio.
onfocus: Fired when the canvas gains focus.
onblur: Fired when the canvas loses focus, useful for pausing activity.
onlisten: Receives broadcasted messages from other players in a multiplayer session.
onjoin: Triggered when a new player joins the session.
onleave: Triggered when a player leaves the session.
onsync: Provides the current list of active sessions, typically after a join or leave event.
onstatus: Indicates multiplayer connection status changes (e.g., connected, timed out, closed).
onkeydown: Triggered when a key is pressed down.
onkeyup: Triggered when a key is released.
onpointerenter: Triggered when a pointer enters the canvas area.
onpointerleave: Triggered when a pointer exits the canvas area.
onpointerdown: Triggered when a pointer is pressed down on the canvas.
onpointerup: Triggered when a pointer is released.
onpointermove: Triggered when a pointer moves across the canvas.
onclick: Triggered when the mouse is clicked.
ondblclick: Triggered when the mouse is double-clicked.
onmousedown: Triggered when the mouse button is pressed.
onmouseup: Triggered when the mouse button is released.
onmousemove: Triggered when the mouse is moved.
onwheel: Fired when the user scrolls using a wheel or similar device, providing delta values.
ontouchstart: Triggered when a touch starts on the canvas.
ontouchend: Triggered when a touch ends.
ontouchmove: Triggered when a touch moves across the canvas.
ontouchcancel: Triggered when a touch event is canceled.

Canvas Events

oncanvas: Provides the drawing canvas

payload: {
  canvas: OffscreenCanvas, // The offscreen canvas
  sessionId: string,      // Current session identifier (used for multiplayer)
  pixelRatio: number,    // Multiply the width and height to get exact screen pixels
}

onresize: Triggered when the canvas is resized

payload: {
  pixelRatio: number, // Multiply the width and height to get exact screen pixels
  width: number,     // Browser pixels
  height: number,   // Browser pixels
}

Every event that privides width/height/x/y/z values uses browser pixels. The browser will scale the pixel size so that things on a 4K monitor look the same as they do on a HD monitor. You can correct this by using the pixelRatio but be careful since you will also need to do the same for all input events.

Focus Events

onfocus: The canvas was focused
onblur: The canvas has lost focus (can be used to automatically pause the game when a user navigates to another tab)

payload: {}

Multiplayer Events

onlisten: Receives messages from other connected players

payload: any; // The broadcasted data

onjoin: Triggered when someone joins

payload: {
  sessions: string[]; // The sessions that have joined
}

onleave: Triggered when someone leaves

payload: {
  sessions: string[]; // The sessions that have left
}

onsync: Provides a list of the current sessions after onjoin or onleave are triggered

payload: {
  sessions: string[]; // The current sessions
}

onstatus: Triggers when the connected or disconnected status changes

payload: {
  status: 'SUBSCRIBED' | 'TIMED_OUT' | 'CLOSED' | 'CHANNEL_ERROR',
},

Keyboard Events

onkeydown: Triggered when a key is pressed
onkeyup: Triggered when a key is released

See relevant vanilla documentation Keyboard Event and
Key values for keyboard events

payload: {
  key: string; // The key value
  code: string; // Physical key code
  altKey: boolean; // Alt key state
  shiftKey: boolean; // Shift key state
  metaKey: boolean; // Meta/Command key state
  ctrlKey: boolean; // Control key state
}

Pointer Events

onpointerenter: Triggered when a pointer enters the canvas
onpointerleave: Triggered when a pointer leaves the canvas
onpointerdown: Triggered when a pointer is pressed
onpointerup: Triggered when a pointer is released
onpointermove: Triggered when a pointer moves

See relevant vanilla documentation Pointer events

payload: {
  pointerType: "mouse" | "pen" | "touch"
  offsetX: number,
  offsetY: number,
  button: number,

  altKey: boolean; // Alt key state
  shiftKey: boolean; // Shift key state
  metaKey: boolean; // Meta/Command key state
  ctrlKey: boolean; // Control key state
}

Mouse Events

onclick: Triggered when the mouse is clicked
ondblclick: Triggered when the mouse is double clicked
onmousedown: Triggered when the mouse is pressed
onmouseup: Triggered when the mouse is released
onmousemove: Triggered when the mouse is moved

See relevant vanilla documentation Mouse events

payload: {
  offsetX: number,
  offsetY: number,
  button: number,

  altKey: boolean; // Alt key state
  shiftKey: boolean; // Shift key state
  metaKey: boolean; // Meta/Command key state
  ctrlKey: boolean; // Control key state
}

Wheel Event

The wheel event on codetoy is a simplified version of the vanilla onwheel event that always returns the scroll delta in pixels.

onwheel: The wheel event fires when the user rotates a wheel button on a pointing device (typically a mouse). It is also fired for related devices that simulate wheel actions, such as trackpads and mouse balls.

See relevant vanilla documentation Wheel event

payload: {
  deltaX: number, // pixels
  deltaY: number, // pixels
  deltaZ: number, // pixels
}

Touch Events

ontouchstart: Triggered when the touch starts
ontouchend: Triggered when the touch ends
ontouchmove: Triggered when the touch moves
ontouchcancel: Triggered when the touch is canceled

See relevant vanilla documentation Touch event

Touch events on codetoy are a simplified verion of vanilla html touch events. The position of touch events is converted to be within the pixel coordinates of the canvas (instead of screenX and screenY you get offsetX and offsetY).

touch.ts

payload: {
  identifier: number; // Unique identifier for the touch
  offsetX: number; // X position of the touch
  offsetY: number; // Y position of the touch
  force: number; // Float between 0.0 (no pressure) and 1.0 (maximum pressure).
  radius: number; // Radius of the circle that most closely circumscribes the area of contact with the screen
}