Joining

Once the player has picked from the browser (or the game places them automatically), you join with Gamehoster.Instance.Join. Joining collects any details the game asks each player for, connects over the socket protocol, and hands you back an Instance to drive everything else.

Provisional: tracks the frontend API as it settles.

Joining a game

There are two ways in, plus creating a room. Each way in lives on Gamehoster.Instance, takes the joining player's playerInfo first, and returns an operation handle: set its onSuccess and onError, and call cancel() to give up. Which one you use follows what the player chose in the browser, itself governed by the game's browse setting:

Call	Joins
`Gamehoster.Instance.Join.Any(playerInfo)`	Matchmake anywhere: the player is dropped into any open instance, creating one if none has room.
`Gamehoster.Instance.Join.Instance(playerInfo, instance)`	A specific live instance the player picked. For a `key` room, pass `{ password }` as a third argument.
`Gamehoster.Create(instanceInfo?)`	Open a new room and join it; see creating a room.

const join = Gamehoster.Instance.Join.Any({ name: "Ada" })
join.onSuccess = (instance) => enter(instance)   // you're in — drive it from here
join.onError   = (error) => showJoinFailed(error) // full, closed, invalid info…
// later, to give up while it's still pending: join.cancel()

Joining a game: each way returns an operation handle

onSuccess runs once you're in, yielding the Instance you joined. onError runs if the join can't complete: the room is full or closed, or the player's info doesn't satisfy the game's schema.

Collecting player info

Some games ask each joining player for a little information: a display name, a colour. The game declares these as a schema, and the front end reads that schema from Gamehoster.Instance.Join.Info to build its form. The values the player fills in are the playerInfo object you pass to every join call:

const schema = Gamehoster.Instance.Join.Info   // the fields the game asks for
const playerInfo = showJoinForm(schema)        // your UI collects the values

const join = Gamehoster.Instance.Join.Any(playerInfo)
join.onSuccess = (instance) => enter(instance)
join.onError   = (error) => showJoinFailed(error)   // includes invalid info

Reading the schema, then passing the collected playerInfo

The client validates playerInfo against the schema and rejects a bad one through onError. Where the game asks for nothing, the schema is empty and playerInfo is {}; you join straight away. See playerInfo & the join schema for the shape.

Creating a room

If the player opts to open a new room rather than join an existing one, the top-level Gamehoster.Create creates one and joins it. You pass instanceInfo (the room settings the game lets you choose, such as its access and capacity) and get back the same operation handle. Every field is optional; a bare Create() opens a default room:

const room = Gamehoster.Create({ access: "key", capacity: 8, password: "hunter2" })
room.onSuccess = (instance) => enter(instance)   // a new keyed room, joined
room.onError   = (error) => showJoinFailed(error)

Creating a room and joining it

See Create for the full instanceInfo fields.

What you get back

Whichever way you joined, onSuccess yields an Instance: the live room you're now in. It's the same shape Browse lists, plus you, your own player id in the room:

{
  "id":       "i-7f3a2c",
  "phase":    "waiting",
  "players":  4,
  "capacity": 8,
  "access":   "open",
  "you":      "p-92"
}

an Instance, as yielded by onSuccess

Field	Type	Description
`id`	string	Unique id of the room you joined.
`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.
`you`	string	Your own player id within the room.

Hold onto this instance; you pass it to every in-room call on Gamehoster.Instance.*.

What's next

With the instance in hand you drive the rest of the front end through Gamehoster.Instance, each call taking the instance first: track its current state with Instance.State(instance), draw its frames with Instance.Frame(instance), and send input and commands with Instance.Send(instance, command). When the player is done, Instance.Leave(instance) disconnects them.