archipelago.js
v1.1.0
Published
A general-purpose client library for communicating with Archipelago game servers, written for Node.js.
Downloads
328
Maintainers
Readme
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.
Prerequisites
Before you begin, make sure you have the following prerequisites:
- Node.js installed on your machine.
- Basic knowledge of JavaScript (or TypeScript).
Installation
To start a new project with Archipelago.js follow these steps:
- Create a new directory for your project.
- Open a terminal or command prompt and navigate to the project directory.
- Run the following command to initialize a new Node.js project:
npm install archipelago.js
. - If you plan to use TypeScript, also install typescript dependencies and nice to haves:
npm install -D typescript
.- Replace any instances of "
.js
" with ".ts
" in this quick start guide.
- Replace any instances of "
Getting Started
Follow the steps below to quickly set up a client and connect to an Archipelago server:
- Create a new file called
client.js
in your project directory. - Open the
client.js
file with your preferred code editor and add the following code:
// ES module import, but you can use CommonJS syntax as well, if you prefer.
import { Client, ITEMS_HANDLING_FLAGS } from "archipelago.js";
// Create a new instance of the Client class.
const client = new Client();
// Set up the connection information.
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,
};
// 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.
});
Make sure to replace "your-server-hostname", 38281, "your-game-name", "your-player-name", and set items_handling
with
the appropriate values for your game and room.
Then just run your client script using node client.js
or if you're using TypeScript: npx ts-node client.ts
.
That's it! You have now set up a client and connected to an Archipelago server using archipelago.js. You can start sending packets, handling server events, and building your multiplayer experience.
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/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.
});
Sending Client Events
You can also respond to the server at at time while you're connected. Here's a few examples of built-in events you can send.
Say: Use the
say
method to send a normal chat message.client.say("Hello, archipelago!");
Update Status: Use the
updateStatus
method to update your status from Ready to Playing or even Goal Complete, once your game has completed.import { /* ... */, CLIENT_STATUS } from "archipelago.js"; // See documentation for all possible statuses. client.updateStatus(CLIENT_STATUS.READY); client.updateStatus(CLIENT_STATUS.PLAYING); client.updateStatus(CLIENT_STATUS.GOAL);
Send Raw Packets: You can also just send raw packets to the server if none of the built-in methods work for your use cases. Be sure to add a listener for the response from the server though (see above)!
import { /* ... */, CLIENT_PACKET_TYPE } from "archipelago.js"; const syncPacket = { cmd: CLIENT_PACKET_TYPE.SYNC, } client.send(syncPacket);
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
:
Check Locations: Use the
check
method to mark locations as found. Pass the location IDs as arguments to the method.client.locations.check(locationId1, locationId2, locationId3);
Scout Locations: Use the
scout
method to scout locations without marking them as found. You can also create hints for these locations by passing theCREATE_AS_HINT_MODE
as the first argument followed by the location IDs.client.locations.scout(CREATE_AS_HINT_MODE.NO_HINT, locationId1, locationId2, locationId3);
Retrieve Location Name: Use the
name
method 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 an "Unknown Location" string instead.const locationName = client.locations.name("your-game-name", locationId);
Retrieve Location Group: Use the
group
method 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");
Automatically Release All Locations: Use the
autoRelease
method to send all missing locations as checked.client.locations.autoRelease();
PlayersManager
The PlayersManager
class in archipelago.js provides functionality for managing and looking up player data within the
game. Here are some helpful methods for working with the PlayersManager
:
Retrieve Player Name: Use the
name
method to retrieve the name of a player based on their ID. If the player is not found, it will throw an error.const playerName = client.players.name(playerId);
Retrieve Player Alias: Use the
alias
method to retrieve the alias of a player based on their ID. If the player is not found, it will throw an error.const playerAlias = client.players.alias(playerId);
Retrieve Player Game: Use the
game
method to retrieve the game name of a player based on their ID. If the player is not found, it will throw an error.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 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
all
method to return an array of allPlayer
objects that are in this room.const players = client.players.all;
Retrieve a specific Player: Use the
get
method to return aPlayer
object with that id. Returnsundefined
if player does not exist.const playerOne = client.players.get(1);
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
for full exceptions.
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 Games List: Use the
games
property to get an array of all games present in the room.const gamesList = client.data.games;
Retrieve Hint Cost: Use the
hintCost
property to get the number of hint points required to receive a hint.const hintCost = client.data.hintCost;
Retrieve Hint Points: Use the
hintPoints
property to get the number of hint points the player has.const hintPoints = client.data.hintPoints;
Retrieve Slot Data: Use the
slotData
property to access the slot data for the game.const slotData = client.data.slotData;
Retrieve Slot and Team: Use the
slot
andteam
properties to get the player's slot and team.const slot = client.data.slot; const team = client.data.team;
Retrieve Seed: Use the
seed
property to get the seed for the room.const seed = client.data.seed;
Retrieve Permissions: Use the
permissions
property to get the current permissions for the room.const permissions = client.data.permissions;
Send Set Operations: Use the
set
method to send a series of set operations using theSetOperationBuilder
object to the server. This method returns a promise that resolves with aSetReplyPacket
ifwantReply
was requested.import { /* ... */, SetOperationsBuilder } from "archipelago.js"; // Add additional set operations to the SetOperationBuilder. const setOperation = new SetOperationsBuilder("key", 0 /* default value */, true /* wantReply */) .add(12) // Add to it! .multiply(4) // Multiply it! .shiftLeft(2); // Shift bits! const setReply = await client.data.set(setOperation);
ItemsManager
The ItemsManager
class in archipelago.js is responsible for managing item data. Here are some tips for working with
the ItemsManager
:
Retrieve Item Name: Use the name method to retrieve the name of an item based on its ID and game name. If the item or game is not found, it will return a default message.
const itemName = client.items.name(gameName, itemId);
Retrieve Item ID: Use the
id
method to retrieve the ID of an item based on its name and game name. If the item or game is not found, it will throw an error.const itemId = client.items.id(gameName, itemName);
Retrieve Item Group: Use the
group
method to retrieve an array of item names belonging to a specific group in a game. If the game or group is not found, it will return an empty array.const itemGroup = client.items.group(gameName, groupName);
Retrieve all received items: Use the
received
property to retrieve an array of all items that have been sent by the server.const allItems = client.items.received;
Retrieve ReceivedItem index: Returns the
index
of 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;
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
mine
property to access an array of hints that are relevant to the player slot.
const relevantHints = client.hints.mine;
Hints update automatically for the slot the player is in when new hints are made that are relevant for the player.
Conclusion
Congratulations! You have successfully set up a client and hopefully learned a good amount of what this library is capable of! You are now ready to integrate Archipelago functionality into your application.
For more information, check out the archipelago.js API documentation and explore the available features and capabilities.
If you encounter any issues or have questions, feel free to reach out on the GitHub repository for support or directly to Phar (thephar) in the Archipelago Discord, and thanks for checking out my little pet project for Archipelago!
Contributing / Development
To develop further or contribute to Archipelago.JS itself, just clone this repository to a desired location on your computer:
git clone https://github.com/ThePhar/archipelago.js && cd archipelago.js
Then run npm install
to install all dependencies.
Archipelago.JS is written in TypeScript and includes a strong ESLint and Prettier config file to ensure code
consistency. Be sure to follow the code standards and check your work with npm run lint
. You can build your code by
running npm run pack
(to package in a .tgz
file) or npm run build
(for a full dist/
folder).
It is recommended to work in a branch other than main
, even if you fork, to avoid merge conflicts with GitHub when
pull requests and squash merges happen.
API Documentation & Other Links
The full API documentation is located here. Please be sure to reference it, while you are developing your JavaScript-based clients.
This library supports 100% of the Archipelago network protocol referenced at here as of 2023-07-08. See more information about Archipelago at their website.