Class Client<TSlotData>
Type Parameters
-
-
TSlotData = SlotData
TSlotData = SlotData
Hierarchy
- Client
@@ -71,7 +71,7 @@ constructorType Parameters
-
-
TSlotData = SlotData
-
-
TSlotData = SlotData
TSlotData = SlotData
Returns Client<TSlotData>
Accessors
@@ -85,18 +85,18 @@dataReturns DataManager<TSlotData>
hints
-
-
- get hints(): HintManager +
- get hints(): HintsManager
- -
Generated using TypeDoc
Hierarchy
- PlayersManager
@@ -36,9 +36,14 @@ Constructors
Accessors
+Methods
client: Returns PlayersManager +
Accessors
+all
+Methods
Returns stringThrows
Throws an error if unable to find a player with the given id.
game
-
@@ -115,7 +133,23 @@
Returns stringThrows
Throws an error if unable to find a player with the given id.
get
+members
-
@@ -135,7 +169,7 @@
id: Returns number[]
name
-
@@ -160,7 +194,7 @@
Returns stringThrows
Throws an error if unable to find a player with the given id.
Generated using TypeDoc
Hierarchy
- SetOperationsBuilder
@@ -67,12 +67,12 @@ Parameters
key: string
-defaultValue: JSONSerializableData
+defaultValue: JSONSerializableData
wantReply: boolean = false
key: string
defaultValue: JSONSerializableData
wantReply: boolean = false
Returns SetOperationsBuilder
+Methods
Parameters
value: number | number[]
Returns SetOperationsBuilder
+and
-
@@ -100,7 +100,7 @@
Parameters
value: number
Returns SetOperationsBuilder
build
-
@@ -108,7 +108,7 @@
build
Returns SetPacket
default
Returns SetOperationsBuilder
max
-
@@ -134,7 +134,7 @@
Parameters
value: number
Returns SetOperationsBuilder
min
-
@@ -147,7 +147,7 @@
Parameters
value: number
Returns SetOperationsBuilder
modulo
-
@@ -160,7 +160,7 @@
Parameters
value: number
Returns SetOperationsBuilder
multiply
-
@@ -173,7 +173,7 @@
Parameters
value: number
Returns SetOperationsBuilder
or
-
@@ -186,7 +186,7 @@
Parameters
value: number
Returns SetOperationsBuilder
pop
Returns SetOperationsBuilder
power
-
@@ -212,7 +212,7 @@
Parameters
value: number
Returns SetOperationsBuilder
remove
Returns SetOperationsBuilder
replace
Returns SetOperationsBuilder
shift
-
@@ -251,7 +251,7 @@
Parameters
value: number
Returns SetOperationsBuilder
shift
-
@@ -264,7 +264,7 @@
Parameters
value: number
Returns SetOperationsBuilder
update
Returns SetOperationsBuilder
xor
-
@@ -290,7 +290,7 @@
Parameters
value: number
Returns SetOperationsBuilder
Generated using TypeDoc
archipelago.js - v1.0.2
archipelago.js - v1.1.0
Archipelago.JS
A general purpose library for communicating with Archipelago servers in Node.js or in the browser.
+You can install it from npm or use a CDN to use it in browser.
+-
+
- NPM:
npm install archipelago.js
+ - CDN:
import { /* ... */ } from "https://unpkg.com/archipelago.js/dist/archipelago.min.js";in a +<script type="module"></script>block.
+
Archipelago.js Node.js Quick Start Guide
Archipelago.js is a JavaScript library that runs in Node or the browser that allows you to connect to an Archipelago server and communicate with it for your JavaScript-based games or tools. This guide will walk you through the process of setting up a client and connecting to an Archipelago server.
@@ -51,8 +57,9 @@archipelago.js - v1.0.2
Running in Browser
Archipelago.js can also run in the browser. Here's an example that works in most major browsers:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Archipelago.js Client Example</title>
</head>
<body>
<script type="module">
import {
Client,
ITEMS_HANDLING_FLAGS,
SERVER_PACKET_TYPE,
} from "https://unpkg.com/archipelago.js/dist/archipelago.min.js";
// Create a new Archipelago client
const client = new Client();
const connectionInfo = {
hostname: "your-server-hostname", // Replace with the actual AP server hostname.
port: 38281, // Replace with the actual AP server port.
game: "your-game-name", // Replace with the game name for this player.
name: "your-player-name", // Replace with the player slot name.
items_handling: ITEMS_HANDLING_FLAGS.REMOTE_ALL,
};
// Set up event listeners
client.addListener(SERVER_PACKET_TYPE.CONNECTED, (packet) => {
console.log("Connected to server: ", packet);
});
client.addListener(SERVER_PACKET_TYPE.ROOM_UPDATE, (packet) => {
console.log("Room update: ", packet);
});
// Connect to the Archipelago server
client
.connect(connectionInfo)
.then(() => {
console.log("Connected to the server");
// You are now connected and authenticated to the server. You can add more code here if need be.
})
.catch((error) => {
console.error("Failed to connect:", error);
// Handle the connection error.
});
// Disconnect from the server when unloading window.
window.addEventListener("beforeunload", () => {
client.disconnect();
});
</script>
</body>
</html>
In this example, the Archipelago client is included as a script from the https://unpkg.com/archipelago.js CDN. You can -also use a locally hosted version of the library if you prefer.
+In this example, the Archipelago client is included as a script from the +https://unpkg.com/archipelago.js/dist/archipelago.min.js CDN. You can also use a locally hosted version of the library +if you prefer.
Handling Server Events
You can listen for server events and handle them in your code. Here's an example of adding an event listener for the "PrintJSON" event:
import { /* ... */, SERVER_PACKET_TYPE } from "archipelago.js";
// Add an event listener for the PRINT_JSON event
client.addListener(SERVER_PACKET_TYPE.PRINT_JSON, (packet, message) => {
console.log("Received a PrintJSON: ", message);
// Add any additional logic here.
});
@@ -75,6 +82,25 @@ archipelago.js - v1.0.2
Player
Player objects returned from PlayersManager contain the following data and helper functions for easy item and location
+name lookups:
-
+
name: The slot name for this player.
+alias: The aliased name for this player.
+slot: The slot number for this player.
+team: The team number for this player.
+game: The name of the game this player is playing.
+type: Whether this player is a spectator, actual player, or item link group.
+group_members: If this player is an item link group, this is the ids of all players that belong to this group.
+item(itemId): A function that returns the name for a given item id in the game of this player.-
+
- Example:
const itemName = player.item(1000);
+
+- Example:
location(locationId): A function that returns the name for a given location id in the game of this player.-
+
- Example:
const locationName = player.location(1000);
+
+- Example:
LocationsManager
The LocationsManager class in archipelago.js provides functionality for managing locations within the game. Here are
some tips for working with the LocationsManager:
-
@@ -89,15 +115,10 @@
Retrieve Location Name: Use the
+If the location or game is not found, it will return an "Unknown Location" string instead.namemethod to retrieve the name of a location based on its ID and game name. -If the location or game is not found, it will return a default message.const locationName = client.locations.name("your-game-name", locationId);
-Retrieve Location ID: Use the
-idmethod to retrieve the ID of a location based on its name and game name. If -the location or game is not found, it will throw an error.
-const locationId = client.locations.id("your-game-name", "location-name"); -Retrieve Location Group: Use the
groupmethod to retrieve an array of location names belonging to a specific group in a game. If the game or group is not found, it will return an empty array.const locationGroup = client.locations.group("your-game-name", "group-name"); @@ -126,12 +147,21 @@archipelago.js - v1.0.2
const playerGame = client.players.game(playerId);
-Retrieve Group Members: Use the members method to retrieve an array of player IDs belonging to an item links +
Retrieve Group Members: Use the
membersmethod to retrieve an array of player IDs belonging to an item links group. If the id is of someone who is not an item links group or the group is not found, it will return an empty array.const groupMembers = client.players.members(groupId);
+Retrieve all Players: Use the
+allmethod to return an array of allPlayerobjects that are in this room.
+const players = client.players.all; +
+Retrieve a specific Player: Use the
+getmethod to return aPlayerobject with that id. Returnsundefinedif +player does not exist.
+const playerOne = client.players.get(1); +
archipelago.js - v1.0.2
Special Cases: The methods in PlayersManager handle some special cases. For example, if the player ID is 0, it
represents the server (Archipelago), and the methods will return appropriate values for these cases. See documentation
@@ -139,11 +169,6 @@
archipelago.js - v1.0.2
DataManager
The DataManager class in archipelago.js is responsible for managing room session data and the data package. Here are
some tips for working with the DataManager:
-
-
Retrieve Player Information: Use the
-playersproperty to access a map of all players, keyed by their player -IDs.
-const player = client.data.players.get(playerId); -Retrieve Games List: Use the
gamesproperty to get an array of all games present in the room.
@@ -197,9 +222,20 @@const gamesList = client.data.games;archipelago.js - v1.0.2
const itemGroup = client.items.group(gameName, groupName);
+Retrieve all received items: Use the
+receivedproperty to retrieve an array of all items that have been sent +by the server.
+const allItems = client.items.received; +
+Retrieve ReceivedItem index: Returns the
+indexof the next expected item to be received from the server. Any +items with a lower index are stored inItemsManager.received. Useful for tracking if new items have been received +or to check if a de-sync event occurred.
+const receivedItemIndex = client.items.index; +
HintManager
The HintManager class in archipelago.js is responsible for managing hint events for a specific player slot. Here are
-some tips for working with the HintManager:
HintsManager
The HintsManager class in archipelago.js is responsible for managing hint events for a specific player slot. Here are
+some tips for working with the HintsManager:
- Get Relevant Hints: Use the
mineproperty to access an array of hints that are relevant to the player slot.
Get the HintManager helper object. See HintManager for additional information.
+Get the HintsManager helper object. See HintsManager for additional information.
Returns HintManager
+Returns HintsManager
+items
@@ -107,7 +107,7 @@
itemsReturns ItemsManager
locations
@@ -118,7 +118,7 @@
locationsReturns LocationsManager
players
@@ -129,7 +129,7 @@
playersReturns PlayersManager
status
@@ -140,7 +140,7 @@
statusReturns ConnectionStatus
uri
@@ -151,7 +151,7 @@
uriReturns undefined | string
Methods
Returns voidReturns void
+Add an eventListener to fire depending on an event from the Archipelago server or the client.
@@ -220,7 +220,7 @@Returns voidReturns void
+Add an eventListener to fire depending on an event from the Archipelago server or the client.
@@ -252,7 +252,7 @@Returns voidReturns void
+Add an eventListener to fire depending on an event from the Archipelago server or the client.
@@ -284,7 +284,7 @@Returns voidReturns void
+Add an eventListener to fire depending on an event from the Archipelago server or the client.
@@ -316,7 +316,7 @@Returns voidReturns void
+Add an eventListener to fire depending on an event from the Archipelago server or the client.
@@ -348,7 +348,7 @@Returns voidReturns void
+Add an eventListener to fire depending on an event from the Archipelago server or the client.
@@ -382,7 +382,7 @@Returns voidReturns void
+Add an eventListener to fire depending on an event from the Archipelago server or the client.
@@ -414,7 +414,7 @@Returns voidReturns void
+Add an eventListener to fire depending on an event from the Archipelago server or the client.
@@ -446,7 +446,7 @@Returns voidReturns void
+Add an eventListener to fire depending on an event from the Archipelago server or the client.
@@ -478,7 +478,7 @@Returns voidReturns void
+Add an eventListener to fire depending on an event from the Archipelago server or the client.
@@ -510,7 +510,7 @@Returns voidReturns void
+Add an eventListener to fire depending on an event from the Archipelago server or the client.
@@ -542,7 +542,7 @@Returns voidReturns void
+Add an eventListener to fire depending on an event from the Archipelago server or the client.
@@ -574,7 +574,7 @@Returns voidReturns void
+connect
@@ -586,7 +586,7 @@
connectParameters-
-
info: ConnectionInformation
+info: ConnectionInformation
All the necessary connection information to connect to an Archipelago server.
Rejects
If web socket connection failed to establish connection or se return a
string[]of error messages.disconnect
@@ -609,7 +609,7 @@
disconnectReturns void
remove
@@ -644,7 +644,7 @@- Defined in Client.ts:265
Returns voidReturns void
+Remove an eventListener from this client's event emitter.
@@ -676,7 +676,7 @@Returns voidReturns void
+Remove an eventListener from this client's event emitter.
@@ -708,7 +708,7 @@Returns voidReturns void
+Remove an eventListener from this client's event emitter.
@@ -740,7 +740,7 @@Returns voidReturns void
+Remove an eventListener from this client's event emitter.
@@ -772,7 +772,7 @@Returns voidReturns void
+Remove an eventListener from this client's event emitter.
@@ -804,7 +804,7 @@Returns voidReturns void
+Remove an eventListener from this client's event emitter.
@@ -838,7 +838,7 @@Returns voidReturns void
+Remove an eventListener from this client's event emitter.
@@ -870,7 +870,7 @@Returns voidReturns void
+Remove an eventListener from this client's event emitter.
@@ -902,7 +902,7 @@Returns voidReturns void
+Remove an eventListener from this client's event emitter.
@@ -934,7 +934,7 @@Returns voidReturns void
+Remove an eventListener from this client's event emitter.
@@ -966,7 +966,7 @@Returns voidReturns void
+Remove an eventListener from this client's event emitter.
@@ -998,7 +998,7 @@Returns voidReturns void
+Remove an eventListener from this client's event emitter.
@@ -1030,7 +1030,7 @@Returns voidReturns void
+say
@@ -1049,7 +1049,7 @@
message: Returns void
send
@@ -1069,7 +1069,7 @@
RestReturns voidupdate
@@ -1088,7 +1088,7 @@
status: Returns void
Generated using TypeDoc
- Preparing search index...
-- The search index is not available
archipelago.js - v1.0.2Hierarchy
- DataManager
+@@ -83,7 +83,7 @@
client: Returns DataManager<TSlotData>
Accessors
gamesReturns string[]
hint
@@ -107,7 +107,7 @@
hint
hint
@@ -118,18 +118,18 @@
hint
package
-- get package(): ReadonlyMap<string, GamePackage>
+- get package(): ReadonlyMap<string, GamePackage>
-
-
- Defined in managers/DataManager.ts:52
+- Defined in managers/DataManager.ts:115
@@ -249,11 +249,11 @@
-
Returns a map of all GamePackage mapped to their game
+name.Returns a map of all GamePackage mapped to their game
name.Returns ReadonlyMap<string, GamePackage>
+Returns ReadonlyMap<string, GamePackage>
+permissions
@@ -140,18 +140,18 @@
permissionsReturns Permissions
players
-- get players(): ReadonlyMap<number, Player>
+- get players(): readonly Player[]
-
-
- Defined in managers/DataManager.ts:59
+- Defined in managers/DataManager.ts:108
+- Defined in managers/DataManager.ts:94
+- Defined in managers/DataManager.ts:87
+- Defined in managers/DataManager.ts:101
@@ -217,7 +217,7 @@ - Defined in managers/DataManager.ts:125
Returns a map of all
+players, keyed by player id.Returns an array of all
players, keyed by player id.Returns ReadonlyMap<number, Player>
+Returns readonly Player[]
+seed
@@ -162,7 +162,7 @@
seedReturns string
slot
@@ -173,7 +173,7 @@
slotReturns number
slot
@@ -184,7 +184,7 @@
slot
team
@@ -195,7 +195,7 @@
teamReturns number
Methods
setOperation: Returns Promise<void | SetReplyPacket>
Generated using TypeDoc
+- Preparing search index...
+- The search index is not available
archipelago.js - v1.1.0+- archipelago.js
+- HintsManager
+Class HintsManager
Manages and watches for hint events to this player slot and provides helper functions to make working with hints +easier.
+Hierarchy
++- HintsManager
+
+Index
Constructors
+Accessors
+Constructors
+constructor
++- new
+-
+
+
+
Parameters
++-
+
client: Client<unknown>
Returns HintsManager
Accessors
+mine
++- get mine(): readonly Hint[]
+-
+
Get all hints that are relevant for this slot.
+Returns readonly Hint[]
++
+Settings
Member Visibility
Theme
+
+On This Page
+- constructor
+- mine
Generated using TypeDoc
- Preparing search index...
-- The search index is not available
archipelago.js - v1.0.2Hierarchy
- ItemsManager
+@@ -35,9 +35,13 @@constructor
Constructors
Accessors
+Methods
client: Returns ItemsManager
Accessors
+index
++- get index(): number
+-
+
Returns the current item index. If this value is larger than expected, that means new items have been received.
+Returns number
+received
++- get received(): readonly NetworkItem[]
+-
+
Returns an array of all items that have been received.
+Returns readonly NetworkItem[]
+Methods
Returns stringThrows
Throws an error if unable to find game for group in data package.
id
+name
-- id(game, name): number
+- name(player, id): string
-
-
-
-
-
-
-
-
-- name(game, id): string
-
-
- Defined in managers/ItemsManager.ts:45
Returns the
+idof a given itemname.Returns the
nameof a given itemid.Parameters
game: string
-The
+nameof the game this item belongs to.player: number
+The
idof the player this item belongs to.name: string
-The
+nameof this item.id: number
+The
idof this item.Returns number
+Returns string
Returns the name of the item or
+Unknown Item: <id>if item or player is not in data.Throws
Throws an error if unable to find the
+idfor an item or unable to find game in data package.Throws
Throws an error if
playeroridis not a safe integer.name
--- name(game, id): string
+- Defined in managers/ItemsManager.ts:34
+Returns the
nameof a given itemid.id:
The
idof this item.Returns string
Returns the name of the item or
+Unknown <Game> Item: <Id>if item or game is not in data package.Returns string
Returns the name of the item or
Unknown Item: <id>if item or player is not in data.Throws
Throws an error if
idis not a safe integer.Generated using TypeDoc
- Preparing search index...
-- The search index is not available
archipelago.js - v1.0.2Hierarchy
- LocationsManager
+@@ -45,7 +45,6 @@auto
Methods
client: Returns LocationsManager +
Accessors
checkedReturns readonly number[]
missing
@@ -94,7 +93,7 @@
missingReturns readonly number[]
Methods
auto
check
@@ -126,7 +125,7 @@
RestReturns voidgroup
@@ -148,37 +147,35 @@
Returns stringThrows
Throws an error if unable to find game for group in data package.
id
+name
-- id(game, name): number
+- name(player, id): string
-
-
-
-
-
-
-
-
-- name(game, id): string
-
-
+- Defined in managers/LocationsManager.ts:88
- Defined in managers/LocationsManager.ts:60
Returns the
+idof a given locationname.Returns the
nameof a given locationid.Parameters
game: string
-The
+nameof the game this location belongs to.player: number
+The
idof the player this location belongs to.name: string
-The
+nameof this location.id: number
+The
idof this location.Returns number
+Returns string
Returns the name of the location or
+Unknown Location: <id>if location or player is not in data.Throws
Throws an error if unable to find the
+idfor a location or unable to find game in data package.Throws
Throws an error if
playeroridis not a safe integer.name
--- name(game, id): string
+- Defined in managers/LocationsManager.ts:77
+Returns the
nameof a given locationid.id:
The
idof this location.Returns string
Returns the name of the location or
+Unknown <Game> Location: <Id>if location or game is not in data -package.Returns string
Returns the name of the location or
Unknown Location: <id>if location or player is not in data.Throws
Throws an error if
idis not a safe integer.scout
@@ -226,7 +222,7 @@
RestReturns void