Native module guides
The Native reference groups three module guides by responsibility. Keep their owners and data types separate when following an example.
| Module | Start here | Boundary to preserve |
|---|---|---|
| BigWorld | Runtime and callbacks, entities and spaces, models and loading | Engine objects and delayed work need an owning client context. |
| ResMgr | Virtual paths and DataSection readers | An opened resource is separate from parsed application data and a ready view. |
| GUI | Component roots, resetters and coordinate modes | Native component ownership is separate from Scaleform and Gameface view ownership. |
BigWorld is the native engine bridge exposed to
client-side Python. It provides access to engine time, scheduled callbacks, entities, spaces,
cameras, input state, models, resources, collision queries, graphics, sound and other runtime-owned
systems.
Use the owner that matches the question
This is not a rule to avoid the source. It is a rule to use the layer that owns the fact you are asking for.
The deepest layer is correct when the fact is genuinely engine-owned: entity lookup, world coordinates, camera state, collision, callbacks, or resource loading. A higher client layer is correct when it owns a processed meaning: selected lobby vehicle, account cache readiness, battle feedback events, UI route visibility, model state, or feature-controller state.
Many bugs happen when a mod reads a deep representation and treats it as the finished semantic answer. Deep objects may exist before the cache is synchronized, before a view is ready, before an entity appearance is built, or after a replay seek has invalidated old references. Use source verification to identify the real owner, then use the most direct stable API or event at that owner.
Where BigWorld fits
Python-to-engine bridge
Many objects returned by BigWorld are native engine objects rather than
ordinary Python-owned values. Their lifetime is controlled by the client.
Low-level state
Use it when the required information genuinely belongs to the engine: entity lookup, world coordinates, camera state, collision, frame-safe callbacks or resource loading.
Not always the best layer
For account data, battle controllers, UI state or feature logic, a higher-level game service or event is often clearer and more stable.
Interpret the owner before the name
Many expressions begin with BigWorld, but they do not all belong to the same API
layer. A native module function, an engine-managed collection, a property on the current player
object, and a server proxy call require different safety rules.
| Expression shape | Owner | Safety rule |
|---|---|---|
BigWorld.callback(...) |
Native module | Client-thread delayed work; cancel or generation-guard it. |
BigWorld.entities |
Engine-managed collection | Entity membership changes during battle, reconnect, and replay seek. |
BigWorld.player().arena |
Current avatar object | Valid only when the player is a battle avatar with an arena. |
BigWorld.entity(id).appearance |
The returned entity | Verify the entity generation and appearance readiness before use. |
player.cell.someRequest(...) |
Server-side entity proxy | Not a local helper. Verify authority, context, and user intent before calling. |
Start with common functions
These familiar BigWorld entry points cover many small mods. Follow the linked guides for lifecycle details; the historical SDK explains the concepts, while current World of Tanks callers establish which forms the client uses.
| Task | Entry point | Check before use |
|---|---|---|
| Defer a small operation | callback / cancelCallback | Keep the live handle and cancel it when its owner stops. |
| Measure an engine-relative interval | time() | Keep both timestamps in the same clock and context. |
| Read the current player | player() | Check for absence and the expected account or avatar type. |
| Find a live entity | entity(id) | A lookup can fail; an ID does not guarantee a live object or ready appearance. |
| Read the render-window dimensions | windowSize() | Window pixels and authored UI coordinates use different scaling. |
Reading a camera, entity or player gives access to a client-owned object. Keep mutations with the subsystem that owns that state, and reacquire references after a context change.
Core areas
Runtime & callbacks
Schedule work on the client thread, cancel it safely, and distinguish engine time from wall-clock time.
Entities & spaces
Understand live entities, spatial identity, collision and coordinate ownership.
Camera & input
Read active camera and key state without stealing ownership from the game UI.
Resources & models
Work with engine-loaded assets, model objects and matrix providers.
API map
Find common historical symbols by responsibility and then verify them in the current client.
Safe decision rule
Game service or controller available? -> prefer it
Lifecycle event available? -> subscribe to it
Only engine state exposes the answer? -> use BigWorld
Historical SDK mentions a symbol? -> verify before shippingCommon mistakes
- Treating
BigWorld.player()as permanently available. - Keeping an entity or model reference after its arena, space or view was destroyed.
- Using repeated zero-delay callbacks as an uncontrolled update loop.
- Assuming an SDK signature matches the current customized client.
- Using a low-level query where a higher-level controller already owns the same state.