Browsing

Whether your front end shows the player a menu before they join (and what's in it) is decided by the game's browse setting. The generated client exposes exactly what that setting allows: with it, the front end can fetch the list of live instances for the player to choose from, and nothing more.

Provisional: a first pass at the shape of the API, to refine alongside the overview.

What the setting lets you fetch

Game's `browse`	What the front end may do
`none`	Nothing to choose; call `Instance.Join.Any(playerInfo)` and the player is placed by matchmaking. No list is available to fetch.
`instances`	Fetch the list of live instances, and let the player join one, or open a new one.

The client only ever hands you the list the definition permits, so you can't accidentally expose a browser the game didn't ask for.

Using the game browser

Your game library provides a function for fetching the live instances, so you can build whatever menu the game's browse setting allows.

Instances

An instance is a live room: the game itself, in progress. Browse.Instances() takes no argument and returns a subscription handle; set its onChange and onError, and call cancel() to stop:

const instances = Gamehoster.Browse.Instances()
instances.onChange = (list) => {
  // render the current list of live instances
}
instances.onError = (error) => showBrowseError(error)
// later: instances.cancel()

Subscribing to the list of live instances

onChange runs once at the start and again every time the list changes, until you cancel(); onError runs on failure, including the game's settings not allowing this. Each item is an instance summary:

Field	Type	Description
`id`	string	Unique id of the instance; pass it to `Instance.Join.Instance(playerInfo, id)` to join this one.
`phase`	string	Its current phase: for pong, one of `waiting`, `playing` or `over`.
`players`	number	How many players are currently in it.
`capacity`	number	The maximum number of players it holds.
`access`	string	`open` to join freely, or `key` if a password is needed.

Private rooms don't appear in this list; a player reaches one with its key.