Настройка окружения для Python-мода (без графической части)

Python-моды наиболее просты в разработке и являются хорошей отправной точкой для новичков. В этом руководстве мы рассмотрим, как настроить окружение для комфортной разработки Python-модов.

Необходимые инструменты

Перед началом разработки убедитесь, что у вас установлены следующие инструменты:

Python 2.7 — интерпретатор Python, который будет использоваться для компиляции скриптов.
7-Zip — архиватор, который будет использоваться для упаковки модов в формат .mtmod.
Git — система контроля версий, с помощью которой будет загружен исходный код игры.
VSCode — редактор кода, который будет использоваться для написания кода.
- Python extension for VSCode — расширение для VSCode, которое добавляет поддержку Python.

Важно

Исполняемый файл Python должен быть доступен из командной строки. Для этого при установке Python необходимо включить Add python.exe to Path. Установите значение Will be installed on local hard drive, по умолчанию оно отключено.

Add python.exe to Path

Если вы его уже установили, то можете переустановить или поискать в интернете, как добавить Python в PATH вручную. После добавления перезапустите VSCode.

Организация проекта

Создайте папку для вашего проекта (один проект = один мод) и откройте её в VSCode.

Исходный код игры

Для подсветки синтаксиса, автодополнений, переходов по коду и удобного поиска по исходному коду игры в папке с проектом необходимо иметь копию исходного кода. Скачаем её из неофициального репозитория GitHub.

Для этого откройте терминал в VSCode (Ctrl+` или Terminal -> New Terminal) и выполните команду:

shell

git clone https://github.com/izeberg/wot-src.git

В корне вашего проекта появится папка wot-src с исходным кодом игры.

Перейдите во вкладку Source Control (или нажмите Ctrl+Shift+G), нажмите на кнопку ... и поставьте галочку на Repositories

После этого выберите репозиторий wot-src в списке, нажмите на кнопку с веткой EU и во всплывающем списке выберите ветку origin/RU — это переключит исходный код на версию для «Мир Танков». Switch Branch

Обратите внимание

Репозиторий большой — скачивание и переключение веток может занять некоторое время, наберитесь терпения.

Настройка VSCode

Чтобы VSCode мог работать с исходным кодом игры, установите расширение Python extension for VSCode.

После установки необходимо указать, где именно находятся скрипты игры. Для этого создайте в корне проекта папку .vscode, а в ней файл settings.json со следующим содержимым:

settings.json

json

{
  "python.autoComplete.extraPaths": [
    "wot-src/sources/res/scripts/client",
    "wot-src/sources/res/scripts/common",
    "wot-src/sources/res/scripts/client_common",
  ],
  "python.analysis.extraPaths": [
    "wot-src/sources/res/scripts/client",
    "wot-src/sources/res/scripts/common",
    "wot-src/sources/res/scripts/client_common",
  ],
  "python.analysis.userFileIndexingLimit": 20000,
}

Файл метаданных `meta.xml`

В корне вашего проекта создайте файл meta.xml со следующим содержимым:

meta.xml

xml

<mod>
  <name>my.first-mod</name>
  <description>My First Mod Description</description>
  <version>{{VERSION}}</version>
  <author>Your Name</author>
</mod>

Обратите внимание на {{VERSION}} на 4-й строке — это специальный маркер, который будет заменён на актуальную версию мода при упаковке.

Точка входа

Поскольку игра автоматически запускает скрипты с префиксом mod_ из папки res/scripts/client/gui/mods/, такую структуру папок и следует использовать в вашем проекте.

Создайте файл вашего мода mod_myFirstMod.py по пути res/scripts/client/gui/mods/mod_myFirstMod.py.

Совет

Вы можете нажать в VSCode кнопку создания нового файла, вписать туда полный путь до этого файла res/scripts/client/gui/mods/mod_myFirstMod.py, и VSCode сам создаст все необходимые подпапки.

Напишите в этом файле следующий код:

mod_myFirstMod.py

python

from gui import SystemMessages
from helpers import dependency
from skeletons.gui.shared.utils import IHangarSpace

MOD_VERSION = '{{VERSION}}'

# Получаем ссылку на IHangarSpace
hangarSpace = dependency.instance(IHangarSpace) # type: IHangarSpace

# Мод загрузился
def init():
  print("[MY_FIRST_MOD] Hello, World! Mod version is %s" % MOD_VERSION)

  # Подписываемся на загрузку ангара
  hangarSpace.onSpaceCreate += onHangarSpaceCreate

def onHangarSpaceCreate():
  # Отписываемся от загрузки ангара
  hangarSpace.onSpaceCreate -= onHangarSpaceCreate

  # Выводим уведомление в ангаре
  SystemMessages.pushMessage(
    text='Привет мир! Версия мода: %s' % MOD_VERSION,
    type=SystemMessages.SM_TYPE.InformationHeader,
    messageData={ 'header': 'MY_FIRST_MOD' }
  )

Обратите внимание, что у вас в редакторе должна быть подсветка синтаксиса. Наведите мышку на SystemMessages.pushMessage и увидите всплывающую подсказку с описанием функции и её параметров.

tooltip

А если вы начнёте печатать, после символа . (точка) появятся подсказки с атрибутами и методами объекта.

suggestion

Если вы видите в окошке Loading..., нужно немного подождать, пока VSCode проиндексирует исходный код игры.

Скрипты и ресурсы

Кроме файла точки входа в вашем моде могут быть и другие скрипты и ресурсы (изображения, файлы конфигурации и т. д.). Хороший подход — создание корневой папки вашего мода рядом с точкой входа, например my_first_mod, и размещение всех дополнительных файлов там. Это минимизирует конфликты имён файлов с другими модами.

По пути res/scripts/client/gui/mods/ создайте папку my_first_mod и добавьте туда пустой файл __init__.py.

Компиляция скриптов `build.bat`

Скачайте файл build.bat и поместите его в корень вашего проекта.

Блок настроек в начале файла

bat

rem ==== настройки ====
set "SEVENZIP=C:\Program Files\7-Zip\7z.exe"
set "MOD_NAME=my.first-mod"
set "MOD_ENTRY=mod_myFirstMod.py"

SEVENZIP — путь до исполняемого файла 7-Zip. Если вы установили 7-Zip в другое место, измените этот путь.
MOD_NAME — имя вашего мода. Используйте формат автор.название; он будет автоматически подставлен при упаковке автор.название_версия.mtmod.
MOD_ENTRY — имя файла точки входа вашего мода. Обычно это mod_<имя_вашего_мода>.py.

Как работает build.bat

Если вам интересно, как работает этот скрипт, ниже приведено подробное описание каждого блока.

Разбор аргументов

В этом блоке скрипт присваивает значение переменной v из аргумента командной строки -v <version>, который указывает версию мода.

bat

set "v="
:parse
if "%~1"=="" goto after_parse
if /I "%~1"=="-v" (
  if "%~2"=="" (echo [ERROR] Missing value for -v & exit /b 1)
  set "v=%~2"
  shift & shift & goto parse
)
echo Usage: %~nx0 -v ^<version^>
exit /b 1

:after_parse
if not defined v (
  echo [ERROR] Version is required. Use -v ^<version^>.
  exit /b 1
)

Очистка и подготовка build

Процесс компиляции происходит в папке build, которая создаётся заново при каждом запуске скрипта. В этой папке создаётся структура, аналогичная той, что используется в игре, и в неё копируются все ресурсы из папки res вашего проекта.

bat

if exist ".\build" rmdir /S /Q ".\build"
mkdir ".\build"
xcopy ".\res" ".\build\res" /E /I /Y >nul

Проставить версию

В этом блоке скрипт ищет в точке входа мода маркер {{VERSION}} и заменяет его на значение переменной v, которая была установлена из аргумента командной строки.

bat

set "configPath=.\build\res\scripts\client\gui\mods\%MOD_ENTRY%"
if exist "%configPath%" (
  powershell -NoProfile -Command ^
    "(Get-Content '%configPath%' -Raw -Encoding utf8) " ^
    "-replace '\{\{VERSION\}\}','%v%' | " ^
    "Set-Content '%configPath%' -Encoding utf8"
) else (
  echo [WARN] %configPath% not found.
)

Байткод Python 2

Происходит компиляция всех .py‑файлов в папке build в байткод .pyc, который используется игрой.

bat

python -m compileall ".\build"

Компиляция в SWF

Запускается скрипт build.bat из папки as3, если такая папка есть в корне проекта. Этот скрипт должен скомпилировать все ActionScript‑файлы в SWF‑файлы и поместить их в папку ./as3/bin. После этого все SWF‑файлы копируются в папку build/res/gui/flash, откуда попадают в файл мода.

bat

if exist ".\as3\build.bat" (
  pushd ".\as3"
  del /Q /F ".\bin\*.swf"
  call build.bat
  xcopy ".\bin\*.swf" "..\build\res\gui\flash\" /Y /I >nul
  popd
)

meta.xml с версией

Аналогично точке входа в meta.xml проставляется версия мода.

bat

if exist ".\meta.xml" (
  powershell -NoProfile -Command ^
    "$m = Get-Content '.\meta.xml' -Raw -Encoding utf8; " ^
    "$m = $m -replace '\{\{VERSION\}\}','%v%'; " ^
    "Set-Content '.\build\meta.xml' $m -Encoding utf8"
) else (
  echo [ERROR] meta.xml not found.
  exit /b 1
)

Упаковка в .mtmod (7-Zip)

Происходит упаковка необходимых файлов в архив .mtmod с помощью 7-Zip. Упаковываются только файлы с расширениями .pyc, .swf, .png и meta.xml.

bat

pushd ".\build"

set "folder=%MOD_NAME%_%v%.mtmod"
if exist "%folder%" del /Q "%folder%"

"%SEVENZIP%" a -tzip -mx=0 "%folder%" ".\*.pyc" -r >nul
"%SEVENZIP%" a -tzip -mx=0 "%folder%" ".\*.swf" -r >nul
"%SEVENZIP%" a -tzip -mx=0 "%folder%" ".\meta.xml" >nul
"%SEVENZIP%" a -tzip -mx=0 "%folder%" ".\*.png" -r >nul

popd

Итоговая структура проекта

В итоге у вас должна получиться следующая структура проекта:

my-first-mod/
├── .vscode
│   └── settings.json
├── wot-src
│   └── ... (исходный код игры)
├── build.bat
├── meta.xml
└── res
    └── scripts
        └── client
            └── gui
                └── mods
                    ├── mod_myFirstMod.py
                    └── my_first_mod
                        ├── __init__.py
                        └── ... (другие файлы вашего мода)

Компиляция и упаковка

Для запуска сборки откройте терминал в VSCode (Ctrl+` или Terminal -> New Terminal)

Обратите внимание

Должна использоваться оболочка CMD. Если у вас используется PowerShell, переключитесь на CMD, нажав на стрелочку рядом с кнопкой + в окне терминала и выбрав Command Prompt.

И выполните команду:

cmd

build.bat -v 1.0.0

Вывод сборки

terminal

В корне проекта появится файл my.first-mod_1.0.0.mtmod — это ваш упакованный мод 🎉.

Важно

В build.bat используется команда python -m compileall — ожидается, что у вас в PATH доступен Python 2.7. Проверить, какая версия Python используется по умолчанию, можно командой в этом же терминале:

bat

python --version

Вывод должен быть таким: Python 2.7.16.

Если версия отличается, замените строку в build.bat на путь до вашего python.exe, например:

bat

# Компиляция Python
C:\Python27\python.exe -m compileall ".\build"

Проверочный запуск

В корневой папке игры очистите файл python.log (откройте любым текстовым редактором, удалите всё его содержимое и сохраните).

Перенесите файл my.first-mod_1.0.0.mtmod в папку с игрой /mods/<версия_игры>/, запустите игру и дождитесь входа в ангар.

В центре уведомлений должно появиться сообщение от вашего мода:

notification

Откройте файл python.log и убедитесь, что там есть вывод вашего мода:

python.log

log

/------------------------------------------------------------------------------------------\
Tanki(x64) Build: 1.37.0.10 #2189918 starting on Mon Sep  8 04:43:39 2025
...
INFO: [PY_DEBUG] Mod package 'e:/tanki/mods/1.37.0.0/my.first-mod_1.0.0.mtmod' loaded
...
INFO: [MY_FIRST_MOD] Hello, World! Mod version is 1.0.0
...

Логов будет много, воспользуйтесь поиском по файлу (Ctrl+F) и найдите MY_FIRST_MOD, чтобы убедиться, что мод успешно загрузился и выполнился.

Авторы

Andrei Soprachev

История изменений

Последнее редактирование 4 месяца назад

Показать историю

Настройка окружения для Python-мода (без графической части) ​

Необходимые инструменты ​

Организация проекта ​

Исходный код игры ​

Настройка VSCode ​

Файл метаданных meta.xml ​

Точка входа ​

Скрипты и ресурсы ​

Компиляция скриптов build.bat ​

Блок настроек в начале файла ​

Итоговая структура проекта ​

Компиляция и упаковка ​

Проверочный запуск ​