The arena owns battle-wide context. Vehicle records describe participants, entities describe loaded world objects, and battle controllers turn raw changes into feature-specific state.
Battle data lifecycle map
Battle availability is a sequence of overlapping owners, not one “battle loaded” moment.
| Stage | What it establishes | What it does not establish |
|---|---|---|
| Lobby / pre-battle | Account caches, queue/prebattle intent, selected vehicle, and mode configuration | A live arena, avatar, world space, or battle entity |
| Arena created | A transition toward one arena and an arena-scoped identity | Avatar, space, HUD, entities, or synchronized battle data |
| Avatar becomes player | Battle-scoped ownership begins and core arena/controller construction can start | Loaded space, player vehicle appearance, input, or completed GUI initialization |
| Space and avatar readiness | Required initialization gates and arena loading have converged for the current Avatar | Every optional component or derived HUD value; some state is republished afterward |
| Entity population | Individual vehicles/components enter the current area of interest and become usable at their own readiness points | A complete server roster history or permanent object lifetime |
| Active battle | Arena period, controllers, replicated properties, and feedback can drive live presentation | Final settlement or data never exposed to this client |
| Battle end / result delivery | Live owners wind down; one or more result paths may deliver final or partial records | That account caches have already resynchronized or a result callback is unique |
| Teardown | Callbacks, entity references, controllers, and view state must be invalidated by owner/generation | Permission to keep reading already-destroyed battle services |
Arena periods
Battle logic should distinguish waiting, countdown, active play, and post-battle phases. The exact enum values are version-sensitive; compare against named constants rather than unexplained integers.
Participant and entity layers
| Layer | Answers |
|---|---|
| Arena roster | Who participates, on which team, using which vehicle type and arena vehicle ID? |
| Vehicle entity | Is the world object loaded, where is it, and what is its current replicated state? |
| Battle controller | What processed information is available to the HUD or feature? |
| Feedback/event stream | Which gameplay events were reported and in what context? |
| Battle results | What final server-confirmed outcome was recorded? |
Context token pattern
_arena_token = 0
_current_arena_id = None
def _enter_arena(arena_id):
global _arena_token, _current_arena_id
_arena_token += 1
_current_arena_id = arena_id
return _arena_token
def _is_current_arena(token, arena_id):
return token == _arena_token and arena_id == _current_arena_id
def _leave_arena():
global _arena_token, _current_arena_id
_arena_token += 1
_current_arena_id = None
_cancel_battle_callbacks()Space and appearance readiness
A participant can exist in the roster before its entity is created. An entity can exist before its appearance or optional components are ready. Use bounded retries only for short initialization gaps and stop when the arena or entity changes.
Respawn and spectator modes
Do not equate participant identity with one entity lifetime. In respawn modes, the same player can receive multiple entities. Postmortem and spectator states can also change the observed vehicle without changing the local avatar.
Replay playback is a separate owner with recorded entity/method/property exposure, seek and time-warp boundaries, and no guarantee of live lobby/account services. Training and special modes may register different controllers or components. Detect the active context and required capability instead of assuming the standard live-battle stack.
Common mistakes
- Starting the feature on avatar entry before arena or GUI controllers exist.
- Assuming every roster member already has an entity.
- Keeping one entity reference for an entire respawn battle.
- Applying live state after the arena changed because a callback completed late.
- Replacing a broad battle method and dropping unknown event types.
Verification trail
Trace arena period changes, roster updates, entity enter/leave events, the controller that feeds the relevant UI, and final result delivery. Test standard, replay, training, spectator, and respawn contexts where applicable.
Entity presence, visuals, and spotting are separate states
Follow Vehicle.py, Avatar's visual-start path, BattleFeedbackAdaptor and BattleFieldCtrl together: they own different parts of entity presence, visuals and spotting.
| Observation | What it establishes | What still needs checking |
|---|---|---|
| Arena roster entry | A participant record exists | Current entity, appearance, and GUI visibility |
BigWorld.entity(vehicleID) | A current local entity exists | Started visuals, rendered model, battlefield spotting |
onVehicleEnterWorld(vehicle) | Avatar reached its enter-world notification | The hidden path can reach it without starting rendered visuals |
| Feedback vehicle proxy | GUI-visual membership and entity lookup succeeded | Model readiness and battlefield spotted status |
| Marker object or handle | A pool entry exists | It may be inactive, detached, or hidden |
Vehicle.show(False) changes draw-pass visibility without setting isHidden or stopping GUI visuals. GUI-visual start and stop separately feed the battlefield controller; position updates also influence alive-enemy spotted state. Do not derive a universal spotted flag from entity presence or isHidden.
Feedback can defer marker/minimap add notifications through a zero-delay callback. Visual stop cancels that add before sending removal, so removal can arrive without a delivered add. Marker removal can retain its object and handle for reuse. Make removal idempotent and release cached proxies or projection data at detach/model change. These source contracts do not establish server detection rules or prove rendering behavior.
State and health owners
Entity health, crew activity, arena kill attribution and battlefield-cache membership do not change through one common event. A cache rebuild can restore roster maximums without observing healing; late visual startup can repeat death presentation without a new kill. See Battle State, Components and Feedback for the ownership and publication contracts.