Class ValidRoom

constructor

• new ValidRoom(server: SongGuessServer): ValidRoom

  Parameters

  • server: SongGuessServer

  Returns ValidRoom

Readonlyconfig

countdown

countdownInterval

game

Optionalhost

OptionalhostID

Readonlylistener

Readonlylobby

players

Readonlyserver

state

activePlayers

• get activePlayers(): Player[]

  List containing online, non-spectating players.

  Returns Player[]

onlinePlayers

• get onlinePlayers(): Player[]

  List containing ALL online players.

  Returns Player[]

broadcastRoomStateMessage

• broadcastRoomStateMessage(): void

  Broadcast a room state update to all connected clients.

  Returns void

  See

  sendRoomStateMessage

getActivePlayerByName

• getActivePlayerByName(name: string): Player | null

  Attempts to find a player by name.

  Parameters

  • name: string

    The username to search for.

  Returns Player | null

  the Player associated with the name or null if not found.

getCountdownMessage

• getCountdownMessage(): { countdown: number; type: "countdown" }

  Constructs a JSON string representing a countdown message. The countdown message is sent to connected clients when the countdown is updated.

  Returns { countdown: number; type: "countdown" }

  The countdown message

  • countdown: number

    The current countdown number. 0 to hide.

  • type: "countdown"

getOnlinePlayerMessages

• getOnlinePlayerMessages(): Record<string, PlayerMessage>

  Retrieves all valid player states from connected clients.

  Returns Record<string, PlayerMessage>

  An array of valid PlayerMessage objects from all connected players.

getOrCreatePlayer

• getOrCreatePlayer(conn: Connection<string>): Player

  Gets a player from the players map. If not found, create new player.

  Parameters

  • conn: Connection<string>

    the connection to search for

  Returns Player

getUnusedColors

• getUnusedColors(): string[]

  Get all colors, which aren't used by any player.

  Returns string[]

  A string array of unused colors or an empty array if all colors are used.

onClose

• onClose(conn: Connection<string>): Promise<void>

  Parameters

  • conn: Connection<string>

  Returns Promise<void>

onConnect

• onConnect(conn: Connection<string>, ctx: ConnectionContext): Promise<void>

  Parameters

  • conn: Connection<string>
  • ctx: ConnectionContext

  Returns Promise<void>

onDelayedHostTransfer

• onDelayedHostTransfer(): Promise<void>

  Callback to transfer host to another client after ROOM_HOST_TRANSFER_TIMEOUT seconds if the client does not join again.

  Returns Promise<void>

  true if host was transfered, false if not.

  See

  SongGuessServer#processEvent

onMessage

• onMessage(conn: Connection<string>, message: string): void

  Parameters

  • conn: Connection<string>
  • message: string

  Returns void

onTick

• onTick(): void

  Called every second by the server

  Returns void

performChecks

• performChecks(
      player: Player | null,
      msg:
          | { action: "load"; audioURL: string; type: "audio_control" }
          | {
              action:
                  | "play"
                  | "pause"
                  | "play_countdown_running"
                  | "play_countdown_end";
              type: "audio_control";
          }
          | { type: "change_username"; username: string }
          | {
              playlists: {
                  cover: string | null;
                  hrefURL: string;
                  name: string;
                  songs: {
                      artist: string;
                      audioURL: string;
                      cover: string | null;
                      hrefURL: string;
                      name: string;
                  }[];
                  subtitle?: string;
              }[];
              type: "add_playlists";
          }
          | { index: number
          | null; type: "remove_playlist" }
          | {
              advancedSongFiltering: boolean;
              audioStartPosition: number;
              distractionsPreferSameArtist: boolean;
              endWhenAnswered: boolean;
              gameMode: "multiple_choice" | "player_picks";
              playerPickTimeout: number;
              roundsCount: number;
              timePerQuestion: number;
              type: "room_config";
          }
          | { type: "start_game" }
          | { answer?: string; answerIndex?: number; type: "select_answer" }
          | { type: "return_to"; where: "lobby" | "results" }
          | { playerName: string; type: "transfer_host" }
          | {
              song: {
                  artist: string;
                  audioURL: string;
                  cover: string | null;
                  hrefURL: string;
                  name: string;
              };
              startPos: number;
              type: "player_pick_song";
          }
          | {
              players: Record<
                  string,
                  {
                      answerData?: {
                          answer?: string;
                          answerIndex?: number;
                          answerSpeed: number;
                          answerTimestamp: number;
                          questionPoints: number;
                      };
                      color: string;
                      isHost: boolean;
                      isSpectator: boolean;
                      points: number;
                      username: string;
                  },
              >;
              state: "lobby"
              | "results"
              | "ingame";
              type: "room_state";
              uuid: string;
              version: string;
          }
          | {
              filteredSongsCount: number;
              playlists?: {
                  cover: string
                  | null;
                  hrefURL: string;
                  name: string;
                  songs: {
                      artist: string;
                      audioURL: string;
                      cover: string | null;
                      hrefURL: string;
                      name: string;
                  }[];
                  subtitle?: string;
              }[];
              type: "update_playlists";
          }
          | { countdown: number; type: "countdown" }
          | {
              gamePhase: GamePhase;
              question?:
                  | {
                      answerOptions: string[];
                      correctAnswerIndex?: number;
                      questionType: "multiple_choice";
                      startPos: number;
                  }
                  | {
                      correctAnswer?: {
                          artist: string;
                          audioURL: string;
                          cover: string
                          | null;
                          hrefURL: string;
                          name: string;
                      };
                      pickerId: string;
                      questionCount: number;
                      questionCurrent: number;
                      questionType: "player_picks";
                      startPos: number;
                  };
              roundCurrent: number;
              type: "round_state";
          }
          | {
              songs: {
                  artist: string;
                  audioURL: string;
                  cover: string
                  | null;
                  hrefURL: string;
                  name: string;
              }[];
              type: "update_played_songs";
          }
          | {
              entry: LogEntry;
              level: "error"
              | "info"
              | "warn"
              | "debug";
              type: "add_log_message";
          }
          | { messages: LoggerStorage; type: "update_log_messages" }
          | { duration: number; offset: number; type: "progressbar_update" }
          | { type: "other" },
      ...checks: (
          | "lobby"
          | "host"
          | "not_lobby"
          | "not_contdown"
          | "not_ingame"
          | "min_song_count"
      )[],
  ): boolean

  Performs one or more of the specified checks.

  Parameters

  • player: Player | null

    The player to perform the checks for.

  • msg:
        | { action: "load"; audioURL: string; type: "audio_control" }
        | {
            action:
                | "play"
                | "pause"
                | "play_countdown_running"
                | "play_countdown_end";
            type: "audio_control";
        }
        | { type: "change_username"; username: string }
        | {
            playlists: {
                cover: string | null;
                hrefURL: string;
                name: string;
                songs: {
                    artist: string;
                    audioURL: string;
                    cover: string | null;
                    hrefURL: string;
                    name: string;
                }[];
                subtitle?: string;
            }[];
            type: "add_playlists";
        }
        | { index: number
        | null; type: "remove_playlist" }
        | {
            advancedSongFiltering: boolean;
            audioStartPosition: number;
            distractionsPreferSameArtist: boolean;
            endWhenAnswered: boolean;
            gameMode: "multiple_choice" | "player_picks";
            playerPickTimeout: number;
            roundsCount: number;
            timePerQuestion: number;
            type: "room_config";
        }
        | { type: "start_game" }
        | { answer?: string; answerIndex?: number; type: "select_answer" }
        | { type: "return_to"; where: "lobby" | "results" }
        | { playerName: string; type: "transfer_host" }
        | {
            song: {
                artist: string;
                audioURL: string;
                cover: string | null;
                hrefURL: string;
                name: string;
            };
            startPos: number;
            type: "player_pick_song";
        }
        | {
            players: Record<
                string,
                {
                    answerData?: {
                        answer?: string;
                        answerIndex?: number;
                        answerSpeed: number;
                        answerTimestamp: number;
                        questionPoints: number;
                    };
                    color: string;
                    isHost: boolean;
                    isSpectator: boolean;
                    points: number;
                    username: string;
                },
            >;
            state: "lobby"
            | "results"
            | "ingame";
            type: "room_state";
            uuid: string;
            version: string;
        }
        | {
            filteredSongsCount: number;
            playlists?: {
                cover: string
                | null;
                hrefURL: string;
                name: string;
                songs: {
                    artist: string;
                    audioURL: string;
                    cover: string | null;
                    hrefURL: string;
                    name: string;
                }[];
                subtitle?: string;
            }[];
            type: "update_playlists";
        }
        | { countdown: number; type: "countdown" }
        | {
            gamePhase: GamePhase;
            question?:
                | {
                    answerOptions: string[];
                    correctAnswerIndex?: number;
                    questionType: "multiple_choice";
                    startPos: number;
                }
                | {
                    correctAnswer?: {
                        artist: string;
                        audioURL: string;
                        cover: string
                        | null;
                        hrefURL: string;
                        name: string;
                    };
                    pickerId: string;
                    questionCount: number;
                    questionCurrent: number;
                    questionType: "player_picks";
                    startPos: number;
                };
            roundCurrent: number;
            type: "round_state";
        }
        | {
            songs: {
                artist: string;
                audioURL: string;
                cover: string
                | null;
                hrefURL: string;
                name: string;
            }[];
            type: "update_played_songs";
        }
        | {
            entry: LogEntry;
            level: "error"
            | "info"
            | "warn"
            | "debug";
            type: "add_log_message";
        }
        | { messages: LoggerStorage; type: "update_log_messages" }
        | { duration: number; offset: number; type: "progressbar_update" }
        | { type: "other" }

    The message that caused the check.

    • { action: "load"; audioURL: string; type: "audio_control" }

      • action: "load"

        • "load": Downloads the music.

      • audioURL: string

        URL to load music from.

        See

        SongSchema.shape.audioURL

      • type: "audio_control"

    • {
          action:
              | "play"
              | "pause"
              | "play_countdown_running"
              | "play_countdown_end";
          type: "audio_control";
      }

      • action: "play" | "pause" | "play_countdown_running" | "play_countdown_end"

        • "play": Starts playback of the music.
        • "pause": Pauses playback of the music.
        • "play_countdown_running": Plays the countdown_running sound effect on a secondary audio player.
        • "play_countdown_end": Plays the countdown_end sound effect on a secondary audio player.

      • type: "audio_control"

    • { type: "change_username"; username: string }

      • type: "change_username"

      • username: string

        The new username.

    • {
          playlists: {
              cover: string | null;
              hrefURL: string;
              name: string;
              songs: {
                  artist: string;
                  audioURL: string;
                  cover: string | null;
                  hrefURL: string;
                  name: string;
              }[];
              subtitle?: string;
          }[];
          type: "add_playlists";
      }

      • playlists: {
            cover: string | null;
            hrefURL: string;
            name: string;
            songs: {
                artist: string;
                audioURL: string;
                cover: string | null;
                hrefURL: string;
                name: string;
            }[];
            subtitle?: string;
        }[]

        The new playlist to add.

      • type: "add_playlists"

    • { index: number | null; type: "remove_playlist" }

      • index: number | null

        The playlist index to remove.

      • type: "remove_playlist"

    • {
          advancedSongFiltering: boolean;
          audioStartPosition: number;
          distractionsPreferSameArtist: boolean;
          endWhenAnswered: boolean;
          gameMode: "multiple_choice" | "player_picks";
          playerPickTimeout: number;
          roundsCount: number;
          timePerQuestion: number;
          type: "room_config";
      }

      • advancedSongFiltering: boolean

        Whether to perform advanced filtering tactics when generating the songs array. Currently just ignores parens when filtering for identical song names.

      • audioStartPosition: number

        The music start position.

        • 0: start of audio
        • 1: close to middle of audio
        • 2: close to end of audio
        • 3: random of the above

        Used as default value in PlayerPicksGame, used as forced position in MultipleChoiceGame.

      • distractionsPreferSameArtist: boolean

        Whether to prefer distractions by the same artist.

      • endWhenAnswered: boolean

        Whether to directly end the round after all players answered.

      • gameMode: "multiple_choice" | "player_picks"

        The game mode being played.

        • multiple_choice: the server selects random songs from the provided playlist and provides a multiple choice question with distractions.
        • player_picks: a player from the room picks a song for other players to guess each round. other players have to guess the song title by typing.

      • playerPickTimeout: number

        The amount of time a player should have to pick a song.

      • roundsCount: number

        The amount of rounds to play.

      • timePerQuestion: number

        The time per question in each round.

      • type: "room_config"

    • { type: "start_game" }
    • { answer?: string; answerIndex?: number; type: "select_answer" }

      • Optionalanswer?: string

        Provided only for PlayerPicksGame. The string of the song name the player guessed.

      • OptionalanswerIndex?: number

        Provided only for MultipleChoiceGame. The index of the selected answer.

      • type: "select_answer"

    • { type: "return_to"; where: "lobby" | "results" }

      • type: "return_to"

      • where: "lobby" | "results"

        Where to send the player to.

    • { playerName: string; type: "transfer_host" }

      • playerName: string

        The name of the player that should get host.

      • type: "transfer_host"

    • {
          song: {
              artist: string;
              audioURL: string;
              cover: string | null;
              hrefURL: string;
              name: string;
          };
          startPos: number;
          type: "player_pick_song";
      }

      • song: {
            artist: string;
            audioURL: string;
            cover: string | null;
            hrefURL: string;
            name: string;
        }

        The song the player picked in the choose step.

        • artist: string

          The name of the song artist.

        • audioURL: string

          A URL to the audio file of the song. Currently only audio previews from Apple Music and SoundCloud are allowed.

        • cover: string | null

          Cover URL of the song.

        • hrefURL: string

          The URL users will be redirected to when clicking.

        • name: string

          The name of the song.

      • startPos: number

        The selected start pos for the song.

        See

        RoomConfigMessageSchema.audioStartPosition

      • type: "player_pick_song"

    • {
          players: Record<
              string,
              {
                  answerData?: {
                      answer?: string;
                      answerIndex?: number;
                      answerSpeed: number;
                      answerTimestamp: number;
                      questionPoints: number;
                  };
                  color: string;
                  isHost: boolean;
                  isSpectator: boolean;
                  points: number;
                  username: string;
              },
          >;
          state: "lobby"
          | "results"
          | "ingame";
          type: "room_state";
          uuid: string;
          version: string;
      }

      • players: Record<
            string,
            {
                answerData?: {
                    answer?: string;
                    answerIndex?: number;
                    answerSpeed: number;
                    answerTimestamp: number;
                    questionPoints: number;
                };
                color: string;
                isHost: boolean;
                isSpectator: boolean;
                points: number;
                username: string;
            },
        >

        A map of all active (online, non-spectating) players. Key is server generated uuid, NOT connection id.

      • state: "lobby" | "results" | "ingame"

        The current game state

      • type: "room_state"

      • uuid: string

        The player's unique identifier generated by the server. Not connection id!

      • version: string

        The current version of the server.

    • {
          filteredSongsCount: number;
          playlists?: {
              cover: string | null;
              hrefURL: string;
              name: string;
              songs: {
                  artist: string;
                  audioURL: string;
                  cover: string | null;
                  hrefURL: string;
                  name: string;
              }[];
              subtitle?: string;
          }[];
          type: "update_playlists";
      }

      • filteredSongsCount: number

        The count of filtered songs.

        See

        filterSongs

      • Optionalplaylists?: {
            cover: string | null;
            hrefURL: string;
            name: string;
            songs: {
                artist: string;
                audioURL: string;
                cover: string | null;
                hrefURL: string;
                name: string;
            }[];
            subtitle?: string;
        }[]

        Currently selected playlist(s)

      • type: "update_playlists"

    • { countdown: number; type: "countdown" }

      • countdown: number

        The current countdown number. 0 to hide.

      • type: "countdown"

    • {
          gamePhase: GamePhase;
          question?:
              | {
                  answerOptions: string[];
                  correctAnswerIndex?: number;
                  questionType: "multiple_choice";
                  startPos: number;
              }
              | {
                  correctAnswer?: {
                      artist: string;
                      audioURL: string;
                      cover: string
                      | null;
                      hrefURL: string;
                      name: string;
                  };
                  pickerId: string;
                  questionCount: number;
                  questionCurrent: number;
                  questionType: "player_picks";
                  startPos: number;
              };
          roundCurrent: number;
          type: "round_state";
      }

      • gamePhase: GamePhase

        The current game phase.

        See

        GamePhase

      • Optionalquestion?:
            | {
                answerOptions: string[];
                correctAnswerIndex?: number;
                questionType: "multiple_choice";
                startPos: number;
            }
            | {
                correctAnswer?: {
                    artist: string;
                    audioURL: string;
                    cover: string
                    | null;
                    hrefURL: string;
                    name: string;
                };
                pickerId: string;
                questionCount: number;
                questionCurrent: number;
                questionType: "player_picks";
                startPos: number;
            }

      • roundCurrent: number

        The round number.

      • type: "round_state"

    • {
          songs: {
              artist: string;
              audioURL: string;
              cover: string | null;
              hrefURL: string;
              name: string;
          }[];
          type: "update_played_songs";
      }

      • songs: {
            artist: string;
            audioURL: string;
            cover: string | null;
            hrefURL: string;
            name: string;
        }[]

        The songs that were played in this round.

      • type: "update_played_songs"

    • {
          entry: LogEntry;
          level: "error" | "info" | "warn" | "debug";
          type: "add_log_message";
      }

      • entry: LogEntry

        The added log message.

      • level: "error" | "info" | "warn" | "debug"

        The log level of the added message.

      • type: "add_log_message"

    • { messages: LoggerStorage; type: "update_log_messages" }
    • { duration: number; offset: number; type: "progressbar_update" }

      • duration: number

        The duration of the progressbar.

      • offset: number

        The number of seconds to offset the progress bar start point.

      • type: "progressbar_update"

    • { type: "other" }
  • ...checks: (
        | "lobby"
        | "host"
        | "not_lobby"
        | "not_contdown"
        | "not_ingame"
        | "min_song_count"
    )[]

    One of the following:

    • "host": Checks whether the connection is the host or an admin.
    • "lobby": Checks whether the game is currently in lobby.
    • "not_lobby": Checks for the opposite.
    • "not_contdown": Checks whether a countdown is currently running.
    • "not_ingame": Checks whether currently not ingame.
    • "min_song_count": Checks whether the minimum song count is reached.

  Returns boolean

  true, if ALL checks were successful, false otherwise.

startCountdown

• startCountdown(from: number, callback: () => void): void

  Starts a countdown that is shown for all players.

  Parameters

  • from: number

    The number to count down from.

  • callback: () => void

    A function to call as soon as the countdown finishes.

  Returns void

stopCountdown

• stopCountdown(): void

  Stops a countdown if running.

  Returns void

toStorage

• toStorage(): PersistedRoomState

  Serializes this room instance to a PersistedRoomState object.

  Returns PersistedRoomState

transferHost

• transferHost(newHost: Player | undefined, sendUpdate?: boolean): void

  Transfers the host to another connection

  Parameters

  • newHost: Player | undefined

    the new host connection. Undefined if no one should be the host.

  • sendUpdate: boolean = true

    whether to broadcast an update (that also informs the new host that it got host).

  Returns void

StaticfromStorage

• fromStorage(
      server: SongGuessServer,
      state: PersistedRoomState | PersistedServerState,
  ): ValidRoom

  Creates a new ValidRoom object.

  Parameters

  • server: SongGuessServer

    a reference to the SongGuessServer this room belongs to

  • state: PersistedRoomState | PersistedServerState

    the serialized PersistedServerState or PersistedRoomState to create this room from

  Returns ValidRoom