Vehicles & Items — Dossier snapshots and item-query ownership

Vehicle dossier data during fast battle entry

The normal dossier requester belongs to the account side of the client. When a player enters or reconnects directly to battle, that public requester may no longer be usable even though the account repository still holds records loaded earlier.

The current client uses a disk-backed dossier cache through account_helpers.DossierCache. It stores an account-specific .dat file in the dossier_cache directory beside preferences.xml. The exact filename encoding, pickle layout, private member names, and record format are version-sensitive and must be checked against the current client source.

Normal source

Use the synchronized account dossier while the account context is active and the record is demonstrably populated.

Read-only fallback

In battle, a retained native record may recover an already-synchronized baseline. It cannot fetch data that was never written locally.

Confirmed snapshot

For features that must survive immediate queueing or restart-to-battle, save a small validated snapshot after the garage dossier is known to be usable.

Record presence alone is not enough. A cache entry can decode to an empty/default dossier when synchronization did not finish.
For an established vehicle, a positive battle count is a useful observed check that the dossier is populated; a zero rating by itself can still be legitimate.
Never let an empty native dossier overwrite a previously confirmed snapshot.
Resolve in this order: confirmed local snapshot, populated native dossier, then an explicit loading or unavailable state.
Treat private cache access as optional and fail closed when the client version no longer matches.
Do not force account-side synchronization from battle by altering internal guards; the account command channel is no longer available there.

Item-query criteria have their own operators

RequestCriteria overloads operators to build predicates. Their meaning is defined by the client class, not by the symbols' usual Boolean or bitwise interpretation.

Expression	Current criterion meaning
`first \| second`	Append both condition sets; all conditions must match.
`first ^ second`	Match either criterion, including when both match.
`~criterion`	Negate the combined condition set.

REQ_CRITERIA.EMPTY accepts every candidate. It is not a false starting value for an OR-style union: EMPTY ^ criterion still accepts everything. REQ_CRITERIA.NONE is the defined false criterion. Parenthesize compound expressions and do not substitute Python and/or for these composition methods.

Illustrative Python 2.7 helper: the caller supplies verified compact descriptor IDs. This combines inventory membership and an explicit ID predicate without changing client items.

from gui.shared.utils.requesters.ItemsRequester import REQ_CRITERIA

def inventory_items_in(item_cds):
    ids = tuple(item_cds)
    return REQ_CRITERIA.INVENTORY | REQ_CRITERIA.IN_CD_LIST(ids)

Criteria retain their predicate objects and captured references. Converting the ID iterable to a tuple fixes the membership keys used by this helper; composing criteria alone would not freeze a supplied mutable list or set. It does not create detached copies of the queried GUI items.

Specialized criteria can also hold an IntCDProtector outside their predicate. Base composition returns a plain RequestCriteria and does not preserve that protector. Inspect such metadata before combining a specialized filter; the example above puts the ID restriction in the membership predicate itself.

lookInInventory() is a candidate-traversal hint, not an inventory-only result boundary. For an eligible vehicle query, synchronous getItems can scan inventory and then the catalog, so a matching ID can reach a predicate more than once. A nation filter skips that initial inventory pass. Prefer read-only predicates unless their state explicitly accounts for the traversal; do not assume one evaluation per item.

These are version-sensitive current-public Python query contracts, not an inventory synchronization or installed-client test. Use the correct item/cache owner and the verified copy path before hypothetical configuration edits.

The async query's callback carries its item collection

ItemsRequester.getItemsAsync sends its accumulated ItemsCollection through callback(result). Its own wg_async Future normally completes with None when the generator finishes. Awaiting that Future's value is not the same as receiving the collection. The client's __cacheVehicles warmup uses await_callback to observe the callback path.

Illustrative Python 2.7 adapter: the caller supplies a requester from its currently synchronized items-cache owner and chooses wait_timeout as a wait budget in seconds. This follows the inspected client caller's default vehicle-query shape; choose your feature's membership and price-coverage requirements explicitly.

from gui.shared.gui_items import GUI_ITEM_TYPE
from wg_async import await_callback, wg_async, wg_return

@wg_async
def read_vehicle_items(items_requester, wait_timeout):
    items = yield await_callback(
        items_requester.getItemsAsync,
        timeout=wait_timeout)(itemTypeID=GUI_ITEM_TYPE.VEHICLE)
    wg_return(items)

The adapter's returned Future carries the callback value. await_callback observes that callback rather than chaining the producer's returned Future, so do not assume producer-Future failures are automatically forwarded. Its timeout bounds waiting after the producer call returns; it does not preempt synchronous work, cancel the underlying query or undo collected results. Observe the adapter's failure path and keep unexpected-exception diagnostics at the owning boundary.

The producer spreads traversal over cooperative waits. If BigWorld.player() disappears, its iterator returns and the outer method can still deliver the accumulated collection. Callback delivery therefore does not establish complete traversal or unchanged account/cache identity. Recheck the current owner and the coverage your feature requires before applying results to a retained view.

The result map is newly assembled, but its GUI-item values can still be cached objects. It is not a detached configuration snapshot. Use the verified copy path before local hypothetical edits, and keep the future, timeout and cancellation contracts separate from item coverage. These are current-public Python data-flow contracts, not a live inventory, disconnect or native scheduling test.