Getting Started

Prerequisites

To lower maintenance costs, Auraxium currently requires Python version 3.9 or higher. Support for older versions can be added/restored if there is demand, get in touch via the repository issues if your use case requires compatibility with these older versions.

Using the latest version of Python is generally recommended.

Installation

Auraxium can be installed from PyPI through pip:

Windows

python -m pip install --user --upgrade auraxium

Unix

python3 -m pip install --user --upgrade auraxium

You can also use the following commands to install the latest development build directly from the repository:

Windows

python -m pip install --user -e git+git://github.com/leonhard-s/auraxium.git#egg=auraxium

Unix

python3 -m pip install --user -e git+git://github.com/leonhard-s/auraxium.git#egg=auraxium

Note

When using pre-release versions of Auraxium as a dependency for your own packages, be sure to pin the exact version used in setup.py or requirements.txt.

The API for these versions should not be considered stable and could break your application with the next minor version upgrade.

Overview

Auraxium can interface with the Daybreak Game Company’s Census API in one of three ways. The first is the object model, which wraps the API’s REST interface and allows accessing and navigating between specific pieces of data like character names or weapon statistics.

The auraxium.event.EventClient subclass additionally supports the event streaming interface, used to react to in-game events like continent locks or player deaths in next to real-time via a WebSocket connection.

Finally, the internal URL generator used to navigate the object model can also be used on its own, allowing a high degree of customization for the queries used. This lower-level access allows for optimizations not possible through the regular object-based REST interface.

Object Model

All API interactions are performed through auraxium.Client or one of its subclasses. The class representations of in-game objects can be found in the auraxium.ps2 module.

To retrieve in-game object instances, use get(), for single items, or find() for lists.

Note

The auraxium.Ps2Object.get_by_* interface has been deprecated and is scheduled for removal in version 0.3. Please use the auraxium.Client methods instead.

For more information on the available classes and the attributes they expose, refer to the Object Model Reference.

Event Stream

The auraxium.event.EventClient subclass adds a trigger-action system allowing the user to trigger actions when certain in-game events occur:

client = auraxium.event.EventClient()

@client.trigger(auraxium.event.Death)
async def on_death(event):
    victim_id = event.character_id
    victim = await client.get_by_id(auraxium.ps2.Character, victim_id)
    print(f'Player {victim.name} has died')

For more information on the event streaming system, refer to the event streaming documentation.

URL Generator

The URL generator used for low-level access to the PlanetSide 2 API resides in the auraxium.census submodule.

Note that this module is targeted at advanced users or anyone familiar with the underlying Census API. An introduction into the module interface can be found here.

Service IDs

The PlanetSide 2 API requires all client applications to register and use a service ID for all of its requests. Service IDs are used to identify your application and troubleshoot quality of service issues.

You can apply for your own service ID here. The process is free and usually only takes an hour or two to complete.

In Auraxium, the service ID is specified via the service_id argument of the auraxium.Client instance.

For casual use and development, the default s:example service ID is also available, but it is limited to 10 requests per minute and IP address.