A client object can exist before it is useful, and a useful object can become stale without a normal-looking transition. Use this matrix to decide which readiness signal must be checked before reading or mutating state.

RuleExisting is not ready. Ready is not synchronized. Synchronized is not valid forever.
Common failureImport-time reads, early arena access, stale replay state, and UI model updates after destruction.
Best practiceRevalidate the owner at the point of use, not only when scheduling work.

See also: Runtime Ownership Glossary for choosing the owner and Callback Lifecycle Patterns for delayed readiness work.

Readiness table

System Exists when Actually useful when Invalidated by Common mistake
BigWorld.player() Very early after a player object is present. The returned object type matches the context being queried. Login state changes, battle transitions, disconnects, replay lifecycle. Treating account and avatar as interchangeable.
Account object After account creation/login. Account GUI, services, and required caches are initialized. Disconnect, account switch, client shutdown. Reading lobby systems during import.
Items cache The service may exist early. Synchronization has completed and the target branch is populated. Cache resync, account switch, invalidation events. Assuming an empty value means the account has no data.
Selected vehicle Hangar services exist. The hangar selection and descriptors are populated. Vehicle change, cache resync, account transition. Reading selected vehicle while loading the hangar.
Avatar object During battle or replay context. Arena and required battle controllers exist. Battle exit, disconnect, replay seek or shutdown. Accessing battle state before arena/entity creation.
Arena Battle loading begins. Period, roster, vehicle records, and required controllers are populated. Battle end, reconnect, replay time warp. Treating arena creation as full battle readiness.
Vehicle entity The entity is created in the space. Relevant replicated properties have arrived and the entity is alive for the question. Destruction, respawn, entity unload, replay seek. Keeping entity references across arena transitions.
Gameface window The Python or Wulf object is created. HTML, JavaScript, model, route visibility, and layout have completed. Route change, view destroy, battle transition, replay rewind. Updating the model before the DOM/model/layout exists.
Replay context A replay is loaded. Playback state and recorded entities are initialized. Pause/resume, seek, time warp, replay close. Assuming live account services exist.
Battle results The battle completion path begins. The full result payload has arrived and matches the arena being processed. Reconnect, duplicate delivery, stale pending callbacks. Processing an early or partial result as final truth.

Readiness checklist

  • Which owner creates this state?
  • Which event proves it is ready?
  • Which cache or service can still be synchronizing?
  • Can the state disappear before a delayed callback runs?
  • Does replay mode skip or replace the normal live lifecycle?
  • What cleanup clears references, listeners, windows, and pending callbacks?

Delayed work

Delayed work should re-check readiness inside the callback. The object that was valid when a callback was scheduled may be gone by the time it runs.

def _on_delayed_refresh():
    player = BigWorld.player()
    if player is None or not _is_expected_context(player):
        return

    owner = _resolve_current_owner(player)
    if owner is None or not _owner_is_ready(owner):
        return

    _refresh_from_owner(owner)