PlanetSide 2 Object Reference

Player Characters

class auraxium.ps2.Character(data: auraxium.types.CensusData, client: auraxium.Client)

A player-controlled character running around the game.

id: int

The unique identifier of the player. In the API payload, this field is called character_id.

Note

IDs are only unique per platform. The same character ID could be reused between PC and PS4.

faction_id: int

ID of the Faction the character belongs to.

See also

Character.faction() – Retrieve the Faction the character belongs to.

head_id: int

The head model selected by the player. This includes the two genders as well as the four head types, giving a total of eight variants.

For human player models, head IDs 1 through 4 are the male variants, 5 through 8 are the female head shapes.

There are ~160 characters with a head ID of 0 (bad data?), and NSO characters appear to be limited to head IDs 1 through 4.

title_id: int

ID of the currently selected Title for this character. May be zero if the character has not selected any title.

See also

Character.title() – Retrieve the currently selected Title of the character.

Character.name_long() – Retrieve the display name of the character (i.e. including their Title, if any).

times: auraxium.models.CharacterData.Times

Login times and minutes played for the given character.

certs: auraxium.models.CharacterData.Certs

Current, past and total certification points for the character.

battle_rank: auraxium.models.CharacterData.BattleRank

The current battle rank of the character, and their progress until the next rankup.

profile_id: int

ID of the last Profile the character played as.

This value is only updated on logout, polling it is not not a reliable way of determining a player’s current class.

See also

Character.profile() – Retrieve the Profile the character last played as.

prestive_level: int

The prestige (or A.S.P.) rank for the character.

__init__(data: auraxium.types.CensusData, client: auraxium.Client) → None

Initialise the named object.

This sets the object’s id attribute and adds it to the cache.

Parameters:

• locale (str | None) – The locale under which to cache this object.

• args – Any extra positional arguments are forwarded to the Cached class’s initialiser.

• kwargs – Any keyword arguments are forwarded to the Cached class’s initialiser.

async achievements(**kwargs) → list[auraxium.models.CharacterAchievement]

Helper method for retrieving character achievements.

Any keyword arguments passed are forwarded to auraxium.census.Query.

Returns at most 5’000 results.

Warning

This method is part of a provisional API and may be removed or altered in upcoming versions.

async currency(**kwargs) → tuple[int, int]

Helper method for retrieving a character’s balance.

This returns a tuple of the number of Nanites and ASP tokens available to the player.

Other currencies are not exposed to the API as of the writing of this module.

async directive(results: int = 1, **kwargs) → list[auraxium.types.CensusData]

Helper method for retrieving character directive progress.

The payloads returned show if and when the character has completed the given Directive.

Any keyword arguments passed are forwarded to auraxium.census.Query.

Warning

This method is part of a provisional API and may be removed or altered in upcoming versions.

async directive_objective(results: int = 1, **kwargs) → list[auraxium.models.CharacterDirectiveObjective]

Helper method for retrieving directive progress.

The payloads returned show the progress towards a given directive.

Any keyword arguments passed are forwarded to auraxium.census.Query.

Warning

This method is part of a provisional API and may be removed or altered in upcoming versions.

async directive_tier(results: int = 1, **kwargs) → list[auraxium.models.CharacterDirectiveTier]

Helper method for retrieving directive tier progress.

The payloads returned show if and when the character has completed a given DirectiveTier.

Any keyword arguments passed are forwarded to auraxium.census.Query.

Warning

This method is part of a provisional API and may be removed or altered in upcoming versions.

async directive_tree(results: int = 1, **kwargs) → list[auraxium.models.CharacterDirectiveTree]

Helper method for retrieving directive tree progress.

The payloads returned show the current progress of the character along a DirectiveTree.

Any keyword arguments passed are forwarded to auraxium.census.Query.

Warning

This method is part of a provisional API and may be removed or altered in upcoming versions.

async events(**kwargs) → list[auraxium.types.CensusData]

Return and process past events for this character.

This provides a REST endpoint for past character events. This is always limited to at most 1000 return values. Use the begin and end parameters to poll more data.

Any keyword arguments passed are forwarded to auraxium.census.Query.

Warning

This method is part of a provisional API and may be removed or altered in upcoming versions.

async events_grouped(**kwargs) → list[auraxium.types.CensusData]

Helper method for retrieving deaths and kills by player.

Any keyword arguments passed are forwarded to auraxium.census.Query.

Warning

This method is part of a provisional API and may be removed or altered in upcoming versions.

faction() → auraxium.InstanceProxy[Faction]

Return the faction of the character.

This returns an auraxium.InstanceProxy.

async friends() → list[Character]

Return the friends list of the character.

classmethod get_by_name(name: str, *, locale: str = 'en', client: auraxium.Client) → Awaitable[Character | None]

Retrieve an object by its unique name.

This query is always case-insensitive.

Deprecated since version 0.2: Scheduled for removal in 0.4. Use auraxium.Client.get() instead.

async classmethod get_online(id_: int, *args: int, client: auraxium.Client) → list[Character]

Retrieve the characters that are online from a list.

items() → auraxium.SequenceProxy[Item]

Return the items available to the character.

This returns a auraxium.SequenceProxy.

async is_online() → bool

Return whether the given character is online.

async name_long(locale: str = 'en') → str

Return the full name of the player.

This includes an optional player title if the player has selected one.

async online_status() → int

Return the online status of the character.

This returns 0 if the character is offline, or the world_id of the server they are logged into.

outfit() → auraxium.InstanceProxy[Outfit]

Return the outfit of the character, if any.

This returns an auraxium.InstanceProxy.

outfit_member() → auraxium.InstanceProxy[OutfitMember]

Return the outfit member of the character, if any.

This returns an auraxium.InstanceProxy.

profile() → auraxium.InstanceProxy[Profile]

Return the last played profile of the character.

This returns an auraxium.InstanceProxy.

async skill(results: int = 1, **kwargs) → list[auraxium.types.CensusData]

Return skills unlocked by the player.

Any keyword arguments passed are forwarded to auraxium.census.Query.

Warning

This method is part of a provisional API and may be removed or altered in upcoming versions.

async stat(results: int = 1, **kwargs) → list[auraxium.types.CensusData]

Return global statistics for this character.

Any keyword arguments passed are forwarded to auraxium.census.Query.

Warning

This method is part of a provisional API and may be removed or altered in upcoming versions.

async stat_by_faction(results: int = 1, **kwargs) → list[auraxium.types.CensusData]

Return faction-specific statistics for this character.

Any keyword arguments passed are forwarded to auraxium.census.Query.

Warning

This method is part of a provisional API and may be removed or altered in upcoming versions.

async stat_history(results: int = 1, **kwargs) → list[auraxium.types.CensusData]

Return historical statistics for this character.

Any keyword arguments passed are forwarded to auraxium.census.Query.

Warning

This method is part of a provisional API and may be removed or altered in upcoming versions.

async weapon_stat(results: int = 1, **kwargs) → list[auraxium.types.CensusData]

Return weapon-specific statistics for this character.

Any keyword arguments passed are forwarded to auraxium.census.Query.

Warning

This method is part of a provisional API and may be removed or altered in upcoming versions.

async weapon_stat_by_faction(results: int = 1, **kwargs) → list[auraxium.types.CensusData]

Return per-faction weapon statistics for this character.

Any keyword arguments passed are forwarded to auraxium.census.Query.

Warning

This method is part of a provisional API and may be removed or altered in upcoming versions.

title() → auraxium.InstanceProxy[Title]

Return the current title of the character, if any.

This returns an auraxium.InstanceProxy.

world() → auraxium.InstanceProxy[World]

Return the world of the character.

This returns an auraxium.InstanceProxy.

class auraxium.ps2.Faction(*args, locale=None, **kwargs)

A faction in PS2.

This includes both playable factions, as well as the default Nanite Systems faction used for uncapturable territories and cross-faction items.

id: int

The unique ID of this faction. In the API payload, this field is called faction_id.

code_tag: str

The canonical tag representation of the faction (VS, TR, NC, or NSO).

name: auraxium.types.LocaleData

The localised name of the faction.

user_selectable: bool

Whether this faction is playable.

image_id: int | None

The image ID of the default image.

image_set_id: int | None

The corresponding image set.

image_path: str | None

The base path to the image with the default image_id.

tag() → str

Return the tag of this faction (VS, TR, NC, or NSO).

class auraxium.ps2.Title(*args, locale=None, **kwargs)

A title selectable by a character.

id: int

The identifier for this title. In the API payload, this field is called title_id.

name: auraxium.types.LocaleData

Per-locale names for this entity. Casting to string will use the English locale.

class auraxium.ps2.Currency(data, client)

A currency obtainable by characters.

Note

As of April 2021, the only currency available are Nanites. None of the new player resources (A-7, Merit, Campaign Standing etc.) are available.

The current A.S.P. token balance of a player can be retrieved through the auraxium.ps2.Character.currency() method.

id: int

The unique ID of this currency. In the API payload, this field is called currency_id.

name: auraxium.types.LocaleData

The localised name of this currency.

icon_id: int

The image ID of the currency icon image asset.

inventory_cap: int

The maximum amount of this currency a character may hold.

Outfits

class auraxium.ps2.Outfit(*args, locale=None, **kwargs)

A player-run outfit.

id: int

The unique ID of the outfit. In the API payload, this field is called outfit_id.

name_lower: str

Lowercase version of name. Useful for optimising case-insensitive lookups.

alias: str

The alias (or tag) of the outfit.

alias_lower: str

Lowercase version of alias. Useful for optimising case-insensitive lookups.

name: str

Name of the outfit. Not localised.

time_created: int

The creation date of the outfit as a UTC timestamp.

time_created_date: str

Human-readable version of time_created.

leader_character_id: int

The character/member ID of the outfit leader.

member_count: int

The number of members in the outfit.

tag() → str

Alias of alias.

classmethod get_by_name(name: str, *, locale: str = 'en', client: auraxium.Client) → Awaitable[Outfit | None]

Retrieve an outfit by its unique name.

This query is always case-insensitive.

Deprecated since version 0.2: Scheduled for removal in 0.4. Use auraxium.Client.get() instead.

classmethod get_by_tag(tag: str, client: auraxium.Client) → Awaitable[Outfit | None]

Return an outfit by its unique tag.

This query is always case-insensitive.

Deprecated since version 0.2: Scheduled for removal in 0.4. Use auraxium.Client.get() instead.

leader() → auraxium.InstanceProxy[OutfitMember]

Return the current leader of the outfit.

This returns an auraxium.InstanceProxy.

members() → auraxium.SequenceProxy[OutfitMember]

Return the members of the outfit.

This returns a auraxium.SequenceProxy.

async ranks() → List[auraxium.models.OutfitRankData]

Return the list of ranks for the outfit.

class auraxium.ps2.OutfitMember(data, client)

A member of an outfit.

This class can be treated as an extension of the Character class.

outfit_id: int

The ID of the outfit this member is a part of.

id: int

The ID of the associated character. In the API payload, this field is called character_id.

member_since: int

The date the character joined the outfit at as a UTC timestamp.

member_since_date: str

Human-readable version of member_since.

rank: str

The name of the member’s in-game outfit rank.

rank_ordinal: int

The ordinal position of the member’s rank within the outfit. The lower the value, the higher the rank.

character() → auraxium.InstanceProxy[Character]

Return the character associated with this member.

This returns an auraxium.InstanceProxy.

outfit() → auraxium.InstanceProxy[Outfit]

Return the character associated with this member.

This returns an auraxium.InstanceProxy.

Game World & Servers

class auraxium.ps2.Region(*args, locale=None, **kwargs)

A map region or facility.

region_id: int

The unique ID of the map region. In the API payload, this field is called region_id.

zone_id: int

The ID of the Zone containing this hex.

initial_faction_id: int

Unused.

name: auraxium.types.LocaleData

The localised name of the map region.

map_region() → auraxium.InstanceProxy[MapRegion]

Return the map region associated with this region.

This returns an auraxium.InstanceProxy.

zone() → auraxium.InstanceProxy[Zone]

Return the zone/continent of the region.

This returns an auraxium.InstanceProxy.

class auraxium.ps2.FacilityType(data, client)

A type of base/facility found in the game.

id: int

The unique ID of this facility type. In the API payload, this field is called facilty_type_id.

description: str

An internal description of this facility type.

class auraxium.ps2.World(*args, locale=None, **kwargs)

A world (or server) in the game.

id: int

The unique ID of the world. In the API payload, this field is called world_id.

name: auraxium.types.LocaleData

Localised name of the world.

state: str

The current state (i.e. online status) of the world.

description: auraxium.types.LocaleData | None

A description of the world’s server region.

async events(**kwargs: Any) → list[auraxium.types.CensusData]

Return events for this world.

This provides a REST endpoint for past alerts (MetagameEvent) and facility captures (FacilityCapture).

This is always limited to at most 1000 return values. Use the begin and end parameters to poll more data.

classmethod get_by_name(name: str, *, locale: str = 'en', client: auraxium.Client) → Awaitable[World | None]

Retrieve a world by name.

This query is always case-insensitive.

Deprecated since version 0.2: Scheduled for removal in 0.4. Use auraxium.Client.get() instead.

async map(zone: int | Zone, *args: int | Zone) → list[auraxium.types.CensusData]

Return the map status of a given zone.

async status() → tuple[str, datetime.datetime]

Return the online status for the world.

This returns a tuple consisting of the reported server state (e.g. “locked”, “low”, or “high”, the latter referring to population numbers), and the last time this value was updated.

class auraxium.ps2.Zone(*args, locale=None, **kwargs)

A continent or dynamic zone in the game world.

Note that some dynamic zones are not resolvable via this object. Dynamic zones include Sanctuary, the tutorial zones, and the outfit wars desolation maps.

id: int

The unique ID of this zone. In the API payload, this field is called zone_id.

code: str

The internal code used to represent this zone.

hex_size: int

The map size for this zone.

description: auraxium.types.LocaleData

The localised name of this zone.

name: auraxium.types.LocaleData

Localised name of the zone.

is_dynamic() → bool

Return whether the given zone is dynamic or not.

Dynamic zones are spun up for individual players as needed, such as the tutorial or Sanctuary.

Classes & Vehicles

class auraxium.ps2.Loadout(data, client)

Represents a faction-specific infantry class.

id: int

The unique ID of this loadout. In the API payload, this field is called loadout_id.

profile_id: int

The ID of the associated Profile.

See also

profile() – Get the profile associated with this loadout.

faction_id: int

The Faction for this loadout.

See also

faction() – Get the faction associated with this loadout.

code_name: str

A string describing the loadout for introspection purposes.

armour_info() → auraxium.SequenceProxy[ArmourInfo]

Return the armour info of the loadout.

This returns a auraxium.SequenceProxy.

faction() → auraxium.InstanceProxy[Faction]

Return the faction of the loadout.

This returns an auraxium.InstanceProxy.

profile() → auraxium.InstanceProxy[Profile]

Return the profile of the loadout.

This returns an auraxium.InstanceProxy.

resist_info() → auraxium.SequenceProxy[ResistInfo]

Return the resist info of the loadout.

This returns a auraxium.SequenceProxy.

class auraxium.ps2.Profile(data, client)

An entity in the game world.

This is used to specify the resistance and armour values to apply to a given object.

Profiles include faction-specific classes, vehicles, facility infrastructure such as turrets, generators or shields, as well as other non-static entities such as Cortium nodes or pumpkins.

id: int

The unique ID of this profile. In the API payload, this field is called profile_id.

description: str

The description of the profile.

armour_info() → auraxium.SequenceProxy[ArmourInfo]

Return the armour info of the profile.

This returns a auraxium.SequenceProxy.

resist_info() → auraxium.SequenceProxy[ResistInfo]

Return the resist info of the profile.

This returns a auraxium.SequenceProxy.

class auraxium.ps2.Vehicle(*args, locale=None, **kwargs)

A mountable vehicle in PlanetSide 2.

This includes aircraft and ground vehicles, as well as mountable turrets and constructible.

id: int

The unique ID of this vehicle type. In the API payload, this field is called vehicle_id.

description: auraxium.types.LocaleData | None

The localised description of the vehicle type.

name: auraxium.types.LocaleData

Localised name of the vehicle.

type_id: int

The type of vehicle.

type_name: str

The name of the type of vehicle.

cost: int | None

The spawn cost of the vehicle.

cost_resource_id: int | None

The ID of the resource the vehicle costs.

image_id: int | None

The image ID of the default image.

image_set_id: int | None

The corresponding image set.

image_path: str | None

The base path to the image with the default image_id.

factions() → auraxium.SequenceProxy[Faction]

Return the factions that have access to this vehicle.

This returns a auraxium.SequenceProxy.

async classmethod get_by_faction(faction: Faction | int, *, client: auraxium.Client) → list[Vehicle]

Return all vehicles available to the given faction.

skill_sets(faction: Faction | int | None) → auraxium.SequenceProxy[SkillSet]

Return the skill sets associated with this vehicle.

By default, this will list all skill sets for all empires. Note that this may result in duplicate results as some skill sets exist for all empires. To avoid duplicates, either generate a set from the returned proxy, or specify the faction to resolve skill sets for.

This returns a auraxium.SequenceProxy.

class auraxium.ps2.VehicleAttachment(data, client)

Links vehicles to the items and attachments they support.

id: int

The item that is being attached. In the API payload, this field is called vehicle_attachment_id.

vehicle_id: int

The ID of the Vehicle the item may be attached to.

See also

vehicle() – The vehicle the item may be attached to.

faction_id: int

The ID of the Faction for which this attachment is available.

See also

faction() – The faction the attachment is availabl to.

description: str

A description of the attachment.

slot_id: int

The slot the attachment goes into.

faction() → auraxium.InstanceProxy[Faction]

Return the faction this attachment is available to.

This returns an auraxium.InstanceProxy.

item() → auraxium.InstanceProxy[Item]

Return the attachable item for the vehicle.

This returns an auraxium.InstanceProxy.

vehicle() → auraxium.InstanceProxy[Vehicle]

Return the vehicle the item may be attached to.

This returns an auraxium.InstanceProxy.

Firing Mechanics

class auraxium.ps2.FireGroup(data, client)

A fire group of a weapon.

Fire groups are comparable to the in-game fire modes, such as fixed burst, semi auto or fully automatic. They are also used to implement auxiliary fire modes such as under-barrel launchers.

id: int

The unique ID of this fire group. In the API payload, this field is called fire_group_id.

chamber_duration_ms: int | None

The amount of time required to rechamber after firing. This is used for pump action shotguns and bolt action sniper rifles and must be added to their respective refire time for fire rate calculation.

transition_duration_ms: int | None

The time required to transition to this fire group. This defines the delay between equipping an underbarrel shotgun and being able to fire it.

spool_up_ms: int | None

The duration of the spool-up period for this fire group.

spool_up_initial_refire_ms: int | None

The initial fire speed (rounds per minute) of the fire group. The weapon starts out at this value when firing, then tapers to the regular value after spool_up_ms milliseconds.

can_chamber_ironsights: bool | None

Whether a bolt-action weapon can be rechambered while in ADS.

fire_modes() → auraxium.SequenceProxy[FireMode]

Return the fire modes in the fire group.

class auraxium.ps2.FireMode(data, client)

A fire mode of a weapon.

An API fire mode defines the bulk of a weapon’s stats, such as reload times, default accuracy and cone-of-fire characteristics.

Note

Do not confuse this with in-game fire modes (automatic, triple burst, etc.). Those are represented by the FireGroup class instead.

Most infantry weapons have two fire modes, one for being hipfired and another used when aiming down sights. For more information on fire mode types, see the FireModeType class.

Keep in mind that most accuracy-related stats can be overwritten by the current PlayerState, i.e. whether the player is jumping, crouching, etc.

See the state_groups() method for a mapping of player states to the state group entries for this fire mode.

id: int

The unique ID of this fire mode. In the API payload, this field is called fire_mode_id.

fire_mode_type_id: int | None

The ID of the FireModeType of the fire mode.

See also

type() – The type of this fire mode.

ability_id: int | None

The item ability ID to trigger when the weapon is fired. Only valid for fire modes of type TRIGGER_ITEM_ABILITY.

ammo_slot: int | None

The index of the ammo slot used by this fire mode. This field is used to select the ammo reservoir to use for this fire mode.

automatic: bool

Whether the fire mode is fully automatic or not.

grief_immune: bool | None

Whether friendly fire is disabled for this fire mode.

iron_sights: bool | None

Whether this fire mode is using iron sights. This is generally true is fire_mode_type_id is set to IRON_SIGHTS.

laser_guided: bool | None

Whether this weapon is laser guided (such as the Hornet Missles on empire-specific fighter aircraft).

move_modifier: float

The movement speed modifier applied while in this fire mode. Higher values provide increased mobility, particularly while aiming down sights.

projectile_speed_override: int | None

A fire mode specific override used to override the default Projectile ‘s speed for this fire mode.

It is recommended to use this value over the projectile’s if available.

sprint_fire: bool | None

Whether the fire mode allows firing and sprinting. This is generally only true for quick knife fire modes.

turn_modifier: float

A turn speed modifier applied while in this fire mode.

This is how MAXes turn speed is limited; all MAX weapons use a 0.75 turn rate modifier.

use_in_water: bool | None

Whether the weapon can be used in water.

This is true for knives and false for all other weapons. Since most bodies of water instantly kill players touching them, this value has no real effect.

zoom_default: float

The default zoom level of the fire mode (i.e. without any scopes attached).

cof_override: float | None

Unused.

cof_pellet_spread: float | None

The pellet spread used for multi-projectile weapons (such as non-slug shotguns or the NSX Tengu).

cof_range: float

Potentially unused? More testing needed.

cof_recoil: float | None

Cone of fire bloom per shot fired in degrees.

cof_scalar: float

The starting cone of fire scalar. This mainly exists so it can be modified by attachments like laser sights.

Note

The VS’s Spiker is the only item with a base cof scalar of 0.5. All other items use 1.0.

cof_scalar_moving: float

The starting cone-of-fire scalar while moving. This exists so it can be modified by attachments. Always 1.0.

player_state_group_id: int

The ID of the PlayerStateGroup for this fire mode. State groups are used to modify weapon accuracy depending on the current PlayerState, i.e. whether the player is standing, crouching, etc.

damage_direct_effect_id: int | None

The damage Effect created on direct hits.

damage_head_multiplier: float | None

The headshot multiplier for the fire mode.

damage_indirect_effect_id: int | None

The damage Effect created on indirect hits.

damage_legs_multiplier: float | None

The leg shot multiplier for the fire mode.

fire_ammo_per_shot: int | None

The amount of ammo consumed per shot. Some weapons, like the VS Lancer, may consume more than 1 bullet per shot.

fire_auto_fire_ms: int | None

The weapon’s refire rate in fixed burst fire modes, such as the NSX Yumi’s five shot burst.

fire_burst_count: int | None

The burst size of fixed burst fire modes.

fire_charge_up_ms: int | None

The maximum amount of time the weapon can be charged before firing automatically. Used in the VS’s Lancer rocket launcher.

fire_delay_ms: int | None

The delay between pulling the trigger and the weapon actually firing. Used in the NXS Yumi.

fire_detect_range: float | None

The base minimap detection range when firing this weapon. Can be modified by silencers or other barrel attachments.

fire_duration_ms: int | None

The firing duration of a weapon. Used for the MELEE and THROWN FireModeType ‘s to sync the damage/throwable release with the player model’s animation.

fire_refire_ms: int | None

The amount of time between shots.

For automatic weapons, this is directly related to the rate of fire::

rounds-per-minute = 60'000 / refire_time_ms

rate-of-fire      = 1'000 / refire_time_ms

fire_pellets_per_shot: int | None

The number of pellets fired by non-slug shotguns or the NSX Tengu per shot.

heat_per_shot: int | None

The amount of heat generated per shot.

heat_recovery_delay_ms: int | None

The duration after which weapon heat will start to dissipate.

heat_threshold: int | None

The overheating threshold of the weapon. This is comparable to the magazine size for heat-based weapons, with the number of shots available without overheating being equal to the floor of heat_threshold divided heat_per_shot::

heat-magazine-size = heat_threshold // heat_per_shot + 1

lockon_acquire_close_ms: int | None

The time required to establish a lock at the launcher’s minimum lock-on distance.

This value is used for fire modes whose acquire time depends on the distance from the target.

See also

lockon_acquire_ms – Lock-on acquire time for fire modes with constant acquire times.

lockon_acquire_far_ms: int | None

The time required to establish a lock at the launcher’s maximum lock-on distance.

This value is used for fire modes whose acquire time depends on the distance from the target.

See also

lockon_acquire_ms – Lock-on acquire time for fire modes with constant acquire times.

lockon_acquire_ms: int | None

The time required to establish a lock at the target.

This value is used for fire modes whose acquire time does not change with distance from the target.

See also

lockon_acquire_close_ms – Minimum acquire time for fire modes whose acquire time depends on the distance from the target.

lockon_acquire_far_ms – Maximum acquire time for fire modes whose acquire time depends on the distance from the target.

lockon_angle: float | None

The maximum error allowed while locking on. As long as the target is within this cone, lock-on acquisition will continue.

lockon_lose_ms: int | None

The amount of time over which an establish lock will be lost. Re-acquiring a lock within this time will not reset the lock-on acquisition timer.

lockon_maintain: bool | None

Whether a lock must be maintained until impact (like for A2A lock-ons) or whether the projetile will continue tracking its target on its own (as for most infantry launchers).

lockon_radius: float | None

Not used as of June 2020, use lockon_range instead.

lockon_range: float | None

The maximum range at which a lock can be maintained. If the target moves beyond this range, an existing lock is lost.

lockon_range_close: float | None

The minimum lock-on distance. Used for launchers whose lock-on acquisition time depends on distance from the target.

See also

lockon_acquire_close_ms – The time required to establish a lock at minimum lock-on distance.

lockon_range_far: float | None

The maximum lock-on distance. Used for launchers whose lock-on acquisition time depends on distance from the target.

See also

lockon_acquire_far_ms – The time required to establish a lock at maximum lock-on distance.

lockon_required: bool | None

Whether this weapon can be fired without being locked on (true for the NS Annihilator, false for most faction-specific lock-on launchers).

recoil_angle_max: float | None

The maximum recoil angle, used to randomise recoil angle.

After every shot, the weapon will kick in a random direction between recoil_angle_min and this value.

recoil_angle_min: float | None

The minimum recoil angle, used to randomise recoil angle.

After every shot, the weapon will kick in a random direction between this value and recoil_angle_max.

recoil_first_shot_modifier: float | None

A recoil multiplier override for the first shot fired in automatic mode. When single-shot bursting, this override is applied to every shot.

For fixed-size bursts (e.g. triple burst fire modes), this will only be applied to the first shot of every burst.

recoil_horizontal_max: float | None

The maximum horizontal recoil per shot. After every shot, the weapon will kick up by a random angle between recoil_horizontal_min and this value.

recoil_horizontal_max_increase: float | None

Some weapons’ recoil increases or decreases with consecutive shots. This value denotes by how much the maximum horizontal recoil will change with each shot fired.

recoil_horizontal_min: float | None

The maximum horizontal recoil per shot. After every shot, the weapon will kick up by a random angle between this value and recoil_horizontal_max.

recoil_horizontal_min_increase: float | None

Some weapons’ recoil increases or decreases with consecutive shots. This value denotes by how much the minimum horizontal recoil will change with each shot fired.

recoil_horizontal_tolerance: float | None

The maximum horizontal deviation of the recoil from the initial aiming position before it must kick back towards the other direction.

recoil_increase: float | None

Some weapons’ recoil increases or decreases with consecutive shots. This value denotes by how much the vertical recoil will change with each shot fired.

For negative values, the maximum recoil will go down until it meets the minimum, for positive values the minimum recoil will climb until it equals the maximum recoil.

The base vertical recoil while standing.

recoil_increase_crouched: float | None

Same as recoil_increase but only affects the crouched PlayerState.

recoil_magnitude_max: float | None

The maximum vertical recoil per shot. After every shot, the weapon will kick up by a random angle between recoil_magnitude_min and this value.

recoil_magnitude_min: float | None

The minimum vertical recoil per shot. After every shot, the weapon will kick up by a random angle between this value and recoil_magnitude_max.

recoil_max_total_magnitude: float | None

The total maximum recoil, including both the horizontal and vertical component.

recoil_recovery_acceleration: int | None

The acceleration at which the recoil recovery will reach its full recovery rate. Lower values lead to a more progressive recovery rate, where the initial recoil recovery window is less effective than they would be with a linear recovery rate.

Note

No conclusive tests regarding this field yet.

recoil_recovery_delay_ms: int | None

The delay in milliseconds before the weapon will start to reset to its default cone of fire after the player stopped firing.

recoil_recovery_rate: int | None

The speed at which the weapon will reset to its original cone of fire after the player stopped firing.

recoil_shots_at_min_magnitude: int | None

The number of shots before which the recoil penalties will take effect. This is 0 or 1 for most weapons, some vehicle weapons like the G40-F Ranger get 3 or more high accuracy shots before recoil penalties starts taking effect.

reload_block_auto: bool | None

Untested: this value seems to correlate with a weapon’s ability to reload while aiming down sights.

reload_continuous: bool | None

Whether the weapon uses a continuous reload system where shots are reloaded bullet by bullet (as pump action shotguns do).

reload_ammo_fill_ms: int | None

The delay between ammo pack refill ticks.

reload_chamber_ms: int | None

The per-chamber reload time for weapons that are reloaded sequentially (such as pump action shotguns).

reload_loop_start_ms: int | None

The initial loop time for reloading with looped reload weapons (such as pump action shotguns).

Used to sync up the reload with the character model’s animation.

reload_loop_end_ms: int | None

The final delay after reloading a looped reload weapon is completed.

Used to sync up the reload with the character model’s animation.

reload_time_ms: int | None

The reload time of the weapon.

sway_amplitude_x: float | None

Sway amplitude in X direction.

sway_amplitude_y: float | None

Sway amplitude in Y direction.

sway_can_steady: bool | None

Whether the player can hold their breath to stop camera sway.

sway_period_x: int | None

Sway period in X direction in milliseconds.

sway_period_y: int | None

Sway period in Y direction in milliseconds.

armor_penetration: float | None

Unused as of June 2020.

max_damage: int | None

Maximum direct damage of the weapon.

For constant damage effects or damage fall off effects (effect type ID 36 or 45), this field is a direct link to the direct damage Effect ‘s param1 field.

As of April 2021, this link is confirmed to be without errors for all fire modes that have a direct damage effect.

max_damage_ind: int | None

Maximum indirect damage of the weapon.

For indirect damage effects (effect type ID 40), this field is a direct link to the direct damage Effect ‘s param1 field.

As of April 2021, this link is confirmed to be without errors for all fire modes that have a direct damage effect.

max_damage_ind_radius: float | None

The radius over which maximum indirect damage of the weapon will be applied (aka. “inner splash”).

For indirect damage effects (effect type ID 40), this field is a direct link to the direct damage Effect ‘s param2 field.

As of April 2021, this link is confirmed to be without errors for all fire modes that have a direct damage effect.

max_damage_range: float | None

The range up to which the weapon will deal its maximum direct damage.

For damage fall off effects (effect type ID 45), this field is a direct link to the direct damage Effect ‘s param2 field.

As of April 2021, this link is confirmed to be without errors for all fire modes that have a direct damage effect.

min_damage: int | None

The minimum direct damage of the weapon.

For damage fall off effects (effect type ID 45), this field is a direct link to the direct damage Effect ‘s param3 field.

As of April 2021, this link is confirmed to be without errors for all fire modes that have a direct damage effect.

min_damage_ind: int | None

Minimum indirect damage of the weapon.

For indirect damage effects (effect type ID 40), this field is a direct link to the direct damage Effect ‘s param3 field.

min_damage_ind_radius: float | None

The outer limit of the splash radius. Beyond this distance, no damage will be dealt.

For indirect damage effects (effect type ID 40), this field is a direct link to the direct damage Effect ‘s param5 field.

As of April 2021, this link is confirmed to be without errors for all fire modes that have a direct damage effect.

min_damage_range: float | None

The range at which the weapon deals its minimum damage.

For damage fall off effects (effect type ID 45), this field is a direct link to the direct damage Effect ‘s param5 field.

As of April 2021, this link is confirmed to be without errors for all fire modes that have a direct damage effect.

shield_bypass_pct: int | None

The percentage of damage that will bypass shields and always affect the raw health pool.

As of April 2021, this field is set to 130 for the default faction-speficic launchers, but no such mechanic is observed in-game.

description: auraxium.types.LocaleData | None

Localised description of the fire mode (e.g. “Automatic”).

type() → FireModeType

Return the type of fire mode as an enum.

async state_groups() → dict[PlayerState, auraxium.models.PlayerStateGroup]

Return the state-specific data for a fire mode.

projectile() → auraxium.InstanceProxy[Projectile]

Return the projectile associated with this fire mode.

class auraxium.ps2.FireModeType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Specifies the type of action taken when a weapon is fired.

The default fire mode type, PROJECTILE, is used for hipfired or otherwise unaimed weapons. IRON_SIGHT is used when aiming down sights (ADS).

MELEE is used for both quick knifing and equipped knives. THROWN is responsible for grenades and mines, and TRIGGER_ITEM_ABILITY is a hook used to place turrets and other constructable items.

Values::

PROJECTILE           =  0  # Hipfire
IRON_SIGHT           =  1  # Aim down sights
MELEE                =  3
TRIGGER_ITEM_ABILITY =  8
THROWN               = 12

class auraxium.ps2.Projectile(data, client)

A projectile fired by a fire mode.

id: int

The unique ID of this projectile. In the API payload, this field is called projectile_id.

projectile_flight_type_id: int

The ID of the projectile’s ProjectileFlightType.

See also

flight_type() – The enum value of the projectile’s flight type.

speed: int

The projectile speed in meters per second.

Note

A FireMode can override this value via its projectile_speed_override field.

It is therefore recommended to use that field instead, if available.

speed_max: int | None

The maximum speed of the projectile; used with acceleration.

acceleration: int | None

The acceleration of the projectile in meters per second per second.

turn_rate: int | None

The turn rate of the projectile in degrees per second.

lifespan: int | float

The time after which the projectile will be destroyed if it ha not hit a target. Effectively limits the maximum distance travelled.

drag: float | None

The atmospheric drag applied to the projectile.

gravity: float | None

The affect on gravity on the projectile.

lockon_acceleration: float | None

Not yet documented.

lockon_lifespan: float | None

The life span of the projectile after it has locked onto a target.

arm_distance: float | None

The minimum distance travelled for the projectile to be armed. Used to increase the Archer’s damage on range.

tether_distance: float | None

Not yet documented.

detonate_distance: float | None

The travelled distance after which the projectile will detonate.

detonate_on_contact: bool | None

Whether the projectile will explode when hitting a target. False for grenades and other bouncing projectiles.

sticky: bool | None

Whether the projectile will stick to objects.

sticks_to_players: bool | None

Whether the projectile will stick to players.

lockon_lose_angle: int | None

The angle at which the projectile will lose its lock if the target’s turn speed exceeds its own.

lockon_seek_in_flight: bool | None

Whether the projectile will continue to follow its target after launch.

flight_type() → ProjectileFlightType

Return the flight type of the projectile.

class auraxium.ps2.ProjectileFlightType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

A projectile flight type. structable items.

Values::

BALLISTIC = 1
TRUE_BALLISTIC = 3
DYNAMIC = 9
PROXIMITY_DETONATE = 10

class auraxium.ps2.PlayerState(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

A player state.

These are used to apply the situational weapon stats depending on the player state, e.g. running, springing, crouching, etc.

Values::

STANDING         = 0
CROUCHING        = 1
STANDING_MOVING  = 2
SPRINTING        = 3
FALLING_LONG     = 4
CROUCHING_MOVING = 5

Metagame & Alerts

class auraxium.ps2.MetagameEvent(data, client)

An event or alert on a continent.

id: int

The unique ID of this event. In the API payload, this field is called metagame_event_id.

name: auraxium.types.LocaleData

The localised name of the event.

description: auraxium.types.LocaleData

The localised description of the event.

type: int

The type of event. Legacy alerts like “Dome Domination” used to share the same type despite being different events due to taking place on different continents.

experience_bonus: float | None

The experience bonus applied to participating players in percent.

class auraxium.ps2.MetagameEventState(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

The state of a auraxium.ps2.MetagameEvent.

The following event state changes are currently recognised::

STARTED          = 135
RESTARTED        = 136
CANCELLED        = 137
ENDED            = 138
XP_BONUS_CHANGED = 139

Items & Weapons

class auraxium.ps2.Item(*args, locale=None, **kwargs)

An item that may be owned by a character.

This includes the item component of weapons, which is extended by weapon specific data in the associated auraxium.ps2.Weapon instance.

id: int

The unique ID of this item. In the API payload, this field is called item_id.

item_type_id: int | None

The ID of the ItemType for this item.

See also

type() – Retrieve the type of this item.

item_category_id: int | None

The ID of the ItemCategory for this item.

See also

category() – Retrieve the category of this item.

activatable_ability_id: int | None

(Not yet documented)

passive_ability_id: int | None

(Not yet documented)

is_vehicle_weapon: bool

Whether this item is a vehicle weapon.

description: auraxium.types.LocaleData | None

Localised description of the item.

faction_id: int | None

The Faction that has access to this item.

max_stack_size: int

The stack size for stackable items such as grenades.

name: auraxium.types.LocaleData

Localised name of the item.

skill_set_id: int | None

The SkillSet associated with this item. This is used for upgradable items like the Medical Applicator or Repair Tool.

is_default_attachment: bool

Default attachments are generally not visible to the user and are used whenever nothing is selected. Examples include the default iron sights, or the regular ammo type for weapon supporting non-standard ammo types.

image_id: int | None

The image ID of the default image.

image_set_id: int | None

The corresponding image set.

image_path: str | None

The base path to the image with the default image_id.

attachments() → auraxium.SequenceProxy[Item]

Return the attachment options for this item.

This returns a auraxium.SequenceProxy.

category() → auraxium.InstanceProxy[ItemCategory]

Return the category of the item.

This returns an auraxium.InstanceProxy.

faction() → auraxium.InstanceProxy[Faction]

Return the faction that has access to this item.

This returns an auraxium.InstanceProxy.

async datasheet() → auraxium.models.WeaponDatasheet

Return the datasheet for the weapon.

profiles() → auraxium.SequenceProxy[Profile]

Return the profiles the item is available to.

This returns a auraxium.SequenceProxy.

type() → auraxium.InstanceProxy[ItemType]

Return the type of item.

This returns an auraxium.InstanceProxy.

weapon() → auraxium.InstanceProxy[Weapon]

Return the weapon associated with this item, if any.

This returns an auraxium.InstanceProxy.

class auraxium.ps2.ItemCategory(*args, locale=None, **kwargs)

A category of item.

This represents the item filter views used in the in-game depot, such as “Infantry Gear”, “Weapon Camo” or “Vehicle Weapons”.

id: int

The unique ID of this item category. In the API payload, this field is called item_category_id.

name: auraxium.types.LocaleData

Localised name of the item category.

class auraxium.ps2.ItemType(data, client)

A type of item.

Item types are a coarser classification used internally. They are used to differentiate between tangible items like weapons or consumables, cosmetics, implants, as well as abstract item-like utilities like loadout slots, server transfers, or name change tokens.

id: int

The unique ID of this item type. In the API payload, this field is called item_type_id.

name: str

The internal identifying name of this item type.

code: str

The internal code used to describe this item type.

class auraxium.ps2.Weapon(data, client)

A weapon available to a player.

This can be treated as an extension to the auraxium.ps2.Item class.

id: int

The unique ID of this weapon. In the API payload, this field is called weapon_id.

weapon_group_id: int | None

Used to group upgradable weapons together and track them as a single entity, such as the Infiltrator’s Recon Dart Device or the Engineer’s Repair Tool.

turn_modifier: float

Turn rate modifier to apply while the weapon is equipped. This is used to control turret turn rates for tanks and construction items.

move_modifier: float

Unused.

sprint_recovery_ms: int | None

Recovery time to allow firing or ADS after the player stopped sprinting.

equip_ms: int | None

The weapon equip time in milliseconds.

unequip_ms: int | None

The weapon unequip time in milliseconds.

to_iron_sights_ms: int | None

The ADS enter time in milliseconds.

from_iron_sights_ms: int | None

The ADS exit time in milliseconds.

heat_capacity: int | None

The heat capacity of the weapon. Generally identical to heat_threshold, but this only uses the first fire mode of the weapon.

heat_bleed_off_rate: float | None

The rate at which the weapon will cool down after firing stops.

heat_overheat_penalty_ms: int | None

The overheat read decay penalty imposed if the user overheats the weapon in seconds.

melee_detect_width: float | None

The hitbox width for melee weapons.

melee_detect_height: float | None

The hitbox height for melee weapons.

is_heat_weapon() → bool

Guess whether this weapon is using a heat mechanic.

This checks for presence and non-zero value for the “heat_mechanic” stat.

async ammo_slots() → list[auraxium.models.WeaponAmmoSlot]

Return the ammo slots for the weapon.

attachments() → auraxium.SequenceProxy[Item]

Return the attachments available for this weapon.

This returns a auraxium.SequenceProxy.

async datasheet() → auraxium.models.WeaponDatasheet

Return the datasheet for the weapon.

fire_groups() → auraxium.SequenceProxy[FireGroup]

Return the fire groups for this weapon.

This returns a auraxium.SequenceProxy.

classmethod get_by_name(name: str, *, locale: str = 'en', client: auraxium.Client) → Awaitable[Weapon | None]

Retrieve a weapon by name.

This is a helper method provided as weapons themselves do not have a name. This looks up an item by name, then returns the weapon associated with this item.

Returns:

The weapon associated with the given item, or None

Deprecated since version 0.2: Scheduled for removal in 0.4. Use auraxium.Client.get() instead.

item() → auraxium.InstanceProxy[Item]

Return the item associated with this weapon.

Map Screen

class auraxium.ps2.MapHex(data, client)

An individual territory hex in the map.

Note that the x and y coordintes are not using a regular Cartesian coordinate system. Rather, they are using a hexagonal coordinate system, with all hexes being positioned via integer coordinates.

An introduction on hexagonal coordinate systems can be found in this article: https://www.redblobgames.com/grids/hexagons/#coordinates-axial

Note

The coordinate system in PlanetSide 2 has its second axis go from bottom left to top right, unlike the article above. All of the principles and transformations still apply.

Refer to the following link for a usage example of this type, including converting from the hexgonal coordinate system to the Cartesian coordinates used on the map screen.

The module’s purpose is to generate serialised SVGs containing merged base outlines for a given continent: https://github.com/auto-pl/apl-api/blob/main/tools/map_hex_generator.py

zone_id: int

The ID of the Zone containing this hex.

map_region_id: int

The ID of the MapRegion associated with this hex.

x: int

The X map position of the hex.

y: int

The Y map position of the hex.

hex_type: int

The type of map hex. Refer to type_name for details.

type_name: str

The name of the hex’s type.

map_region() → auraxium.InstanceProxy[MapRegion]

Return the map region associated with this map hex.

class auraxium.ps2.MapRegion(data, client)

A facility on the continent map.

id: int

The unique ID of this map region. In the API payload, this field is called map_region_id.

zone_id: int

The ID of the Zone containing this hex.

facility_id: int | None

The ID of the associated facility.

Note

Facilities are not available as an API datatype, but are referenced by facility capture events.

Use the get_by_facility_id() method to look up a map region by its associated facility ID.

facility_name: str

The display name of the associated facility.

facility_type_id: int | None

The ID of the FacilityType of the map region.

facility_type: str | None

The type name of the associated facility.

location_x: float | None

The X world position of the facility.

The coordinate system used goes from -4096 to +4096 for normal continents, with the origin in the centre of the continent.

The map X axis points North (i.e. up on the map screen).

location_y: float | None

The Y world position of the facility.

The map Y axis points upwards from the map plane and represents the elevation of the base marker in the first person UI.

location_z: float | None

The Z world position of the facility.

The coordinate system used goes from -4096 to +4096 for normal continents, with the origin in the centre of the continent.

The map Z axis points East (i.e. right on the map screen).

reward_amount: int | None

Unused.

reward_currency_id: int | None

Unused.

classmethod get_by_facility_id(facility_id: int, client: auraxium.Client) → MapRegion

Return a map region by its facility ID.

This returns an auraxium.InstanceProxy.

async get_connected() → set[MapRegion]

Return the facilities connected to this region.

zone() → auraxium.InstanceProxy[Zone]

Return the zone/continent of the region.

This returns an auraxium.InstanceProxy.

Certifications & A.S.P. Skills

class auraxium.ps2.Skill(*args, locale=None, **kwargs)

A skill or certification unlockable by a character.

id: int

The unique ID of this skill. In the API payload, this field is called skill_id.

name: auraxium.types.LocaleData

Localised name of the skill.

skill_line_id: int

The ID of the associated SkillLine.

See also

skill_line() – The skill line containing this skill.

skill_line_index: int

The position of the skill in its skill line.

skill_points: int

The unlock cost of the skill.

grant_item_id: int | None

The Item granted by this skill, if any.

See also

grant_item() – The item granted by this skill.

description: auraxium.types.LocaleData | None

The localised description for this skill.

image_id: int | None

The image ID of the default image.

image_set_id: int | None

The corresponding image set.

image_path: str | None

The base path to the image with the default image_id.

grant_item() → auraxium.InstanceProxy[Item]

Return the item unlocked by this skill.

This returns an auraxium.InstanceProxy.

skill_line() → auraxium.InstanceProxy[SkillLine]

Return the skill line containing this skill.

This returns an auraxium.InstanceProxy.

class auraxium.ps2.SkillCategory(*args, locale=None, **kwargs)

A skill category for a particular class or vehicle.

Skill categories are groups like “Passive Systems”, “Performance Slot”, or weapon-specific groups like scopes or rail attachments.

id: int

The unique ID of this skill category. In the API payload, this field is called skill_category_id.

name: auraxium.types.LocaleData

Localised name of the skill category.

skill_set_id: int

The SkillCategory this category belongs to.

See also

skill_set() – The skill set containing this skill category.

skill_set_index: int

The position of this category in the associated skill category.

skill_points: int

Unused.

description: auraxium.types.LocaleData | None

The localised description for this skill category.

image_id: int | None

The image ID of the default image.

image_set_id: int | None

The corresponding image set.

image_path: str | None

The base path to the image with the default image_id.

skill_lines() → auraxium.SequenceProxy[SkillLine]

Return the skill lines contained in this category.

This returns a auraxium.SequenceProxy.

skill_set() → auraxium.InstanceProxy[SkillSet]

Return the skill set for this category.

This returns an auraxium.InstanceProxy.

class auraxium.ps2.SkillLine(*args, locale=None, **kwargs)

A series of skills or certifications.

id: int

The unique ID for this skill line. In the API payload, this field is called skill_line_id.

name: auraxium.types.LocaleData

Localised name of the skill line.

skill_points: int

Unused. Any skill lines that can be acquired in-game have a cost of zero. Skill lines with non-zero cost are unused and have costs of 999’999.

skill_category_id: int | None

The SkillCategory this skill line belongs to.

See also

category() – The skill set category containing this skill line.

skill_category_index: int | None

The index of this skill line in its containing skill category.

description: auraxium.types.LocaleData | None

The localised description for this skill line.

image_id: int | None

The image ID of the default image.

image_set_id: int | None

The corresponding image set.

image_path: str | None

The base path to the image with the default image_id.

category() → auraxium.InstanceProxy[SkillCategory]

Return the category this skill line belongs to.

This returns an auraxium.InstanceProxy.

skills() → auraxium.SequenceProxy[Skill]

Return the skills contained in this skill line in order.

This returns a auraxium.SequenceProxy.

class auraxium.ps2.SkillSet(*args, locale=None, **kwargs)

A skill set for a particular vehicle or class.

In the old certifications menu, skill sets were used for all certifications associated with a given item or vehicle. Since its removal, they are mostly for internal grouping of skill lines.

Additionally, skill sets are used for unlocking vehicle weapons.

id: int

The unique ID of this skill set. In the API payload, this field is called reward_type_id.

name: auraxium.types.LocaleData

Localised name of the skill set.

skill_points: int | None

The number of certification points required to unlock a given vehicle weapon.

required_item_id: int | None

The Item required to unlock this skill set. Used to prevent buying upgrades for items the player has not unlocked yet.

description: auraxium.types.LocaleData | None

The localised description of the skill set.

image_id: int | None

The image ID of the default image.

image_set_id: int | None

The corresponding image set.

image_path: str | None

The base path to the image with the default image_id.

categories() → auraxium.SequenceProxy[SkillCategory]

Return the skill categories in this skill set.

This returns a auraxium.SequenceProxy.

required_item() → auraxium.InstanceProxy[Item]

Return the item required for access to this skill set.

This returns an auraxium.InstanceProxy.

Progression

class auraxium.ps2.Achievement(*args, locale=None, **kwargs)

An achievement a player may pursue.

Achievements include weapon medals and service ribbons.

id: int

The unique ID of this achievement. In the API payload, this field is called achievement_id.

item_id: int

The Item associated with this achievement. An item ID of 0 signifies that this achievement is a service ribbon and not tied to any weapon (e.g. facility type specific capture ribbons).

name: auraxium.types.LocaleData

Localised name of the achievement. This is the name of the weapon medal or service ribbon displayed in the game.

objective_group_id: int

The objective group of to this achievement. All objectives in the given group will count towards this achievement.

See also

objectives() – Retrieve all objectives from this achievement’s objective group.

reward_id: int

The auraxium.ps2.Reward granted when this achievement is earned.

See also

reward() – Retrieve the reward tied to this achievement.

repeatable: bool

Whether this achievement is repeatable. Ribbons generally are repeatable, weapon medals are not.

Note

Repeatable achievements are tracked differently than one-off ones. See the auraxium.models.CharacterAchievement model for details.

description: auraxium.types.LocaleData

The localised description of achievement.

image_id: int | None

The image ID of the default image.

image_set_id: int | None

The corresponding image set.

image_path: str | None

The base path to the image with the default image_id.

async objectives() → list[Objective]

Return any objectives in the given objective group.

reward() → auraxium.InstanceProxy[Reward]

Return the reward tied to this achievement.

This returns an auraxium.InstanceProxy.

class auraxium.ps2.Experience(data, client)

An experience type that can be earned by a character.

Note

Not all experience types returned through the WebSocket event stream’s GainExperience event are present in this table.

id: int

The unique ID of this experience tick. In the API payload, this field is called experience_id.

description: str

A description of when this experience reward is granted.

xp: int

The amount of experience points awarded.

class auraxium.ps2.ExperienceRank(data, client)

A type of experience tick.

rank: int

The battle rank value represented by this rank name.

xp_max: int

The amount of experience needed to achieve this rank.

Note

Due to the BR 100 / BR 120 level caps, this may not correlate estimate the rank of a given character as they might have “lost” part of their experience to a level cap in the past.

vs: auraxium.models.ExperienceRankData.EmpireData

Empire-specific rank data for VS.

vs_image_path: str

The VS-specific default image path.

nc: auraxium.models.ExperienceRankData.EmpireData

Empire-specific rank data for NC.

nc_image_path: str

The NC-specific default image path.

tr: auraxium.models.ExperienceRankData.EmpireData

Empire-specific rank data for TR.

tr_image_path: str

The TR-specific default image path.

image(faction: int | Faction) → str

Return the default image for this type.

class auraxium.ps2.Directive(*args, locale=None, **kwargs)

A directive a character may complete.

id: int

The unique ID of this directive. In the API payload, this field is called directive_id.

directive_tree_id: int

The ID of the DirectiveTree of this directive.

See also

tree() – Return the directive tree of this directive.

directive_tier_id: int

The ID of the DirectiveTier of this directive.

See also

tier() – Return the directive tier of this directive.

objective_set_id: int

The objective set of this directive. All objectives in the given set will contribute towards this directive.

See also

objectives() – Return the objectives counting towards completion of this directive.

name: auraxium.types.LocaleData

The localised name of the directive.

qualify_requirement_id: int

The ID of an Item (usually weapon) that must be unlocked for this directive to be available.

description: auraxium.types.LocaleData

The localised description of the directive.

image_id: int | None

The image ID of the default image.

image_set_id: int | None

The corresponding image set.

image_path: str | None

The base path to the image with the default image_id.

objectives() → auraxium.SequenceProxy[Objective]

Return the objectives for this directive.

This returns a auraxium.SequenceProxy.

tier() → auraxium.InstanceProxy[DirectiveTier]

Return the tier of the directive.

This returns an auraxium.InstanceProxy.

tree() → auraxium.InstanceProxy[DirectiveTree]

Return the tree of the directive.

This returns an auraxium.InstanceProxy.

class auraxium.ps2.DirectiveTier(*args, locale=None, **kwargs)

A tier in a directive tree.

Directive tiers list the set of directives required to advance to the next tier in the DirectiveTree, e.g. “Combat Medic: Adept” or “Shotguns: Master”.

id: int

The unique ID of the directive tier. In the API payload, this field is called directive_tier_id.

directive_tree_id: int

The ID of the DirectiveTree this directive tier is a part of.

See also

tree() – Return the directive tree of this directive tier.

reward_set_id: int | None

The ID of the reward set awarded upon completion of this directive tier.

See also

rewards() – Return the list of rewards awarded upon completion of this directive tier.

directive_points: int

The number of directive points awarded upon completion of this directive tier.

completion_count: int

The number of directives in this tier that must be completed to advance to the next stage.

name: auraxium.types.LocaleData

The localised name of the directive tier.

image_id: int | None

The image ID of the default image.

image_set_id: int | None

The corresponding image set.

image_path: str | None

The base path to the image with the default image_id.

directives() → auraxium.SequenceProxy[Directive]

Return the list of directives in this tier.

This returns a auraxium.SequenceProxy.

async rewards() → list[Reward]

Return the rewards granted upon completion of this tier.

tree() → auraxium.InstanceProxy[DirectiveTree]

Return the tree of the directive.

This returns an auraxium.InstanceProxy.

class auraxium.ps2.DirectiveTree(*args, locale=None, **kwargs)

A multi-tiered tree of directives for a given category.

Directive trees are chains of related directives like “Heavy Assault” in the “Infantry” category, or “Carbines” in the “Weapons” category.

id: int

The unique ID of the directive tree. In the API payload, this field is called directive_tree_id.

directive_tree_category_id: int

The ID of the DirectiveTreeCategory of this directive tree.

See also

category() – Return the directive tree category of this directive tree.

description: auraxium.types.LocaleData | None

The localised description of the directive tree.

name: auraxium.types.LocaleData

The localised name of the directive tree.

image_id: int | None

The image ID of the default image.

image_set_id: int | None

The corresponding image set.

image_path: str | None

The base path to the image with the default image_id.

category() → auraxium.InstanceProxy[DirectiveTreeCategory]

Return the category of the directive tree.

This returns an auraxium.InstanceProxy.

directives() → auraxium.SequenceProxy[Directive]

Return the list of directives in this category.

This returns a auraxium.SequenceProxy.

tiers() → auraxium.SequenceProxy[DirectiveTier]

Return the list of directive tiers in this category.

This returns a auraxium.SequenceProxy.

class auraxium.ps2.DirectiveTreeCategory(*args, locale=None, **kwargs)

A category of directive.

In-game, this is represented by the side bar to the left, e.g. “Infantry”, “Weapons”, or “Vehicles”.

id: int

The unique ID of the directive tree category. In the API payload, this field is called directive_tree_category_id.

name: auraxium.types.LocaleData

The localised name of the directive tree category.

trees() → auraxium.SequenceProxy[DirectiveTree]

Return the directive trees in this category.

This returns a auraxium.SequenceProxy.

class auraxium.ps2.Objective(data, client)

A objective presented to a character.

id: int

The unique ID of this objective. In the API payload, this field is called objective_id.

objective_type_id: int

The associated ObjectiveType for this objective.

See also

type() – The type of objective.

objective_group_id: int

The objective group this objective contributes to. Used to link objectives to directives.

See also

get_by_objective_group() – Get the list of objectives for a given objective group.

param*

Type-specific parameters for this objective. Refer to the corresponding ObjectiveType for details.

classmethod get_by_objective_group(objective_group_id: int, client: auraxium.Client) → auraxium.SequenceProxy[Objective]

Return any rewards contained from the given reward group.

This returns a auraxium.SequenceProxy.

type() → auraxium.InstanceProxy[ObjectiveType]

Return the objective type of this objective.

This returns an auraxium.InstanceProxy.

class auraxium.ps2.ObjectiveType(data, client)

A type of objective.

This class mostly specifies the purpose of any generic parameters.

id: int

The unique ID of the objective type. In the API payload, this field is called objective_type_id.

description: str

A description of what the objective type is used for.

param*

Descriptions of what the corresponding parameter is used for in objectives of this type.

class auraxium.ps2.Reward(data, client)

A reward awarded to a player.

Access the corresponding auraxium.ps2.RewardType instance via the Reward.type() method for information on generic parameters.

id: int

The unique ID of this reward. In the API payload, this field is called reward_id.

reward_type_id: int

The RewardType of this reward.

See also

type() – The reward type instance for this report.

count_min: int

The minimum number of rewarded items/currency.

count_max: int

The maximum number of rewarded items/currency.

param*

Type-specific parameters for this reward. Refer to the corresponding RewardType for details.

classmethod get_by_reward_group(reward_group_id: int, client: auraxium.Client) → auraxium.SequenceProxy[Reward]

Return any rewards contained in the given reward group.

This returns a auraxium.SequenceProxy.

classmethod get_by_reward_set(reward_set_id: int, client: auraxium.Client) → auraxium.SequenceProxy[Reward]

Return any rewards contained in the given reward set.

This returns a auraxium.SequenceProxy.

type() → auraxium.InstanceProxy[RewardType]

Return the type of reward.

This returns an auraxium.InstanceProxy.

class auraxium.ps2.RewardType(data, client)

A type of reward.

This class mostly specifies the purpose of any generic parameters.

id: int

The unique ID of this reward type. In the API payload, this field is called reward_type_id.

description: str

A description of what this reward type is used for.

count_min: str | None

The minimum number of rewarded items/currency.

count_max: str | None

The maximum number of rewarded items/currency.

param*

Descriptions of what the corresponding parameter is used for in rewards of this type.

Abilities

class auraxium.ps2.Ability(data, client)

An ability triggered by a character or vehicle.

See the corresponding AbilityType instance via the Ability.type() method for information on generic parameters.

Note

The in-game mechanics these abilities correspond to is currently undocumented due to the lack of links between abilities and other types in the API.

It should be possible to correlate fields like expire_msec or reuse_delay_msec to their corresponding in-game ability. Though very time-consuming.

More information needed & much appreciated.

id: int

The unique ID of this ability. In the API payload, this field is called ability_id.

ability_type_id: int

The ID of the AbilityType of this ability.

See also

type() – Return the type of this ability.

expire_msec: int | None

The duration of a single-shot ability in milliseconds.

Only present for ability types 3, 6, 12, 16, 17, and 30.

first_use_delay_msec: int | None

The initial delay before the ability can be used in milliseconds.

Note

As of April 2021, this field is always 0 or 1 for all fields. Since an initial cast delay of 1 millisecond makes little sense, this field is likely unused.

next_use_delay_msec: int | None

The cooldown of a single-shot ability in milliseconds.

Note

The difference between this field and reuse_delay_msec has not been tested yet.

Only present for ability types 6, 13, and 30.

reuse_delay_msec: int | None

The recharge cooldown for multi-use abilities in milliseconds.

Note

The difference between this field and next_use_delay_msec has not been tested yet.

Only present for ability types 3, 6, 12, 16, 17, and 30.

resource_type_id: int | None

The ID of the ResourceType used by this ability.

Only present for ability types 3, 6, 10, 13, and 30.

See also

resource_type() – Return the resource type of this ability.

resource_first_cost: int | None

The initial cost of activating a continuous the ability.

Only present for ability types 3, 6, 10, 13, and 30.

resource_cost_per_msec: int | None

Only present for ability types 3, 6, 10, 13, and 30.

The amount drained from the ability’s ResourceType every millisecond as long as the ability is active.

distance_max: float | None

Not yet documented. See also radius_max.

radius_max: float | None

Not yet documented. See also distance_max.

flag_toggle: bool | None

Whether the ability is channeled and can be toggled on and off.

Only present for ability types 3, 6, 10, 13, and 30.

param*

Type-specific parameters for this ability. Refer to the corresponding AbilityType for details.

Note

As of April 2021, only the param1 field is used.

string*

Type-specific string values for this ability. Refer to the corresponding AbilityType for details.

Note

As of April 2021, none of the string fields are used.

resource_type() → auraxium.InstanceProxy[ResourceType]

Return the resource type used by this ability, if any.

This returns an auraxium.InstanceProxy.

type() → auraxium.InstanceProxy[AbilityType]

Return the ability type of this ability.

This returns an auraxium.InstanceProxy.

class auraxium.ps2.AbilityType(data, client)

A type of ability.

Ability types specify the basic function of a given Ability. The param* fields in the ability type list what these generic parameters are used for in the corresponding abilities (where specified).

Note

The purpose of these base types and what mechanics they correspond to in-game is currently undocumented due to the lack of links between abilities and other types in the API.

More information needed & much appreciated.

id: int

The unique ID for this ability type. In the API payload, this field is called ability_type_id.

description: str | None

A description of what this ability type is used for.

param*

Descriptions of what the corresponding parameter is used for in abilities of this type.

Note

As of April 2021, only the param1 field is used.

string*

Descriptions of what the corresponding string value is used for in abilities of this type.

Note

As of April 2021, none of the string fields are used.

class auraxium.ps2.ResourceType(data, client)

Resources are entity-specific states used by other mechanics.

You can think of them as attributes attached to a character or vehicle that is then modified by other game mechanics.

This includes active class abilities like the Combat Medic’s Nano Regen Device or the Heavy Assault’s overshield, physical resources like Cortium carried by A.N.T.s or Collossi, but are also used as a reservoir for other game mechanics like Esamir’s Electrical Storm vehicle debuff.

id: int

The unique ID of this resource type. In the API payload, this field is called resource_type_id.

description: str

An internal description of what this resource type is used for. This string is not safe to display to users as this field could be blank or set to a dummy value like Esamir.Storm.VehicleOverload.

Effects

class auraxium.ps2.Effect(data, client)

An effect acting on a character.

Effects are usually created by an Ability or are the result of a weapon firing.

Access the corresponding EffectType instance via the Effect.type() method for information on generic parameters.

Note

The relationship between Effect and ZoneEffect is currently undocumented and non-obvious.

Both deal in weapon and character stat modifiers, but Effect seems to act on individual entities (damage, single-target-heal, revives, etc.) while ZoneEffect usually acts on groups of entities (ammo dispatch, armour buffs, etc.).

id: int

The unique ID of this effect. In the API payload, this field is called effect_id.

effect_type_id: int

The ID of the EffectType of this effect.

See also

type() – Return the type of this effect.

ability_id: int | None

The ability that the effect, if any.

target_type_id: int | None

Integer value of the TargetType enum used to find targets for this effect.

See also

target_type() – Return the enum value representing the effect’s target type.

resist_type_id: int

The ResistType entry used by this effect.

See also

resist_type() – Return the resist type used by this effect.

is_drain: bool | None

Unknown. This flag does not appear to correlate with draineable abilities such as Afterburners or overshields.

The resist type of any effect with this flag set will be zero.

duration_seconds: float | None

The duration of the effect. For continuously channeled effects such as the Combat Medic’s healing beam, this will be 999’999 seconds.

param*

Type-specific parameters for this effect. Refer to the corresponding EffectType for details.

resist_type() → auraxium.InstanceProxy[ResistType]

Return the resist type of the effect.

This returns an auraxium.InstanceProxy.

target_type() → TargetType | None

Return the target type of this effect.

type() → auraxium.InstanceProxy[EffectType]

Return the effect type of this effect.

class auraxium.ps2.EffectType(data, client)

A type of effect.

Effect types specify the core function of a given Effect. The param* fields in the effect type list what these generic parameters are used for in effects of this type.

Effects include damage (direct, indirect, and distance falloff), (de-)buffs, resource modification, as well as healing/revives.

id: int

The unique ID of this effect type. In the API payload, this field is called effect_type_id.

description: str

A description of what this effect type is used for.

param*

Descriptions of what the corresponding parameter is used for in effects of this type.

class auraxium.ps2.TargetType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Enumerate the types of targets for effects.

Effects will only act upon entities matching the given target type. This is why AoE heal generally does not apply to enemies.

Values::

SELF  = 1
ANY   = 2
ENEMY = 3
ALLY  = 4

class auraxium.ps2.ZoneEffect(data, client)

An effect or buff applied in an area.

Zone effects are area-bound effects acting on a group of characters or entities.

Access the corresponding ZoneEffectType instance via the type() method for information on generic parameters.

Note

The relationship between ZoneEffect and Effect is currently undocumented and non-obvious.

Both deal in weapon and character stat modifiers, but Effect seems to act on individual entities (damage, single-target-heal, revives, etc.) while ZoneEffect usually acts on groups of entities (ammo dispatch, armour buffs, etc.).

However, zone effects are also responsible for Gate Shield Diffusors and certain types of implant buffs like the jump height of Catlike. Again, more information is needed here.

id: int

The unique ID of this zone effect. In the API payload, this field is called zone_effect_id.

zone_effect_type_id: int

The ID of the associated ZoneEffectType.

See also

type() – Return the type of this effect.

ability_id: int

The ID of the auraxium.ps2.Ability associated with this zone effect.

Note

Tests are inconclusive whether this is the ability that triggered the zone effect or whether these effects are used to control abilities.

See also

ability() – The ability associated with this zone effect.

param*

Type-specific parameters for this zone effect. Refer to the corresponding ZoneEffectType for details.

ability() → auraxium.InstanceProxy[Ability]

Return the ability associated with this zone effect.

type() → auraxium.InstanceProxy[ZoneEffectType]

Return the type of this zone effect.

class auraxium.ps2.ZoneEffectType(data, client)

A type of zone effect.

Zone effect types specify the core function of a given ZoneEffect. The param* fields in the zone effect type list what these generic parameters are used for in effects of this type.

id: int

The unique ID of this zone effect type. In the API payload, this field is called zone_effect_type_id.

description: str

A description of what this zone effect type is used for.

param*

Descriptions of what the corresponding parameter is used for in zone effects of this type.

Resistance & Armour

class auraxium.ps2.ArmourFacing(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Enumerator for armour facing directions.

This enum is used to list different ArmourInfo values for the same vehicle depending on the attacker’s position.

Note that this mechanic uses the relative position of the attacker and the impacted vehicle, not the impact location the projectile.

Values::

FRONT  = 0
RIGHT  = 1
TOP    = 2
REAR   = 3
LEFT   = 4
BOTTOM = 5
ALL    = 6

class auraxium.ps2.ArmourInfo(data, client)

An armour info entry for an entity.

Armour is a vehicle-specific property that modifies incoming damage depending on the angle of attack. Note that this mechanic uses the relative position of the attacker and the impacted vehicle, not the impact location the projectile.

A vehicle may have multiple ArmourInfo entries associated with different ArmourFacing directions.

Note that these armour percentages may be negative, in which case the damage dealt is increased beyond the base damage of the weapon.

See also

auraxium.ps2.Profile.armour_info – Access the armour info entries for a given auraxium.ps2.Profile.

id: int

The unique ID of this entry. In the API payload, this field is called armour_info_id.

armor_facing_id: int

The integer representation of the ArmourFacing enum value this entry provides armour data for.

See also

facing – The enum value of this entry.

armor_percent: int

Damage reduction in percent. A value of 10.0 denotes an armour reduction of 10 percent. Negative armour values will increase damage taken::

actual_damage = (1 - (resistance / 100)) * base_damage

armor_amount: int | None

A flat damage reduction applied to the damage effect prior to the percentage reduction.

Note

This field is unused since the 2017 armour rework as part of the “Critical Mass” game update.

description: str

An internal description of what situation this armour info entry is used for.

facing() → ArmourFacing

Return the facing direction for this stat entry.

class auraxium.ps2.ResistInfo(data, client)

Specifies the resistance values for a given profile and type.

id: int

The ID of this resist info entry. In the API payload, this field is called resist_info_id.

resist_type_id: int

The ID of the corresponding auraxium.ps2.ResistType for this entry.

See also

type() – Return the resist type of the entry.

resist_percent: int | None

The damage reduction in percent.

resist_amount: int | None

A flat amount of damage to absorb.

multiplier_when_headshot: float | None

A custom headshot multiplier override to apply for this combination of weapon and target. This is used to specify the custom headshot multipliers used for MAXes for the NS-AM7 Archer vs. regular sniper rifles.

description: str

A description of this resist info entry.

type() → auraxium.InstanceProxy[ResistType]

Return the resist type for this entry.

This returns an auraxium.InstanceProxy.

class auraxium.ps2.ResistType(data, client)

A type of resistance a profile may hold.

This is used to implement weapon type specific damage modifiers like “Melee”, “Small Arms” or “Heavy Machine Gun”.

id: int

The unique ID of this resist type. In the API payload, this field is called resist_type_id.

description: str

A description of what this resist type is used for.

Weapon Unlocks & Depot Bundles

class auraxium.ps2.MarketingBundle(*args, locale=None, **kwargs)

A marketing bundle containing multiple items.

A purchaseable bundle in the in-game depot. Use the items() method to retrieve the items contained in this bundle.

id: int

The unique ID of this bundle. In the API payload, this field is called marketing_bundle_id.

description: auraxium.types.LocaleData

The description text for this bundle.

image_id: int

The image asset ID for this bundle.

cert_price: int | None

The unlock price in certification points, if any. Note that most promotional bundles may only be unlocked via Daybreak Cash.

name: auraxium.types.LocaleData

Localised display name of the bundle.

station_cash_price: int

The unlock price in Daybreak Cash (formerly SOE Station Cash).

release_time: int

The time at which this bundle was first released as a UTC timestamp.

image() → str

Return the default image for this type.

async items() → list[tuple[Item, int]]

Return the contents of the bundle.

This returns a list of tuples consisting of the item and the quantity awarded.

class auraxium.ps2.MarketingBundleSingle(data, client)

A marketing bundle containing a single item.

This is used for single-item entries in the depot, such as weapons, scopes or other upgrades that can be purchased in the Depot.

id: int

The unique ID of this bundle. In the API payload, this field is called marketing_bundle_id.

item_id: int

The auraxium.ps2.Item unlocked by this bundle.

item_quantity: int

The number of items received.

name: auraxium.types.LocaleData

Localised display name of the bundle.

station_cash_price: int

The unlock price in Daybreak Cash (formerly SOE Station Cash).

cert_price: int | None

The certification point price of the item, if any.

release_time: int

The time at which this item was first released as a UTC timestamp.

item() → auraxium.InstanceProxy[Item]

Return the item unlocked by the bundle.

This returns an auraxium.InstanceProxy.

Leaderboard

Utility functions for working with leaderboard data.

class auraxium.ps2.leaderboard.Period(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

The periods supported by the leaderboard.

The following valid time periods are currently known::

FOREVER
MONTHLY
WEEKLY
DAILY
ONE_LIFE

class auraxium.ps2.leaderboard.Stat(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

A statistic tracked by the leaderboard.

The following statistics are currently available via the leaderboard::

KILLS
SCORE
TIME
DEATHS

async auraxium.ps2.leaderboard.by_char(stat: Stat, character: int | auraxium.ps2.Character, period: Period = Period.FOREVER, *, client: auraxium.Client) → tuple[int, int] | None

Return the rank of the player on the leaderboard.

Note that only the top 10’000 players are tracked by the leaderboard. For characters not in the top 10’000, this will return None. Otherwise, this returns the a tuple consisting of the rank and stat value for the character.

async auraxium.ps2.leaderboard.by_char_multi(stat: Stat, character: int | auraxium.ps2.Character, *args: int | auraxium.ps2.Character, period: Period = leaderboard.Period.FOREVER, client: auraxium.Client) → list[tuple[int, int]]

Return the rank of the players on the leaderboard.

Like by_char, but takes any number of arguments.

async auraxium.ps2.leaderboard.top(stat: Stat, period: Period = Period.FOREVER, matches: int = 10, offset: int = 0, world: int | auraxium.ps2.World | None = None, *, client: auraxium.Client) → list[tuple[int, auraxium.ps2.Character]]

Retrieve the top entries on the leaderboard for the given stat.

Note that only the top 10’000 players are tracked by the leaderboard.