Skip to main content
Dusk Logo
DocsFAQ

API Reference

Dusk methods for writing multiplayer games. The SDK is split into two parts:

  • Game logic, this code needs to be located in a file called logic.js
  • UI integration, that can live anywhere, but the docs will refer to client.js

Game logic​

Dusk.initLogic(options)​

The initLogic function should be called directly at the top level of your logic.js file. This should contain all logic required to control your game state and handle player life cycle events. All options except events are required. Example:

// logic.js
Dusk.initLogic({
  minPlayers: 1,
  maxPlayers: 4,
  setup: (allPlayerIds) => {
    const scores = {}
    for (let playerId of allPlayerIds) {
      scores[playerId] = 0
    }
    return { scores, currentPlayerIndex: 0, currentPlayerStartedAt: 0 }
  },
  actions: {
    myAction: (payload, { game, playerId, allPlayerIds }) => {
      // Check it's not the other player's turn
      if (game.currentPlayer !== allPlayerIds[game.currentPlayerIndex]) {
        throw Dusk.invalidAction()
      }

      // Increase score and switch turn
      game.scores[playerId]++
      //Switch turn
      game.currentPlayerIndex = (game.currentPlayerIndex + 1) % allPlayerIds.length;
      game.currentPlayerStartedAt = Dusk.gameTimeInSeconds();
      // Determine if game has ended
      if (isVictoryOrDraw(game)) {
        Dusk.gameOver()
      }
    },
  },
  events: {
    playerJoined: (playerId, { game }) => {
      game.scores[playerId] = 0
    },
    playerLeft: (playerId, { game }) => {
      delete game.scores[playerId]
    },
  },
  update: ({ game, allPlayerIds }) => {
    //If 30 seconds have passed since last player scored, switch player
    if (Dusk.gameTimeInSeconds() - game.lastPlayerScoredAt > 30) {
      game.currentPlayerIndex = (game.currentPlayerIndex + 1) % allPlayerIds.length;
      game.currentPlayerStartedAt = Dusk.gameTimeInSeconds();
    }
  },
  updatesPerSecond: 10,
  inputDelay: 30,
})

minPlayers: number​

A value between 1-4 of the minmum amount of players that is required to play the game. See Joining and Leaving.

maxPlayers: number​

A value between 1-4, must be equal to or greater than minPlayers. If the value is lower than 4, other users may join the game as spectators. See Joining and Leaving.

setup(allPlayerIds: string[]): any​

The setup function returns the initial values for the game state, which is the game information that’s synced across players. The function gets the allPlayerIds argument which is an array of the player IDs at the time of starting the game and must return the initial game state.

actions: { [string]: (payload, { game: object, playerId: string, allPlayerIds: string[] }) => void}​

The actions option is an object with actions functions exposed to the UI integration layer, called with Dusk.actions.myAction(payload). The functions are responsible for validating the action, mutating the game state and end the game when appropriate.

events: { playerJoined? | playerLeft?: (playerId: string, { game: any, allPlayerIds: string[] }) => void } optional {#events--playerjoined--playerleft-playerid-string--game-any-allplayerids-string---void--optional}​

By default a game will end if a player leaves (see Joining and Leaving), but by defining the playerJoined/playerLeft events you can Support Players Joining Midgame.

update({game: object, allPlayerIds: string[]}) => void optional {#updategame-object--allplayerids-string--void-optional}​

Function that is executed every second. See Using Time in your Game.

updatesPerSecond?: number​

How many times update function should be executed per second. Allowed values 1-30. Default 1. See Real time games.

inputDelay?: number​

How many milliseconds user action is delayed before run locally. Allowed values 0-250. Default value 25. Higher values will mean that players are more in sync with each other (i.e. fewer rollbacks), but will feel less snappy locally as it takes longer for a player's actions to be reflected on their screen.

Dusk.invalidAction()​

Whenever a player tries to do an action that is not allowed, the action handler should reject it by calling throw Dusk.invalidAction() which will cancel the action and roll back any local optimistic updates.

This is completely safe to do and can be used throughout your game.

// logic.js
Dusk.initLogic({
  actions: {
    myAction: (payload, { game, playerId }) => {
      if (!isValidAction(payload)) {
        throw Dusk.invalidAction()
      }
    },
  },
})

Dusk.gameOver(options)​

When the game has ended, the action handler should call Dusk.gameOver. Your game doesn't need to show a "game over" screen. Dusk overlays a standardized game over popup to the user. See more in the Game Over guide.

// logic.js
Dusk.initLogic({
  actions: {
    myAction: (payload, { game }) => {
      if (isGameOver(game)) {
        const winner = getWinner(game)
        const loser = getLoser(game)

        Dusk.gameOver({
          players: {
            [winner.playerId]: "WON",
            [loser.playerId]: "LOST",
          },
          delayPopUp: true,
        })
      }
    },
  },
})

players: Record<string, "WON" | "LOST" | number>​

players is an object with player IDs as keys and the game result as values. The game result for each player can be either WON/LOST or an integer score (higher is better) score. Mixing WON/LOST and scores at the same time is not allowed. All players present in the game at the moment the game ends must be mentioned in the players object.

delayPopUp?: boolean​

Optional. Set to true if you want to instruct Dusk to delay showing of the game over popup until you call Dusk.showGameOverPopUp().

Dusk.gameTime()​

Returns the amount of milliseconds that have passed since the start of the game. See Using Time in your Game.

Client​

Dusk.initClient(options)​

The initClient function should be called after your game is fully ready, but should not start the actual gameplay until onChange is called.

// client.js
Dusk.initClient({
  onChange: ({
    game,
    previousGame,
    futureGame,
    yourPlayerId,
    players,
    action,
    event,
    rollbacks,
  }) => {
    render(game)
  },
})

onChange: () => void​

game: object​

This argument is the current game state. Your onChange() function should update the UI to reflect its values.

previousGame: object​

This argument is the previous game state. Usually this can be ignored, but it's useful if your game needs to detect changes of certain values.

futureGame?: object​

This argument is the predicted future game state. This value is only available if game uses update function. Used in cases game wants to do interpolations. See Reducing stutter.

yourPlayerId?: string​

Your player id, if the current user is a spectator this argument is undefined.

players: Record<string, { playerId: string, displayName: string, avatarUrl: string }>​

The players argument is an object of the current players, useful to display their names and avatars in the game.

caution

Do not rely on players argument for determining player order, instead use setup and events.playerJoined/playerLeft callbacks in logic.js.

action?: { name: string, playerId: string, params: any }​

If the update was triggered from a Dusk.actions.* call, this argument will contain info about it, such as the payload and who initiated. Usually this should be ignored and rely on game instead.

event?: { name: string, params: any }​

Possible events: playerJoined, playerLeft, stateSync, update, timeSync.

Dusk.actions.*(payload)​

All functions passed in the actions object in Dusk.initLogic() will be exposed to the client via Dusk.actions.myActionName. This is the only way game state may be updated to make sure it's propagated to every player. You may call it with one argument of any type, but usually an object is recommended.

// client.js
button.onClick = () => {
  Dusk.actions.markCell({
    myId: "button",
  })
}

Dusk.showGameOverPopUp()​

If you set delayPopUp to true in Dusk.gameOver(), you should call this function in your client.js to show the game over popup.

Dusk.showInvitePlayers()​

Opens invite modal inside the Dusk app. Useful if you want to incentivize players to invite their friends.

Dusk.gameTime()​

Returns the amount of milliseconds that have passed since the start of the game. See Using Time in your Game.

Dusk.timeSinceLastUpdate()​

Returns the amount of milliseconds that have passed since the last update call. Can be used to smoothly render timers or interpolate between two positions.

Dusk.msPerUpdate​

Number of milliseconds indicating how often update function is called. Only available if game uses updates.

Dusk.interpolator()​

Returns an instance of interpolator. See Reducing Stutter

Dusk.interpolatorLatency()​

Returns an instance of interpolator. See Reducing stutter.

© 2024 Dusk
© 2024 Dusk