Первый практический шаг в X4FO

Результат первого подхода#

Хорошая первая цель — самостоятельно найти путь переименования, выполнить его адресный автономный тест и объяснить один отрицательный сценарий. После этого можно взять маленькое изменение одного слоя, уже понимая способ проверки.

Это учебный план действий для тебя. Команды ниже не означают, что во время написания курса были выполнены сборка мода или игровая приёмка. Порядок чтения начинается на стартовой странице.

1. Зафиксируй, с какой копией работаешь#

Открой папку D:\X4FoundationsOnline в редакторе. В PowerShell из корня:

Set-Location D:\X4FoundationsOnline
git status --short
git log -5 --oneline

status показывает локальные изменения; они могут быть новее последнего коммита. log показывает историю коммитов. Изменённое дерево само по себе не ошибка. Не сбрасывай файлы и не переключай ветку поверх неизвестных правок, чтобы «начать с чистого листа».

Прочитай верх docs/status.md: текущий пакет, оставшиеся ограничения, следующий сценарий. Затем открой docs/developer-code-map.md и раздел нужной механики. Курс объясняет код на дату редакции, а текущий статус продолжает обновляться.

2. Подготовь инструменты по своей цели#

Для нового окружения полный порядок установки зависимостей, сборки DLL и подготовки профилей находится в руководстве разработчика. Если в нём уже выполнен шаг для этой копии, повторять его ради чтения курса не нужно.

Не запускай вручную вторую службу на pipe работающего профиля. Изменения Python-файлов на диске также не означают, что уже запущенная служба перешла на новую версию.

3. Выполни одну небольшую проверку без запуска X4#

После установки подходящего Python:

Set-Location D:\X4FoundationsOnline
py -3.12 -m unittest discover -s tests -p test_object_names.py

Это конкретный пример с Python 3.12. Если используешь подготовленное .venv, вместо py -3.12 укажи его интерпретатор:

& .\.venv\Scripts\python.exe -m unittest discover -s tests -p test_object_names.py

Выбери один подходящий вариант. Команда проверяет семейство в модели сессии; она не запускает настоящую операцию над кораблём X4.

Открой tests/test_object_names.py и найди тест test_stale_foreign_and_untrusted_fields_never_reach_native. Он показывает, что чужое имущество и неверная ревизия не должны порождать ожидающую операцию, а лишнее поле/неприемлемый текст отклоняются проверкой намерения.

В тестах assertEqual(a, b) проверяет равенство, assertIsNone(value) — отсутствие значения, assertRaises(...) — ожидаемое исключение. setUp создаёт исходные условия перед каждым тестом. Не путай эти помощники тестового набора с API игры.

4. Прочитай Lua-проверку того же пути#

В tests/lua_object_names.lua функции X4 заменены заглушками. Найди проверку с текстом never renamed locally: после обычного SetComponentName имя не должно сразу меняться на стороне гостя. Затем проследи доставку OBJECT_NAME_STATE, применение имени и ACK.

Если установленная X4 находится по другому пути, замени значение $game. Запуск из корня проекта:

$game = 'C:\Program Files (x86)\Steam\steamapps\common\X4 Foundations'
py -3.12 tools/test_lua_adapter.py $game tests/lua_object_names.lua

Проверка использует Lua-библиотеку установленной игры и заглушки API. Окно X4 для неё не требуется. Успех показывает поведение адаптера с этими заглушками; реальный интерфейс и объект всё равно проверяются отдельно при изменении игрового пути.

5. Выбери первое изменение#

После чтения удачный небольшой участок — понятность сообщения об отказе в переименовании. В extension/ui/x4_online_object_names.lua найди текст Переименование: ожидается имя хоста или нет права управления.

Это сообщение выдаёт клиентская ветка, когда ключ объекта не найден или локальная подготовка запроса не удалась. Причин несколько: отсутствуют данные хоста, уже есть ожидающий запрос, идёт сохранение и другие условия. Текст должен объяснять ограниченность знания, а не выдавать любую из этих ситуаций за окончательный отказ хоста.

Возможная первая задача: сделать эту фразу понятнее, сохранив логику. Для начала выпиши:

Требование: понятное сообщение, когда локально не удалось начать переименование.
Место: Lua, ветка SetComponentName.
Что меняется: только текст сообщения.
Доказательство: diff текста, синтаксис Lua и адресная проверка адаптера.
Если проверяем показ в игре: воспроизводим указанную ветку через обычный UI.

Не меняй request_id, поля сообщений, права или время повторной отправки в одной задаче с редактурой сообщения. Такие изменения имеют другой объём и потребуют собственных проверок.

Задача выше предлагается для твоей самостоятельной работы; этот курс не вносит её в код мода.

6. Проверь именно то, что поменял#

Для текста статьи достаточно сборки вики и проверки ссылок. Для изменения Lua нужны соответствующие синтаксис и адаптер. Для нового игрового поведения заранее определяются фактическая операция, независимое чтение и восстановление. Полный дорогой прогон нужен по новым рискам и затронутым зависимостям.

Если задача меняет владение, деньги, очередь или сохранение, сначала проследи всю цепочку до движка. Собери неизвестные свойства в короткие совместимые опыты, затем реализуй связанный пакет и проверь его общим сценарием. Так предписывает порядок работы проекта.

В реальном тесте переименования результат полезно записать так:

Это план проверки, а не утверждение, что все строки сейчас пройдены. Результат записывается с версией, исходными условиями и оставшимися ограничениями. Правила подготовки изолированных профилей и общего прогона есть в developer-guide и combined-autotests.

7. Куда двигаться после первого семейства#

Следующей изучай механику похожим способом: штатная кнопка → Lua/MD/AI → намерение → authority → операция хоста → readback → доставка → сохранение. Используй карту кода, чтобы выбрать семейство.

Хороший признак прогресса — ты можешь до изменения назвать требование, неизвестный участок и минимальное доказательство. После этого новая строка кода появляется в понятном месте и с понятным способом проверки.

Вернуться к маршруту знакомства.