Native module guides

The Native reference groups three module guides by responsibility. Keep their owners and data types separate when following an example.

ModuleStart hereBoundary to preserve
BigWorldRuntime and callbacks, entities and spaces, models and loadingEngine objects and delayed work need an owning client context.
ResMgrVirtual paths and DataSection readersAn opened resource is separate from parsed application data and a ready view.
GUIComponent roots, resetters and coordinate modesNative component ownership is separate from Scaleform and Gameface view ownership.

Explore Game Behavior & Mechanics for explanations of vehicle stats, reload cycles, visibility, mode rules, progression and replay behavior, with links to the supporting game files.

World of Tanks client development

Build mods that are easier to understand, maintain, and update.

Follow step-by-step Python modding tutorials, then explore safe hooks, events, Gameface overlays, BigWorld APIs, packaging, debugging, and client update migration.

Start learningBuild your first mod

What are you building?

Choose a visible result, follow a complete example, then use the linked reference to understand its ownership and limits. Check each tutorial's compatibility note before adapting it to your client.

New to client modding? Follow this path

You do not need to understand the whole client before starting. Complete these four stages, then use the rest of the site as a reference.

Load a minimal mod

Learn the package path, loader lifecycle, compilation, and safe wrappers.

Follow the production tutorials

Build complete mods across ten levels, with source research, annotated code, testing, diagnostics, and maintenance at every level.

How the layers fit together

Core principles

Lifecycle before behavior

Import means the file was discovered. It does not mean the account, battle, cache, dependency container, or UI is ready.

State has a scope

Account, arena, vehicle entity, vehicle type, inventory item, and view instance are different identities.

Async results can go stale

Carry context with every delayed result and reject it when the player, arena, vehicle, or view changed.

Cleanup is part of the feature

Callbacks, event handlers, windows, GUI roots, observers, workers, and patches all need an explicit owner and exit path.

Learn by building complete mods

The Level 1–10 series begins with configuration and garage state, introduces battle and Gameface systems, then advances through persistence, local integration, analytics, and replay-safe data engineering. Every level carries the feature through investigation, implementation, packaging, testing, diagnosis, and update maintenance.

Build a loader-safe single file

Keep each mod in one mod_*.py file with clearly ordered constants, state, helpers, hooks, lifecycle handlers, and teardown.

Understand the game systems

Move beyond isolated hooks by learning which subsystem owns the data, when it becomes ready, and which identifiers remain valid.

Vehicles & Items

Understand descriptors, inventory objects, entities, and results.

Battle & Arena

Follow participants, periods, controllers, and live state.

Gameface Modding

Build injected native extensions and standalone modern overlays with correct models, sizing, scaling, input, and lifecycle ownership.

Typical architecture

A robust mod can stay in one source file when its constants, state, helpers, hooks, lifecycle handlers, and cleanup are kept in a deliberate order.

_started = False
_callback_id = None
_context_token = 0

def init():
    global _started
    if _started:
        return
    _started = True
    subscribe_lifecycle()
    install_hooks()

def start_context():
    global _context_token
    _context_token += 1
    create_owned_state(_context_token)

def stop_context():
    global _context_token
    _context_token += 1       # invalidates delayed work
    cancel_callbacks()
    destroy_owned_state()

def fini():
    global _started
    if not _started:
        return
    stop_context()
    restore_owned_hooks()
    unsubscribe_lifecycle()
    _started = False

Release checklist

  • Initialization is idempotent and does not rely on import order.
  • Every callback, event, hook, worker, input handler, and view has a teardown path.
  • Slow work runs outside the game thread and returns through the engine callback bridge.
  • Configuration is validated, backward compatible, and written safely.
  • Optional features fail independently rather than preventing the whole mod from loading.
  • Logs provide context without exposing tokens, endpoints, or high-frequency noise.

Advanced system guides

Native actions

Build synchronized server-changing flows without duplicate requests or misleading success messages.

Battle data

Choose authoritative event layers, preserve baselines, and reconcile final results.

Gameface models

Work with native projections, placeholders, composite roots, and host update contracts.

Local tools

Bridge loopback tools and background threads to the game client safely.

Spatial coordinates

Convert between world, arena, minimap, and UI spaces without mixing ownership.

Mode identifiers

Keep GUI type, bonus type, queue type, and mode tags in the right namespace.

Development workflow

The guide now includes a practical path from source file to a verified local archive: environment checks, ownership discovery, package extraction, asset staging, deterministic .wotmod builds, and post-update verification.

Open Tooling, Assets & Packaging →

Expanded engineering references

The guide now includes dedicated references for Python 2.7 behavior, multi-mod compatibility, update testing, source navigation, native BigWorld helpers, and the historical API.

Detailed contract reference