Packets

Packets

Packets are the messages exchanged between your client and the Archipelago server. Each packet is a Python object (a Pydantic model) with named fields you can read and set.

• Client packets are sent by your client to the server (e.g. "authenticate me", "I checked this location")
• Server packets are received from the server (e.g. "here are your items", "a player sent a chat message")

The library automatically converts incoming JSON into the correct packet objects for you. You just work with Python objects in your callbacks.

For full protocol details, see the Archipelago Network Protocol.

Sending packets

To send a packet, create an instance and pass it to client.send():

# Send a chat message
await client.send(packets.Say(text="Hello!"))

# Report a checked location
await client.send(packets.LocationChecks(locations=[12345]))

Common types used in packets

These types appear frequently in the field tables below:

Type	Description	Import
Version	Server/client version (major, minor, build)	from archipelagopy.structs import Version
NetworkItem	An item in the multiworld (item ID, location ID, player, flags)	from archipelagopy.structs import NetworkItem
NetworkSlot	A slot/player in the game (name, game, type)	from archipelagopy.structs import NetworkSlot
NetworkPlayer	A player (team, slot, alias, name)	from archipelagopy.structs import NetworkPlayer
Permissions	Command permissions for the room	from archipelagopy.structs import Permissions
JSONMessagePart	A piece of a formatted message (text, color, type)	from archipelagopy.structs import JSONMessagePart
ItemHandlingFlag	Controls which items the server sends you	from archipelagopy.enums import ItemHandlingFlag
ClientStatus	Your client's game status (PLAYING, GOAL, etc.)	from archipelagopy.enums import ClientStatus
PrintJSONType	Type of message (CHAT, ITEM_SEND, HINT, etc.)	from archipelagopy.enums import PrintJSONType
DataStorageOperation	An operation on the server's key-value store	from archipelagopy.structs import DataStorageOperation

---

Client packets (client -> server)

Connect

Authenticate with the server. This is typically the first packet you send after connecting.

Field	Type	Default	Description
version	Version	(required)	Client version
name	str	(required)	Your slot name (assigned when the game was generated)
tags	list[str]	[]	Client tags (e.g. ["AP"], ["Tracker"])
items_handling	ItemHandlingFlag	NONE	Which items to receive from the server
game	str | None	None	Game name
slot_data	bool	False	Request game-specific slot data
password	str	""	Room password (if the room has one)
uuid	str	""	Unique client identifier

ConnectUpdate

Update your connection settings after authenticating.

Field	Type	Description
tags	list[str]	Updated client tags
items_handling	ItemHandlingFlag	Updated item handling flags

Say

Send a chat message visible to all players.

Field	Type	Description
text	str	Message text

Bounce

Relay a message to specific other clients via the server. Useful for client-to-client communication.

Field	Type	Default	Description
slots	list[int]	(required)	Target slot IDs to send to
games	list[str] | None	None	Only send to clients playing these games
tags	list[str] | None	None	Only send to clients with these tags
data	dict | None	None	The data payload to relay

LocationChecks

Tell the server that you've checked (completed) locations in your game.

Field	Type	Description
locations	list[int]	Location IDs that were checked

LocationScouts

Ask the server what items are at specific locations, without checking them.

Field	Type	Description
locations	list[int]	Location IDs to scout
create_as_hint	LocationScoutHint	Whether to create hints for the scouted locations

StatusUpdate

Tell the server your current game status (e.g. you've reached your goal).

Field	Type	Description
status	ClientStatus	New status (PLAYING, GOAL, etc.)

Get

Retrieve values from the server's key-value data storage.

Field	Type	Description
keys	list[str]	Keys to retrieve

Set

Set values in the server's key-value data storage.

Field	Type	Description
key	str	Storage key
default	int | float	Default value if the key doesn't exist yet
operations	list[DataStorageOperation]	Operations to apply (add, replace, etc.)
want_reply	bool	Whether to receive a SetReply confirmation

SetNotify

Subscribe to changes on specific data storage keys. You'll receive a SetReply whenever a subscribed key changes.

Field	Type	Description
keys	list[str]	Keys to watch for changes

UpdateHint

Update the status of an existing hint.

Field	Type	Default	Description
player	int	(required)	Player slot
location	int	(required)	Location ID
status	HintStatus | None	None	New hint status

GetDataPackage

Request game data packages containing item/location name mappings.

Field	Type	Description
games	list[str]	Games to get data for

Sync

Request a full state synchronization from the server. This packet has no fields.

---

Server packets (server -> client)

These packets are received from the server and dispatched to your callbacks.

RoomInfo

Server information, sent automatically when you first connect (before authentication).

Field	Type	Description
version	Version	Server version
generator_version	Version	Generator version used to create the multiworld
permissions	Permissions	What commands players are allowed to use
datapackage_checksums	dict[str, str]	Checksums for each game's data package (for caching)
tags	tuple[str, ...]	Server tags
games	tuple[str, ...]	Games present in the multiworld
seed_name	str	Unique seed identifier
time	datetime	Server time
hint_cost	int	Point cost to create a hint
location_check_points	int	Points earned per location check
password	bool	Whether the room requires a password

Connected

Sent when your authentication is successful. Contains your game session info.

Field	Type	Default	Description
team	int	(required)	Your team number
slot	int	(required)	Your slot number
hint_points	int	(required)	Your available hint points
slot_info	dict[int, NetworkSlot]	(required)	Info about all slots (use slot_info[slot].name to look up names)
players	tuple[NetworkPlayer, ...]	(required)	All players in the multiworld
missing_location	tuple[int, ...] | None	None	Locations you haven't checked yet
checked_location	tuple[int, ...] | None	None	Locations you've already checked
slot_data	dict[str, Any] | None	None	Game-specific data (only if you requested it in Connect)

ConnectionRefused

Sent when authentication fails.

Field	Type	Description
errors	tuple[ConnectionRefusedFlag, ...]	Reasons for refusal (e.g. invalid slot, wrong password)

ReceivedItems

Items that have been sent to you by other players (or yourself).

Field	Type	Description
items	tuple[NetworkItem, ...]	The items you received
index	int	Starting index for tracking which items you've processed

LocationInfo

Response to a LocationScouts request, telling you what items are at the scouted locations.

Field	Type	Description
locations	tuple[NetworkItem, ...]	Item data for each scouted location

RoomUpdate

A partial update to the room state. Only changed fields are included; everything else is None.

Field	Type	Default
version	Version | None	None
permissions	Permissions | None	None
tags	tuple[str, ...] | None	None
games	tuple[str, ...] | None	None
players	tuple[NetworkPlayer, ...] | None	None
checked_location	tuple[int, ...] | None	None
slot_info	dict[int, NetworkSlot] | None	None
hint_points	int | None	None
(and others)

PrintJSON

A formatted message from the server. This is used for chat messages, item send notifications, hints, and more.

Field	Type	Default	Description
data	list[JSONMessagePart]	(required)	The message broken into parts (each part has .text, .type, etc.)
type	PrintJSONType | None	None	What kind of message: CHAT, ITEM_SEND, HINT, JOIN, PART, etc.
item	NetworkItem | None	None	The item involved (for item-related messages)
receiving	int | None	None	Slot number of the player receiving an item
team	int | None	None	Team number
slot	int | None	None	Slot number of the player who triggered the message
tags	list[str] | None	None	Tags
message	str | None	None	Plain text version of the message
countdown	int | None	None	Countdown value (for countdown messages)
found	bool | None	None	Whether a hint location has been found

DataPackage

Game data containing mappings between item/location names and their numeric IDs.

Field	Type	Description
data	DataPackageData	Contains a games dict mapping game names to their data (item names, location names, checksums)

Bounced

A message relayed from another client via the server (response to someone else's Bounce packet).

Field	Type	Default	Description
slots	tuple[int, ...]	(required)	Slot IDs that sent the bounce
data	dict | list | None	None	The relayed payload
games	tuple[str, ...] | None	None	Games of the senders
tags	tuple[ClientTag | str, ...] | None	None	Tags of the senders

Retrieved

Response to a Get request, containing the requested key-value pairs.

Field	Type	Description
keys	dict[str, Any]	The key-value pairs you requested

SetReply

Response to a Set request, confirming the change.

Field	Type	Description
key	str	The storage key that was changed
value	int | float	The new value after the operation
original_value	int | float	The value before the operation
slot	int	The slot that made the change

InvalidPacket

Sent by the server when you send a malformed packet.

Field	Type	Default	Description
type	PacketProblemType	(required)	What kind of problem occurred
text	str	(required)	Human-readable error description
original_cmd	str | None	None	The command name that caused the error