Skip to Content
defold-typescript libraries
megalanthusdefold-gamepush

megalanthus/defold-gamepush/gamepush.core.multiplayer

GamePush multiplayer rooms: connect, sync player and global state, send messages and follow the host, with their events.

  • GitHub: megalanthus/defold-gamepush — pinned to v1.4.1
    1. Pick a release from megalanthus/defold-gamepush 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 core_multiplayer from "gamepush.core.multiplayer"

Functions

connect(parameters: RoomParameters, callback?: (result: unknown) => void)

Connects to a room. The player must be a member of its channel. Raises when the table is missing.

Parameters

  • parameters: RoomParameters — The room's channel.
  • callback?: (result: unknown) => void — Receives the result.

disconnect(parameters?: RoomParameters, callback?: (result: unknown) => void)

Disconnects from a room.

Parameters

  • parameters?: RoomParameters — The room's channel, or nil for the current room.
  • callback?: (result: unknown) => void — Receives the result.

define_player_schema(schema: Record<string, unknown>)

Declares the player fields to sync. Raises when the table is missing.

Parameters

  • schema: Record<string, unknown> — The fields and their settings.

define_global_schema(schema: Record<string, unknown>)

Declares the shared fields to sync. Raises when the table is missing.

Parameters

  • schema: Record<string, unknown> — The fields and their settings.

set_player_initializer(initializer: (player_id: number, player_info: Record<string, unknown>) => Record<string, unknown>)

Sets how the host creates a joining player's state. Raises unless initializer is a function.

Parameters

  • initializer: (player_id: number, player_info: Record<string, unknown>) => Record<string, unknown> — Receives the player's id and info and returns its initial state.

set_player_state(state: Record<string, unknown>)

Updates the player's state. Raises when the table is missing.

Parameters

  • state: Record<string, unknown> — The fields to change.

set_global_state(state: Record<string, unknown>)

Sets the global state; the host only. Raises when the table is missing.

Parameters

  • state: Record<string, unknown> — The world state.

set_mode(mode: "fast" | "smooth")

Picks the sync mode. Raises unless mode is a string.

Parameters

  • mode: "fast" | "smooth" — MODE_FAST or MODE_SMOOTH.

on_tick()

Subscribes to the SDK tick, delivered to callbacks.tick.

off_tick()

Unsubscribes from the SDK tick.

send_message(event_name: string, data: unknown, target_or_options?: string | number | SendMessageOptions)

Sends a one-off event to other players. Raises unless event_name is a string.

Parameters

  • event_name: string — The message type.
  • data: unknown — JSON-compatible data.
  • target_or_options?: string | number | SendMessageOptions — "all", a player id, or the target and echo options; nil sends to everyone.

on_message()

Subscribes to messages from other players, delivered to callbacks.message.

off_message()

Unsubscribes from messages from other players.

is_connected(): boolean

Whether the player is connected to a room.

Returns

  • boolean

is_host(): boolean

Whether the player is the room's host.

Returns

  • boolean

connected_players(): Record<string, unknown>[]

The players connected to the room.

Returns

  • Record<string, unknown>[]

network_stats(): NetworkStats

The current network figures.

Returns

  • NetworkStats

my_state(): Record<string, unknown> | undefined

The player's state, or nil before it is set.

Returns

  • Record<string, unknown> | undefined

players_state(): Record<string, unknown>

Every player's state, keyed by player id.

Returns

  • Record<string, unknown>

global_state(): Record<string, unknown> | undefined

The last global state, or nil before one is set.

Returns

  • Record<string, unknown> | undefined

Variables

MODE_FAST: "fast"

The fast sync mode, for set_mode.

MODE_SMOOTH: "smooth"

The smooth sync mode, for set_mode.

callbacks: MultiplayerCallbacks

The multiplayer event handlers.

Types

RoomParameters

RoomParameters.channelId: number

The id of the channel that hosts the room.

SendMessageOptions

SendMessageOptions.target?: string | number

Who receives the message: "all" or a player id.

SendMessageOptions.echo?: boolean

Deliver the message to the sender as well.

NetworkStats

NetworkStats.ping: number

The connection's ping.

NetworkStats.bufferSize: number

The size of the state buffer.

NetworkStats.bufferDelay: number

The delay of the state buffer.

MultiplayerCallbacks

MultiplayerCallbacks.connect?: (result: unknown) => void

The player connected to a room.

MultiplayerCallbacks.disconnect?: (result: unknown) => void

The player disconnected from a room.

MultiplayerCallbacks.player_joined?: (result: unknown) => void

A player joined the room.

MultiplayerCallbacks.player_left?: (result: unknown) => void

A player left the room.

MultiplayerCallbacks.became_host?: () => void

The player became the room's host.

MultiplayerCallbacks.became_peer?: () => void

The player stopped being the room's host.

MultiplayerCallbacks.host_migrated?: (result: unknown) => void

Another player became the room's host.

MultiplayerCallbacks.players_updated?: (result: unknown) => void

The players' states changed.

MultiplayerCallbacks.global_state_updated?: (result: unknown) => void

The global state changed.

MultiplayerCallbacks.error_connect?: (error: unknown) => void

Connecting to a room failed.

MultiplayerCallbacks.error_send_state?: (error: unknown) => void

Sending the player's state failed.

MultiplayerCallbacks.error_disconnect?: (error: unknown) => void

Disconnecting from a room failed.

MultiplayerCallbacks.tick?: (delta: number) => void

An SDK tick, while subscribed with on_tick.

MultiplayerCallbacks.message?: (payload: unknown) => void

A message from another player, while subscribed with on_message.

MultiplayerCallbacks.player_initializer?: (data: unknown) => void

Set by set_player_initializer; call that instead of assigning this slot.

On this page

Functionsconnect(parameters: RoomParameters, callback?: (result: unknown) => void)disconnect(parameters?: RoomParameters, callback?: (result: unknown) => void)define_player_schema(schema: Record<string, unknown>)define_global_schema(schema: Record<string, unknown>)set_player_initializer(initializer: (player_id: number, player_info: Record<string, unknown>) => Record<string, unknown>)set_player_state(state: Record<string, unknown>)set_global_state(state: Record<string, unknown>)set_mode(mode: "fast" | "smooth")on_tick()off_tick()send_message(event_name: string, data: unknown, target_or_options?: string | number | SendMessageOptions)on_message()off_message()is_connected(): booleanis_host(): booleanconnected_players(): Record<string, unknown>[]network_stats(): NetworkStatsmy_state(): Record<string, unknown> | undefinedplayers_state(): Record<string, unknown>global_state(): Record<string, unknown> | undefinedVariablesMODE_FAST: "fast"MODE_SMOOTH: "smooth"callbacks: MultiplayerCallbacksTypesRoomParametersRoomParameters.channelId: numberSendMessageOptionsSendMessageOptions.target?: string | numberSendMessageOptions.echo?: booleanNetworkStatsNetworkStats.ping: numberNetworkStats.bufferSize: numberNetworkStats.bufferDelay: numberMultiplayerCallbacksMultiplayerCallbacks.connect?: (result: unknown) => voidMultiplayerCallbacks.disconnect?: (result: unknown) => voidMultiplayerCallbacks.player_joined?: (result: unknown) => voidMultiplayerCallbacks.player_left?: (result: unknown) => voidMultiplayerCallbacks.became_host?: () => voidMultiplayerCallbacks.became_peer?: () => voidMultiplayerCallbacks.host_migrated?: (result: unknown) => voidMultiplayerCallbacks.players_updated?: (result: unknown) => voidMultiplayerCallbacks.global_state_updated?: (result: unknown) => voidMultiplayerCallbacks.error_connect?: (error: unknown) => voidMultiplayerCallbacks.error_send_state?: (error: unknown) => voidMultiplayerCallbacks.error_disconnect?: (error: unknown) => voidMultiplayerCallbacks.tick?: (delta: number) => voidMultiplayerCallbacks.message?: (payload: unknown) => voidMultiplayerCallbacks.player_initializer?: (data: unknown) => void