Introduction

This guide will go through installing berconpy and using it to connect to a server, send commands, and receive messages.

Requirements

The minimum Python version required is 3.10. No other external dependencies are required.

Installation

This library can be installed from PyPI using one of the following commands:

# Linux/macOS
python3 -m pip install berconpy

# Windows
py -m pip install berconpy

To install the development version of the library, you can download it from GitHub directly:

# Windows
py -m pip install git+https://github.com/thegamecracks/berconpy

Note

The above command requires Git to be installed.

Basic Usage

The primary class berconpy offers is the AsyncRCONClient, which provides an interface over the underlying protocol and allows you to register event listeners and send commands to the BattlEye RCON server.

Sending commands

Let’s start with an example of how to send a command:

import asyncio
import berconpy as rcon

IP_ADDR = "XXX.XXX.XXX.XXX"
PORT = 9999
PASSWORD = "ASCII_PASSWORD"

client = rcon.AsyncRCONClient()

async def main():
    async with client.connect(IP_ADDR, PORT, PASSWORD):
        response = await client.send_command("players")
        print(response)

asyncio.run(main())

Note

The RCON IP address, port, and password can be found in your server’s BEServer.cfg / BEServer_x64.cfg.

  1. client = rcon.AsyncRCONClient() creates the client instance. No arguments are necessary, but you can set up event listeners on the client before beginning any connection which will be demonstrated afterwards.

  2. async with client.connect(IP_ADDR, PORT, PASSWORD) attempts to connect and log into the RCON server. The context manager also keeps the connection alive until you exit it, or an error occurs.

  3. response = await client.send_command("players") requests the players currently connected to the server and returns a string.

send_command() provides a low-level method for sending commands. Certain commands are already available as methods, like fetch_players() and whisper(). The BattlEye documentation describes server-side commands that can be sent with send_command().

Event listeners

There are several events you can listen to handle messages sent by the server in real-time. Below is an example of displaying in-game messages from players:

import asyncio
import math
import berconpy as rcon

IP_ADDR = "XXX.XXX.XXX.XXX"
PORT = 9999
PASSWORD = "ASCII_PASSWORD"

client = rcon.AsyncRCONClient()

@client.dispatch.on_player_message
async def on_player_message(player: rcon.Player, channel: str, message: str):
    print(f"({channel}) {player.name}: {message}")

async def main():
    async with client.connect(IP_ADDR, PORT, PASSWORD):
        await asyncio.sleep(math.inf)  # Keep client alive indefinitely

asyncio.run(main())

The @client.dispatch.on_player_message decorator adds a function as a listener for that specific event when it is received from the server. All on_* methods provided by @client.dispatch have function signatures that allow your type checker to ensure that your listener is correctly typed. For a full list of events, see the EventDispatcher.

You might have also noticed in the listener that it receives a Player instance as its first argument. The client instance manages a cache of players which makes it easier to perform operations on different players like whispering and kicking. A list of players can be retrieved through the players property.

Configuring Logging

berconpy allows logging information about the protocol and the client during runtime with the built-in logging module. By default, no logging configuration is used. You can set up logging either by calling logging.basicConfig() (which configures the root logger) or by adding your own handlers to the berconpy logger.

The following table describes what messages are shown in each level of logging:

Level

Messages

CRITICAL

Unused

ERROR

Potentially fatal connection errors (e.g. incorrect password)

WARNING

Failed commands and consecutive reconnects

INFO

Connection attempts and timeouts

DEBUG

Events and packets transmitted/received

Example configurations

Log all messages to stderr:

import logging

logging.basicConfig(level=logging.DEBUG)

Log berconpy warnings to berconpy.log:

import logging

log = logging.getLogger("berconpy")
log.setLevel(logging.WARNING)
handler = logging.FileHandler("berconpy.log", "w")
handler.setFormatter(logging.Formatter("%(asctime)s:%(levelname)s:%(name)s: %(message)s"))
log.addHandler(handler)

Next Steps

This has covered the fundamentals of using berconpy. You can learn more about the available methods by checking the Async I/O API Reference, or if you’re interested in the technical details you can check the source code.