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- Pick a release from widgrensit/asobi-defold releases and add its Source code (zip) URL (or a packaged
.zipasset, if the library ships one) togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as realtime from "asobi.realtime"
- Pick a release from widgrensit/asobi-defold releases and add its Source code (zip) URL (or a packaged
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 thematch.joinedpayload, or a reason such asmatch_not_foundormatch_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 thematch.joinedpayload, or a reason such asmatch_not_foundormatch_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 thematch.joinedpayload, or a reason such asnot_foundorquick_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 thematch.joinedpayload, or a reason such asnot_foundorquick_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: anRpcErrorthe 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, whichworld_ackechoes 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:unknownpayload: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:unknownpayload:unknowncallback?: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:unknownpayload:unknownseq?:unknown
Realtime._apply_entity_update(delta: unknown, zkey: unknown): unknown
Internal. Applies one entity delta to entities: _dispatch_tick calls it.
Parameters
delta:unknownzkey: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:unknownupdates: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:unknownzone: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.