The client changes identity as the player moves between login, lobby, battle, replay, and disconnect. Code that is correct for one player object can be invalid for the next.

Think in screens first

At login there may be no account object. In the garage the account exists but no battle avatar exists. In battle the garage UI is gone and a new player object represents the avatar. A mod file may remain loaded throughout, but the objects it talks to do not.

Primary ownershipCurrent player object and its context
Readiness anchorPlayer lifecycle events, not module import
Version sensitivityVerify private names per client build

Plain-language map

  • Account: the logged-in player while using the garage and account services.
  • Avatar: the player's live battle-side object.
  • Arena: the current battle and its participants, teams, period, and rules.
  • Entity: one live object in the loaded battle space, such as a vehicle.
  • View: one visible UI screen or component that can be closed and recreated.

The formal class names below help you find these objects in the client source, but the screen transition is the important idea.

Core object model

Object Context What it represents
Account Lobby The connected account and lobby-side server interaction
PlayerAvatar Battle The player inside an arena and battle space
Arena Battle or replay Periods, participants, teams and battle-wide state
Vehicle entity Loaded battle space A live world object with transform, appearance and replicated state
GUI application Lobby or battle Views, windows, controllers, input and presentation state

BigWorld.player() returns the current player entity, but its type and readiness must be checked. A non-None value is not proof that every service, arena, cache, or view exists.

Transition sequence

Import / init
    ↓
Account becomes player
    ↓
Account GUI and synchronized caches become ready
    ↓
Account becomes non-player
    ↓
Avatar becomes player
    ↓
Arena and battle space become ready
    ↓
Avatar becomes non-player
    ↓
Account becomes player again
    ↓
Disconnect

The account-to-avatar transition is not necessarily logout. State intended to survive one battle should be cleared on account change or disconnect, not merely because the lobby player stopped being current.

Safe context gate

import BigWorld

def _current_account():
    player = BigWorld.player()
    if player is None or player.__class__.__name__ != 'Account':
        return None
    return player

def _current_avatar():
    player = BigWorld.player()
    if player is None or player.__class__.__name__ != 'PlayerAvatar':
        return None
    if getattr(player, 'arena', None) is None:
        return None
    return player

Direct class imports are preferable when stable and available. Defensive name checks are useful only at optional boundaries where importing a mode-specific class may itself fail.

State ownership

  • Process: installation flags and immutable constants.
  • Account session: account identity and settings intended to survive battle transitions.
  • Arena: participants, vehicle IDs, temporary battle data, and battle callbacks.
  • Entity: live health, transform, appearance, and per-spawn state.
  • View: DOM nodes, view-model subscriptions, drag state, and UI callbacks.

Common mistakes

  • Starting lobby work during import because the module loaded while the client happened to be in the hangar.
  • Keeping a PlayerAvatar, arena, entity, or view reference after its context ended.
  • Clearing account-session state on every account/avatar transition.
  • Assuming the GUI is ready because the player object exists.
  • Allowing a delayed callback from the old arena to modify the new arena.

Verification trail

Locate the player lifecycle event source, inspect where each event is fired, and trace which GUI or cache initialization follows it. Confirm teardown by following the reverse transition as well.