Example: Simple Client

Example: Simple Client

This is the most basic example: connect to a server, log in, and print incoming messages.

View source on GitHub

What this example does

1. Creates a Client and overrides on_print_json to print chat messages
2. Connects to the server and sends a Connect packet to log in
3. Waits 5 seconds to receive messages, then disconnects

Code

import asyncio
from archipelagopy import Client, packets, structs, enums

async def on_print_json(packet: packets.PrintJSON):
    for msg in packet.data:
        if msg.text is not None:
            print(f">> {msg.text}")

async def main():
    client = Client(port=12345)
    # replace the default on_print_json callback with our own
    client.on_print_json = on_print_json

    # connect to the server
    await client.start()

    # send a connect packet to log in
    await client.send(
        packets.Connect(
            version=structs.Version(major=6, minor=0, build=0),
            tags=["AP"],
            name="Link", # slot name
            game="Ocarina of Time"
        )
    )

    # wait for a while to receive packets
    await asyncio.sleep(5)

    # stop the client
    await client.stop()

if __name__ == "__main__":
    asyncio.run(main())

Output

>> Link (Team #1) playing Ocarina of Time has joined. Client(6.0.0), ['AP'].
>> Now that you are connected, you can use !help to list commands to run via the server. If your client supports it, you may have additional local commands you can list with /help.

What's happening step by step

• asyncio.run(main()) starts the asyncio event loop and runs main(). All async code needs to run inside an event loop.
• Client(port=12345) creates a client configured to connect to archipelago.gg on port 12345 using an encrypted connection. See Client Configuration for all options.
• client.on_print_json = on_print_json replaces the default (empty) on_print_json callback with our function. When the server sends a PrintJSON packet (chat messages, status updates, etc.), our function will be called. Note that the replacement must be async def to match the original — see Callbacks for details.
• await client.start() opens the WebSocket connection to the server.
• await client.send(packets.Connect(...)) sends the authentication packet. The name must match a slot name in the Archipelago game, and game must match the game for that slot.
• await asyncio.sleep(5) keeps the program running for 5 seconds so we can receive and print messages.
• await client.stop() closes the connection and cleans up.

For a cleaner way to manage the client lifecycle, see the Advanced Client example which uses async with (a context manager) instead of manual start()/stop().