Skip to Content
defold-typescript libraries
widgrensitasobi-defold

widgrensit/asobi-defold/asobi.realtime

The realtime connection a client creates as client.realtime: one websocket that authenticates the session, carries matchmaking, matches, worlds, chat, votes and extension calls, and keeps a registry of the entities the server syncs.

  • GitHub: widgrensit/asobi-defold — pinned to v1.18.1
    1. Pick a release from widgrensit/asobi-defold releases and add its Source code (zip) URL (or a packaged .zip asset, if the library ships one) to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as realtime from "asobi.realtime"

Functions

new(client: Client): Realtime

Creates the realtime connection for a client. create calls it, so a project reaches the connection as client.realtime.

Parameters

  • client: Client — The client.

Returns

  • Realtime

_is_auth_close(reason: unknown): boolean

Internal. Whether a close or error reason means the session's token was rejected: connect's socket callback and _handle_message call it to choose auth_expired.

Parameters

  • reason: unknown — The reason.

Returns

  • boolean

Types

type RealtimeError = Payload & { error?: string; reason?: string; }

type RequestCallback = (payload: Payload | undefined, err: string | undefined) => void

Realtime

Realtime.on<E extends keyof RealtimeEvents>(event: E, callback: RealtimeEvents[E])

Registers a handler for an event. A name RealtimeEvents does not list raises an error, and handlers for one event run in the order they were registered. The reply to a request made with a callback goes to that callback rather than to an event.

Parameters

  • event: E — The event.
  • callback: RealtimeEvents[E] — The handler.

Realtime.connect()

Opens the websocket and authenticates with the client's access token. Set request_binary_wire and request_datagram before calling it, and register handlers first. Does nothing while connected.

Realtime.update()

Drains the datagram plane, and is a no-op without one. Call it once per frame from update when request_datagram is set.

Realtime.disconnect()

Closes the datagram plane and the websocket.

Realtime.reauth()

Re-authenticates the open socket with the client's current access token, after a token refresh. Does nothing when not connected.

Realtime.join_match(match_id: string, callback?: RequestCallback)

Joins a match by id. A running match accepts joiners while it has room.

Parameters

  • match_id: string — The match's id.
  • callback?: RequestCallback — Receives the match.joined payload, or a reason such as match_not_found or match_full.

Realtime.join_match(match_id: string, opts: JoinOptions | undefined, callback?: RequestCallback)

Joins a match by id. A running match accepts joiners while it has room.

Parameters

  • match_id: string — The match's id.
  • opts: JoinOptions | undefined — The join context the game module receives.
  • callback?: RequestCallback — Receives the match.joined payload, or a reason such as match_not_found or match_full.

Realtime.find_or_create_match(mode: string, callback?: RequestCallback)

Joins a live match of mode, creating one when there is none. The server resolves it, so simultaneous callers converge on one match. Needs an asobi server 0.86.0 or later.

Parameters

  • mode: string — The match mode.
  • callback?: RequestCallback — Receives the match.joined payload, or a reason such as not_found or quick_play_disabled.

Realtime.find_or_create_match(mode: string, opts: JoinOptions | undefined, callback?: RequestCallback)

Joins a live match of mode, creating one when there is none. The server resolves it, so simultaneous callers converge on one match. Needs an asobi server 0.86.0 or later.

Parameters

  • mode: string — The match mode.
  • opts: JoinOptions | undefined — The join context the game module receives.
  • callback?: RequestCallback — Receives the match.joined payload, or a reason such as not_found or quick_play_disabled.

Realtime.send_match_input(input: Payload)

Sends input to the current match.

Parameters

  • input: Payload — The input.

Realtime.leave_match()

Leaves the current match.

Realtime.list_matches(opts?: string | ListOptions, callback?: RequestCallback)

Lists matches.

Parameters

  • opts?: string | ListOptions — A mode, or the mode and whether to list only matches with room.
  • callback?: RequestCallback — Receives the list, or the reason it failed.

Realtime.add_to_matchmaker(opts?: string | MatchmakerOptions)

Queues for a match with the matchmaker. Register matchmaker_queued, error and matchmaker_failed first, or a failure goes unnoticed.

Parameters

  • opts?: string | MatchmakerOptions — A mode, or the mode and its matchmaking properties. Defaults to "default".

Realtime.quick_play(opts?: string | MatchmakerOptions)

Queues for a match with the matchmaker, as add_to_matchmaker does.

Parameters

  • opts?: string | MatchmakerOptions — A mode, or the mode and its matchmaking properties. Defaults to "default".

Realtime.remove_from_matchmaker(ticket_id: string)

Takes a ticket out of the matchmaker.

Parameters

  • ticket_id: string — The ticket's id.

Realtime.join_chat(channel_id: string)

Joins a chat channel.

Parameters

  • channel_id: string — The channel's id.

Realtime.send_chat_message(channel_id: string, content: string)

Sends a message to a chat channel.

Parameters

  • channel_id: string — The channel's id.
  • content: string — The message.

Realtime.leave_chat(channel_id: string)

Leaves a chat channel.

Parameters

  • channel_id: string — The channel's id.

Realtime.cast_vote(vote_id: string, option_id: string)

Casts a vote.

Parameters

  • vote_id: string — The vote's id.
  • option_id: string — The chosen option's id.

Realtime.cast_veto(vote_id: string)

Vetoes a vote.

Parameters

  • vote_id: string — The vote's id.

Realtime.send_dm(recipient_id: string, content: string)

Sends a direct message.

Parameters

  • recipient_id: string — The recipient's player id.
  • content: string — The message.

Realtime.update_presence(status?: string)

Sets the player's presence.

Parameters

  • status?: string — The status. Defaults to "online".

Realtime.send_heartbeat()

Sends a heartbeat.

Realtime.ping(callback?: (rtt_ms: number | undefined, err: string | undefined) => void)

Measures the round trip of one heartbeat.

Parameters

  • callback?: (rtt_ms: number | undefined, err: string | undefined) => void — Receives the round trip in milliseconds, or the reason it failed.

Realtime.rpc(method: string, params?: Payload, callback?: (result: Payload | undefined, err: RpcError | string | undefined) => void)

Calls a server extension's RPC method. Calls may answer out of order.

Parameters

  • method: string — The method, such as "quests.claim".
  • params?: Payload — The method's parameters. Defaults to an empty table.
  • callback?: (result: Payload | undefined, err: RpcError | string | undefined) => void — Receives the method's result, or the error: an RpcError the method answered with, or the reason the request failed.

Realtime.list_worlds(opts?: string | ListOptions, callback?: RequestCallback)

Lists worlds.

Parameters

  • opts?: string | ListOptions — A mode, or the mode and whether to list only worlds with room.
  • callback?: RequestCallback — Receives the list, or the reason it failed.

Realtime.create_world(mode: string, callback?: RequestCallback)

Creates a world.

Parameters

  • mode: string — The world mode.
  • callback?: RequestCallback — Receives the reply, or the reason it failed.

Realtime.join_world(world_id: string, callback?: RequestCallback)

Joins a world by id.

Parameters

  • world_id: string — The world's id.
  • callback?: RequestCallback — Receives the reply, or the reason it failed.

Realtime.join_world(world_id: string, opts: JoinOptions | undefined, callback?: RequestCallback)

Joins a world by id.

Parameters

  • world_id: string — The world's id.
  • opts: JoinOptions | undefined — The join context the world's join callback receives, such as a lobby code.
  • callback?: RequestCallback — Receives the reply, or the reason it failed.

Realtime.find_or_create_world(mode: string, callback?: RequestCallback)

Joins an open world of mode, creating one when there is none. The server resolves it, so simultaneous callers converge on one world.

Parameters

  • mode: string — The world mode.
  • callback?: RequestCallback — Receives the reply, or the reason it failed.

Realtime.join_or_host(mode: string, callback?: RequestCallback)

Joins an open world of mode or hosts a new one, as find_or_create_world does.

Parameters

  • mode: string — The world mode.
  • callback?: RequestCallback — Receives the reply, or the reason it failed.

Realtime.send_world_input(input: Payload, seq?: number)

Sends input to the current world.

Parameters

  • input: Payload — The input.
  • seq?: number — An increasing input number for client-side prediction, which world_ack echoes back once the server consumes it.

Realtime.leave_world()

Leaves the current world.

Realtime._datagram_open()

Internal. Opens the datagram plane: _handle_message calls it on session.connected when request_datagram is set.

Realtime._datagram_stop()

Internal. Closes the datagram plane: disconnect and a failed open call it.

Realtime._apply_pose(pose: unknown)

Internal. Applies one datagram pose to entities: update calls it.

Parameters

  • pose: unknown

Realtime._datagram_endpoint(endpoint: unknown): LuaMultiReturn<[ host: string, port: number ] | [ host: undefined ]>

Internal. Splits the host:port endpoint a datagram mint answers with: _datagram_open calls it.

Parameters

  • endpoint: unknown

Returns

  • LuaMultiReturn<[ host: string, port: number ] | [ host: undefined ]>

Realtime._send_session_connect()

Internal. Sends session.connect with the access token: the open socket and reauth call it.

Realtime._send(msg_type: unknown, payload: unknown)

Internal. Sends a frame with a correlation id and no callback: leave_match, join_chat and the other methods that take no callback call it.

Parameters

  • msg_type: unknown
  • payload: unknown

Realtime._send_with_callback(msg_type: unknown, payload: unknown, callback?: unknown)

Internal. Sends a frame and records its callback for the reply: the methods taking a callback call it.

Parameters

  • msg_type: unknown
  • payload: unknown
  • callback?: unknown

Realtime._send_fire_and_forget(msg_type: unknown, payload: unknown, seq?: unknown)

Internal. Sends a frame with no correlation id: send_match_input, send_world_input, send_chat_message and send_heartbeat call it.

Parameters

  • msg_type: unknown
  • payload: unknown
  • seq?: unknown

Realtime._apply_entity_update(delta: unknown, zkey: unknown): unknown

Internal. Applies one entity delta to entities: _dispatch_tick calls it.

Parameters

  • delta: unknown
  • zkey: unknown

Returns

  • unknown

Realtime._dispatch_tick(payload: unknown)

Internal. Applies a world.tick or match.state frame and fires its events: _handle_message and _handle_binary call it.

Parameters

  • payload: unknown

Realtime._reconcile_keyframe(zkey: unknown, updates: unknown)

Internal. Removes the entities a keyframe left out: _dispatch_tick calls it.

Parameters

  • zkey: unknown
  • updates: unknown

Realtime._request_resync(zkey: unknown, zone: unknown)

Internal. Asks the server for a zone's keyframe after a gap: _dispatch_tick calls it.

Parameters

  • zkey: unknown
  • zone: unknown

Realtime._handle_binary(raw: unknown)

Internal. Decodes a binary world.tick frame: _handle_message calls it.

Parameters

  • raw: unknown

Realtime._handle_message(raw: unknown)

Internal. Routes one websocket message: the socket's callback calls it.

Parameters

  • raw: unknown

Realtime.client: Client

The client this connection belongs to.

Realtime.entities: LuaMap<string, Payload>

Every synced entity's whole state, keyed by entity id. Emptied when a world is joined or left.

Realtime.local_player_id: string | undefined

The signed-in player's entity id, set once connected fires.

Realtime.request_binary_wire: boolean

Set before connect to ask for the binary world.tick encoding.

Realtime.wire: 'json' | 'binary'

The encoding the server granted, read once connected fires.

Realtime.request_datagram: boolean

Set before connect to also open the datagram plane, which carries entity positions over UDP. It never opens on HTML5, and the websocket keeps carrying everything either way.

RealtimeEvents

RealtimeEvents.error: (payload: RealtimeError) => void

An error frame, or { error } with the websocket's message when the socket fails. A frame whose reason rejects the access token fires auth_expired as well.

RealtimeEvents.connected: (payload: Payload) => void

session.connected: the session is authenticated, and local_player_id and wire are set. Send game messages only after this fires.

RealtimeEvents.heartbeat: (payload: Payload) => void

session.heartbeat: the server's heartbeat.

RealtimeEvents.match_state: (payload: Payload) => void

match.state: a match state snapshot. A { tick, updates } frame has already updated entities and fired the entity events and tick.

RealtimeEvents.match_matched: (payload: Payload) => void

match.matched: the matchmaker placed the player in a match, carrying its match_id.

RealtimeEvents.match_joined: (payload: Payload) => void

match.joined: the player joined a match.

RealtimeEvents.match_left: (payload: Payload) => void

match.left: the player left the match.

RealtimeEvents.match_list: (payload: Payload) => void

match.list: a list of matches.

RealtimeEvents.match_finished: (payload: Payload) => void

match.finished: the match ended.

RealtimeEvents.matchmaker_expired: (payload: Payload) => void

match.matchmaker_expired: the matchmaker ticket expired.

RealtimeEvents.matchmaker_failed: (payload: Payload) => void

match.matchmaker_failed: the match could not start, carrying a reason.

RealtimeEvents.vote_start: (payload: Payload) => void

match.vote_start: a vote opened.

RealtimeEvents.vote_tally: (payload: Payload) => void

match.vote_tally: a vote's running tally.

RealtimeEvents.vote_result: (payload: Payload) => void

match.vote_result: a vote's result.

RealtimeEvents.vote_vetoed: (payload: Payload) => void

match.vote_vetoed: a vote was vetoed.

RealtimeEvents.matchmaker_queued: (payload: Payload) => void

matchmaker.queued: the matchmaker accepted the ticket, carrying ticket_id and players_needed.

RealtimeEvents.matchmaker_removed: (payload: Payload) => void

matchmaker.removed: the ticket left the matchmaker.

RealtimeEvents.chat_joined: (payload: Payload) => void

chat.joined: the player joined a chat channel.

RealtimeEvents.chat_left: (payload: Payload) => void

chat.left: the player left a chat channel.

RealtimeEvents.chat_message: (payload: Payload) => void

chat.message: a message in a joined channel.

RealtimeEvents.dm_sent: (payload: Payload) => void

dm.sent: a direct message was sent.

RealtimeEvents.dm_message: (payload: Payload) => void

dm.message: a direct message arrived.

RealtimeEvents.presence_changed: (payload: Payload) => void

presence.updated: a player's presence changed.

RealtimeEvents.notification: (payload: Payload) => void

notification.new: a new notification.

RealtimeEvents.game_message: (payload: Payload) => void

game.message or module.message: a message from the game module. The server sends both names for each message, and the event fires for whichever the connection saw first.

RealtimeEvents.game_error: (payload: Payload) => void

game.error or module.error: an error from the game module. The server sends both names for each error, and the event fires for whichever the connection saw first.

RealtimeEvents.module_event: (payload: Payload) => void

module.event: a named push from a server extension, carrying event and data.

RealtimeEvents.vote_cast_ok: (payload: Payload) => void

vote.cast_ok: the vote was recorded.

RealtimeEvents.vote_veto_ok: (payload: Payload) => void

vote.veto_ok: the veto was recorded.

RealtimeEvents.world_tick: (payload: Payload) => void

world.tick: a world frame. It has already updated entities and fired the entity events and tick.

RealtimeEvents.world_terrain: (payload: Payload) => void

world.terrain: the world's terrain.

RealtimeEvents.world_list: (payload: Payload) => void

world.list: a list of worlds.

RealtimeEvents.world_joined: (payload: Payload) => void

world.joined: the player joined a world. entities is emptied first.

RealtimeEvents.world_left: (payload: Payload) => void

world.left: the player left the world. entities is emptied first.

RealtimeEvents.phase_changed: (payload: Payload) => void

world.phase_changed: the world's phase changed.

RealtimeEvents.world_finished: (payload: Payload) => void

world.finished: the world ended.

RealtimeEvents.world_ack: (ack: WorldAck) => void

world.ack: the highest input seq the server consumed. It fires only for inputs sent with a seq.

RealtimeEvents.auth_expired: (reason: string) => void

The server rejected the access token: the socket closed, or an error frame arrived, for a revoked, invalid or idle-timed-out session. Sign in again rather than retrying.

RealtimeEvents.disconnected: (reason: string) => void

The socket closed for any other reason, "closed" when it gave none.

RealtimeEvents.entity_added: (id: string, state: Payload) => void

An entity entered entities, with its full initial state.

RealtimeEvents.entity_updated: (id: string, state: Payload, changed: string[]) => void

An entity changed. state is its whole merged state, never a partial one, and changed names the fields that changed.

RealtimeEvents.entity_removed: (id: string) => void

An entity left entities.

RealtimeEvents.tick: (tick: number | undefined, payload: Payload) => void

A world.tick or match.state frame was applied, after its entity events.

RealtimeEvents.match_event: (name: string, payload: Payload) => void

A match.<name> frame that a match script sent with game.broadcast(name, payload). Frames asobi itself sends keep their own events.

RealtimeEvents.world_event: (name: string, payload: Payload) => void

A world.<name> frame that a world script sent with game.broadcast(name, payload). Frames asobi itself sends keep their own events.

WorldAck

WorldAck.tick: number

The world tick the input was consumed by.

WorldAck.seq: number

The highest seq passed to send_world_input that the server has consumed.

JoinOptions

JoinOptions.ctx?: Payload

Passed untouched to the game module's join callback, such as a room code or a team pick.

ListOptions

ListOptions.mode?: string

Only sessions of this mode.

ListOptions.has_capacity?: boolean

Only sessions with room for another player.

MatchmakerOptions

MatchmakerOptions.mode?: string

The matchmaker mode. Defaults to "default".

MatchmakerOptions.properties?: Payload

Properties the matchmaker groups tickets by.

RpcError

RpcError.code: string

The error code, "internal" when the server sent none.

RpcError.message?: string

A message for people, which may be reworded at any time.

RpcError.details?: unknown

Further detail the method attached.

On this page

Functionsnew(client: Client): Realtime_is_auth_close(reason: unknown): booleanTypestype RealtimeError = Payload & { error?: string; reason?: string; }type RequestCallback = (payload: Payload | undefined, err: string | undefined) => voidRealtimeRealtime.on<E extends keyof RealtimeEvents>(event: E, callback: RealtimeEvents[E])Realtime.connect()Realtime.update()Realtime.disconnect()Realtime.reauth()Realtime.join_match(match_id: string, callback?: RequestCallback)Realtime.join_match(match_id: string, opts: JoinOptions | undefined, callback?: RequestCallback)Realtime.find_or_create_match(mode: string, callback?: RequestCallback)Realtime.find_or_create_match(mode: string, opts: JoinOptions | undefined, callback?: RequestCallback)Realtime.send_match_input(input: Payload)Realtime.leave_match()Realtime.list_matches(opts?: string | ListOptions, callback?: RequestCallback)Realtime.add_to_matchmaker(opts?: string | MatchmakerOptions)Realtime.quick_play(opts?: string | MatchmakerOptions)Realtime.remove_from_matchmaker(ticket_id: string)Realtime.join_chat(channel_id: string)Realtime.send_chat_message(channel_id: string, content: string)Realtime.leave_chat(channel_id: string)Realtime.cast_vote(vote_id: string, option_id: string)Realtime.cast_veto(vote_id: string)Realtime.send_dm(recipient_id: string, content: string)Realtime.update_presence(status?: string)Realtime.send_heartbeat()Realtime.ping(callback?: (rtt_ms: number | undefined, err: string | undefined) => void)Realtime.rpc(method: string, params?: Payload, callback?: (result: Payload | undefined, err: RpcError | string | undefined) => void)Realtime.list_worlds(opts?: string | ListOptions, callback?: RequestCallback)Realtime.create_world(mode: string, callback?: RequestCallback)Realtime.join_world(world_id: string, callback?: RequestCallback)Realtime.join_world(world_id: string, opts: JoinOptions | undefined, callback?: RequestCallback)Realtime.find_or_create_world(mode: string, callback?: RequestCallback)Realtime.join_or_host(mode: string, callback?: RequestCallback)Realtime.send_world_input(input: Payload, seq?: number)Realtime.leave_world()Realtime._datagram_open()Realtime._datagram_stop()Realtime._apply_pose(pose: unknown)Realtime._datagram_endpoint(endpoint: unknown): LuaMultiReturn<[ host: string, port: number ] | [ host: undefined ]>Realtime._send_session_connect()Realtime._send(msg_type: unknown, payload: unknown)Realtime._send_with_callback(msg_type: unknown, payload: unknown, callback?: unknown)Realtime._send_fire_and_forget(msg_type: unknown, payload: unknown, seq?: unknown)Realtime._apply_entity_update(delta: unknown, zkey: unknown): unknownRealtime._dispatch_tick(payload: unknown)Realtime._reconcile_keyframe(zkey: unknown, updates: unknown)Realtime._request_resync(zkey: unknown, zone: unknown)Realtime._handle_binary(raw: unknown)Realtime._handle_message(raw: unknown)Realtime.client: ClientRealtime.entities: LuaMap<string, Payload>Realtime.local_player_id: string | undefinedRealtime.request_binary_wire: booleanRealtime.wire: 'json' | 'binary'Realtime.request_datagram: booleanRealtimeEventsRealtimeEvents.error: (payload: RealtimeError) => voidRealtimeEvents.connected: (payload: Payload) => voidRealtimeEvents.heartbeat: (payload: Payload) => voidRealtimeEvents.match_state: (payload: Payload) => voidRealtimeEvents.match_matched: (payload: Payload) => voidRealtimeEvents.match_joined: (payload: Payload) => voidRealtimeEvents.match_left: (payload: Payload) => voidRealtimeEvents.match_list: (payload: Payload) => voidRealtimeEvents.match_finished: (payload: Payload) => voidRealtimeEvents.matchmaker_expired: (payload: Payload) => voidRealtimeEvents.matchmaker_failed: (payload: Payload) => voidRealtimeEvents.vote_start: (payload: Payload) => voidRealtimeEvents.vote_tally: (payload: Payload) => voidRealtimeEvents.vote_result: (payload: Payload) => voidRealtimeEvents.vote_vetoed: (payload: Payload) => voidRealtimeEvents.matchmaker_queued: (payload: Payload) => voidRealtimeEvents.matchmaker_removed: (payload: Payload) => voidRealtimeEvents.chat_joined: (payload: Payload) => voidRealtimeEvents.chat_left: (payload: Payload) => voidRealtimeEvents.chat_message: (payload: Payload) => voidRealtimeEvents.dm_sent: (payload: Payload) => voidRealtimeEvents.dm_message: (payload: Payload) => voidRealtimeEvents.presence_changed: (payload: Payload) => voidRealtimeEvents.notification: (payload: Payload) => voidRealtimeEvents.game_message: (payload: Payload) => voidRealtimeEvents.game_error: (payload: Payload) => voidRealtimeEvents.module_event: (payload: Payload) => voidRealtimeEvents.vote_cast_ok: (payload: Payload) => voidRealtimeEvents.vote_veto_ok: (payload: Payload) => voidRealtimeEvents.world_tick: (payload: Payload) => voidRealtimeEvents.world_terrain: (payload: Payload) => voidRealtimeEvents.world_list: (payload: Payload) => voidRealtimeEvents.world_joined: (payload: Payload) => voidRealtimeEvents.world_left: (payload: Payload) => voidRealtimeEvents.phase_changed: (payload: Payload) => voidRealtimeEvents.world_finished: (payload: Payload) => voidRealtimeEvents.world_ack: (ack: WorldAck) => voidRealtimeEvents.auth_expired: (reason: string) => voidRealtimeEvents.disconnected: (reason: string) => voidRealtimeEvents.entity_added: (id: string, state: Payload) => voidRealtimeEvents.entity_updated: (id: string, state: Payload, changed: string[]) => voidRealtimeEvents.entity_removed: (id: string) => voidRealtimeEvents.tick: (tick: number | undefined, payload: Payload) => voidRealtimeEvents.match_event: (name: string, payload: Payload) => voidRealtimeEvents.world_event: (name: string, payload: Payload) => voidWorldAckWorldAck.tick: numberWorldAck.seq: numberJoinOptionsJoinOptions.ctx?: PayloadListOptionsListOptions.mode?: stringListOptions.has_capacity?: booleanMatchmakerOptionsMatchmakerOptions.mode?: stringMatchmakerOptions.properties?: PayloadRpcErrorRpcError.code: stringRpcError.message?: stringRpcError.details?: unknown