Class Client

constructor

• new Client(options?): Client

• Instantiates a new Archipelago client. After creating, call Client.login to connect and authenticate to a server.

  Parameters

  • Optionaloptions: ClientOptions

    Additional configuration options for this client. See ClientOptions for more information.

  Returns Client

ReadonlydeathLink

Readonlyitems

Readonlymessages

options

Readonlypackage

Readonlyplayers

Readonlyroom

Readonlysocket

Readonlystorage

arguments

• get arguments(): Required<ConnectionOptions>

• Returns a copy of this client's current connection arguments (or defaults, if never connected).

  Returns Required<ConnectionOptions>

authenticated

• get authenticated(): boolean

• Returns true if currently connected and authenticated to the Archipelago server.

  Returns boolean

game

• get game(): string

• Returns the client's current game name (or an empty string, if never connected).

  Returns string

name

• get name(): string

• Returns the client's current slot name (or an empty string, if never connected).

  Returns string

bounce

• bounce(targets, data): void

• Send a bounce packet targeting any clients that fulfil any target parameters. Can be listened for by listening to "bounced" events on SocketManager.

  Parameters

  • targets: {
        games?: string[];
        slots?: number[];
        tags?: string[];
    }

    The targets to receive this bounce packet.

    • Optionalgames?: string[]

      Specific games that should receive this bounce.

    • Optionalslots?: number[]

      Specific slots that should receive this bounce.

    • Optionaltags?: string[]

      Specific clients with these tags that should receive this bounce.
  • data: JSONRecord

    The json-serializable data to send.

  Returns void

  Throws

  UnauthenticatedError If attempting to send a bounce while not authenticated.

  Remarks

  If no targets are specified, no clients will receive this bounce packet.

check

• check(...locations): void

• Marks a list of locations as checked on the server.

  Parameters

  • Rest...locations: number[]

    Location ids to check.

  Returns void

  Throws

  UnauthenticatedError If attempting to check locations while not authenticated.

  Remarks

  Locations that do not exist or have already been checked in the multi-world are ignored.

goal

• goal(): void

• A shorthand for running Client.updateStatus(clientStatuses.goal). Once set, cannot be changed and if release and/or collect is set to automatic, will release/collect all items.

  Returns void

  Throws

  UnauthenticatedError If not connected and authenticated.

login

• login<SlotData>(url, name, game?, options?): Promise<SlotData>

• Connect and authenticate to an Archipelago server.

  Type Parameters

  • SlotData extends JSONRecord

    If slot data is requested, this sets the type of the returning slot data.

  Parameters

  • url: string | URL

    The url of the server, including the protocol (e.g., wss://archipelago.gg:38281).
  • name: string

    The slot name this client will be connecting to.
  • game: string = ""

    The game name this client will be connecting to. If omitted, client will connect in "TextOnly" mode.
  • Optionaloptions: ConnectionOptions

    Additional optional connection arguments.

  Returns Promise<SlotData>

  Throws

  ArgumentError If slot name is empty.

  Throws

  LoginError If the server refuses the authentication attempt.

  Throws

  TypeError If provided URL is malformed or invalid protocol.

  Remarks

  If the port is omitted, the client will default to 38281 (AP default).

  If the protocol is omitted, client will attempt to connect via wss, then fallback to ws if unsuccessful.

  Any paths, queries, fragments, or userinfo components of the provided url will be ignored.

  Example: Password Required and No Slot Data

  import { Client } from "archipelago.js";
  
  const client = new Client();
  
  await client.login("wss://archipelago.gg:38281", "Phar", "Clique", {
      slotData: false,
      password: "4444"
  });
  Copy

  Example: TypeScript with Slot Data

  import { Client } from "archipelago.js";
  
  interface CliqueSlotData {
      color: string
      hard_mode: boolean
  }
  
  const client = new Client();
  
  // slotData: CliqueSlotData { color: "red", hard_mode: false }
  const slotData = await client.login<CliqueSlotData>("wss://archipelago.gg:38281", "Phar", "Clique");
  Copy

scout

• scout(locations, createHint?): Promise<Item[]>

• Scout a list of locations for their containing items.

  Parameters

  • locations: number[]

    A list of location ids to scout.
  • createHint: 0 | 1 | 2 = 0

    Whether to create hints for these locations.

    • If set to 0, this packet will not create hints for any locations in this packet.
    • If set to 1, this packet will create hints for all locations in this packet and broadcast them to all relevant clients.
    • If set to 2, this packet will create hints for all locations in this packet and broadcast only new hints to all relevant clients.

  Returns Promise<Item[]>

  Throws

  UnauthenticatedError If attempting to scout locations while not authenticated.

updateItemsHandling

• updateItemsHandling(items): void

• Request the server update the kinds of item received events this client should receive.

  Parameters

  • items: number

    New item handling flags.

  Returns void

  Throws

  UnauthenticatedError If not connected and authenticated.

updateStatus

• updateStatus(status): void

• Update the client status for the current player. For a list of known client statuses, see clientStatuses.

  Parameters

  • status: ClientStatus

    The status to change to.

  Returns void

  Throws

  UnauthenticatedError If not connected and authenticated.

  Remarks

  The server will automatically set the player's status to clientStatuses.disconnected when all clients connected to this slot have disconnected, set the status to clientStatuses.connected if a client connects to this slot when previously set to clientStatuses.disconnected, or ignores any future updates if ever set to clientStatuses.goal.

  Example

  import { Client, clientStatuses } from "archipelago.js";
  
  const client = new Client();
  await client.login("wss://archipelago.gg:38281", "Phar", "Clique");
  
  // Mark client as ready to start.
  client.updateStatus(clientStatuses.ready);
  Copy

updateTags

• updateTags(tags): void

• Request the server update this client's tags.

  Parameters

  • tags: string[]

    Tags to replace the current ones.

  Returns void

  Throws

  UnauthenticatedError If not connected and authenticated.