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.