--- title: "Настройка окружения для Python-мода (без графической части)" description: "Python-моды наиболее просты в разработке и являются хорошей отправной точкой для новичков. В этом руководстве мы рассмотрим, как настроить окружение для комфортной разработки Python-модов." lang: ru canonical_url: "https://docs.wotstat.info/guide/first-steps/environment/python/" markdown_url: "https://docs.wotstat.info/guide/first-steps/environment/python/index.md" source_url: "https://github.com/wotstat/mods-development-docs/blob/main/docs/ru/guide/first-steps/environment/python/index.md" --- # Настройка окружения для Python-мода (без графической части) Python-моды наиболее просты в разработке и являются хорошей отправной точкой для новичков. В этом руководстве мы рассмотрим, как настроить окружение для **комфортной** разработки Python-модов. ## Необходимые инструменты Перед началом разработки убедитесь, что у вас установлены следующие инструменты: - [Python 2.7](https://www.python.org/downloads/release/python-2716/) — интерпретатор Python, который будет использоваться для компиляции скриптов. - [7-Zip](https://www.7-zip.org/) — архиватор, который будет использоваться для упаковки модов в формат `.mtmod`. - [Git](https://git-scm.com/) — система контроля версий, с помощью которой будет загружен исходный код игры. - [VSCode](https://code.visualstudio.com/) — редактор кода, который будет использоваться для написания кода. - [Python extension for VSCode](https://marketplace.visualstudio.com/items?itemName=ms-python.python) — расширение для VSCode, которое добавляет поддержку Python. > **WARNING — Важно** Исполняемый файл Python должен быть доступен из командной строки. Для этого при установке Python необходимо включить `Add python.exe to Path`. Установите значение `Will be installed on local hard drive`, по умолчанию оно отключено. ![Add python.exe to Path](https://docs.wotstat.info/guide/first-steps/environment/python/assets/install-python.png) Если вы его уже установили, то можете переустановить или поискать в интернете, как добавить Python в PATH вручную. После добавления перезапустите VSCode. ## Организация проекта Создайте папку для вашего проекта (один проект = один мод) и откройте её в `VSCode`. ### Исходный код игры Для подсветки синтаксиса, автодополнений, переходов по коду и удобного поиска по исходному коду игры в папке с проектом необходимо иметь копию исходного кода. Скачаем её из [неофициального репозитория GitHub](https://github.com/izeberg/wot-src). Для этого откройте терминал в VSCode (`` Ctrl+` `` или `Terminal -> New Terminal`) и выполните команду: ```shell git clone https://github.com/izeberg/wot-src.git ``` В корне вашего проекта появится папка `wot-src` с исходным кодом игры. Перейдите во вкладку `Source Control` (или нажмите `Ctrl+Shift+G`), нажмите на кнопку `...` и поставьте галочку на `Repositories` ![Source Control](https://docs.wotstat.info/guide/first-steps/environment/python/assets/enable-repo.png) После этого выберите репозиторий `wot-src` в списке, нажмите на кнопку с веткой `EU` и во всплывающем списке выберите ветку `origin/RU` — это переключит исходный код на версию для «Мир Танков». ![Switch Branch](https://docs.wotstat.info/guide/first-steps/environment/python/assets/checkout.png) > **TIP — Обратите внимание** Репозиторий большой — скачивание и переключение веток может занять некоторое время, наберитесь терпения. #### Настройка VSCode Чтобы `VSCode` мог работать с исходным кодом игры, установите расширение [Python extension for VSCode](https://marketplace.visualstudio.com/items?itemName=ms-python.python). После установки необходимо указать, где именно находятся скрипты игры. Для этого создайте в корне проекта папку `.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 my.first-mod My First Mod Description {{VERSION}} Your Name ``` Обратите внимание на `{{VERSION}}` на 4-й строке — это специальный маркер, который будет заменён на актуальную версию мода при упаковке. ### Точка входа Поскольку игра автоматически запускает скрипты с префиксом `mod_` из папки `res/scripts/client/gui/mods/`, такую структуру папок и следует использовать в вашем проекте. Создайте файл вашего мода `mod_myFirstMod.py` по пути `res/scripts/client/gui/mods/mod_myFirstMod.py`. > **TIP — Совет** Вы можете нажать в 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](https://docs.wotstat.info/guide/first-steps/environment/python/assets/hint.png) А если вы начнёте печатать, после символа `.` (точка) появятся подсказки с атрибутами и методами объекта. ![suggestion](https://docs.wotstat.info/guide/first-steps/environment/python/assets/suggestion.png) Если вы видите в окошке `Loading...`, нужно немного подождать, пока `VSCode` проиндексирует исходный код игры. ### Скрипты и ресурсы Кроме файла точки входа в вашем моде могут быть и другие скрипты и ресурсы (изображения, файлы конфигурации и т. д.). Хороший подход — создание корневой папки вашего мода рядом с точкой входа, например `my_first_mod`, и размещение всех дополнительных файлов там. Это минимизирует конфликты имён файлов с другими модами. По пути `res/scripts/client/gui/mods/` создайте папку `my_first_mod` и добавьте туда пустой файл `__init__.py`. ### Компиляция скриптов `build.bat` Скачайте [файл build.bat](https://docs.wotstat.info/download/mod-build/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`. **Details — Как работает build.bat** Если вам интересно, как работает этот скрипт, ниже приведено подробное описание каждого блока. --- **Разбор аргументов** В этом блоке скрипт присваивает значение переменной `v` из аргумента командной строки `-v `, который указывает версию мода. ```bat:line-numbers=10 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 ^ exit /b 1 :after_parse if not defined v ( echo [ERROR] Version is required. Use -v ^. exit /b 1 ) ``` --- **Очистка и подготовка build** Процесс компиляции происходит в папке `build`, которая создаётся заново при каждом запуске скрипта. В этой папке создаётся структура, аналогичная той, что используется в игре, и в неё копируются все ресурсы из папки `res` вашего проекта. ```bat:line-numbers=28 if exist ".\build" rmdir /S /Q ".\build" mkdir ".\build" xcopy ".\res" ".\build\res" /E /I /Y >nul ``` --- **Проставить версию** В этом блоке скрипт ищет в точке входа мода маркер `{{VERSION}}` и заменяет его на значение переменной `v`, которая была установлена из аргумента командной строки. ```bat:line-numbers=33 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:line-numbers=44 python -m compileall ".\build" ``` --- **Компиляция в SWF** Запускается скрипт `build.bat` из папки `as3`, если такая папка есть в корне проекта. Этот скрипт должен скомпилировать все `ActionScript`‑файлы в `SWF`‑файлы и поместить их в папку `./as3/bin`. После этого все `SWF`‑файлы копируются в папку `build/res/gui/flash`, откуда попадают в файл мода. ```bat:line-numbers=47 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:line-numbers=56 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:line-numbers=67 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`) > **TIP — Обратите внимание** Должна использоваться оболочка `CMD`. Если у вас используется `PowerShell`, переключитесь на `CMD`, нажав на стрелочку рядом с кнопкой `+` в окне терминала и выбрав `Command Prompt`. И выполните команду: ```cmd build.bat -v 1.0.0 ``` **Details — Вывод сборки** ![terminal](https://docs.wotstat.info/guide/first-steps/environment/python/assets/terminal-output.png) В корне проекта появится файл `my.first-mod_1.0.0.mtmod` — это ваш упакованный мод :tada:. > **WARNING — Важно** В `build.bat` используется команда `python -m compileall` — ожидается, что у вас в `PATH` доступен `Python 2.7`. Проверить, какая версия Python используется по умолчанию, можно командой в этом же терминале: ```bat python --version ``` Вывод должен быть таким: `Python 2.7.16`. Если версия отличается, замените строку в `build.bat` на путь до вашего `python.exe`, например: ```bat:line-numbers=32 # Компиляция Python C:\Python27\python.exe -m compileall ".\build" ``` ## Проверочный запуск В корневой папке игры очистите файл `python.log` (откройте любым текстовым редактором, удалите всё его содержимое и сохраните). Перенесите файл `my.first-mod_1.0.0.mtmod` в папку с игрой `/mods/<версия_игры>/`, запустите игру и дождитесь входа в ангар. В центре уведомлений должно появиться сообщение от вашего мода: ![notification](https://docs.wotstat.info/guide/first-steps/environment/python/assets/notification.png) Откройте файл `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`, чтобы убедиться, что мод успешно загрузился и выполнился.