Карта кода X4FO: кто за что отвечает

Общая картина#

X4FO состоит из расширения внутри игры и отдельного Python-процесса рядом с ней. На обоих компьютерах есть свои части этого набора. Хост ведёт мир, гость показывает разрешённое состояние и отправляет действия.

ГОСТЬ                                 ХОСТ
Обычное окно X4                       Обычное окно X4
       ↓                                     ↓
Lua адаптер ↔ C++ мост                 Lua / MD / native
       ↕ named pipe                          ↕ named pipe
Python гостя ── намерение по сети ──→ Python хоста
       ↑                               Session + authority
       └── состояние и результаты ────────┘

На схеме сокращены обратные вызовы. Python хоста отправляет операцию в свою X4 и получает наблюдение о результате; его собственный словарь не заменяет состояние движка.

Почему отдельный процесс: сетевые соединения, очереди и ожидание ответов удобнее обслуживать вне UI-потока игры. Named pipe — локальный канал между процессами Windows. Он соединяет игру с её службой; связь между участниками выполняется отдельным транспортом LAN или Steam.

Папки репозитория#

Все пути ниже указаны от D:\X4FoundationsOnline.

Наличие каталога dist в корне проекта и wiki/dist — два разных случая: корневой относится к результатам проекта, второй содержит собранный сайт.

Откуда начинается работа внутри X4#

extension/content.xml описывает расширение и зависимость от X4Native. X4Native — сторонний компонент, а код в native/ — часть нашего проекта. Эти названия не стоит смешивать.

extension/ui.xml задаёт подключение Lua. Сначала идут native_path.lua, основной x4_online.lua, затем вспомогательные модули. Порядок важен: последующие адаптеры используют уже созданный объект X4FO.

В x4_online.lua найди:

X4FO = {state=state, native=native,workClock=native.monotonic}

Это общая таблица приложения: state — состояние адаптера, native — загруженный C-модуль, workClock — часы для измерения работы. Префикс X4FO обозначает наш код, а не встроенную библиотеку X4.

Во многих соседних файлах начало такое:

if not X4FO then return end
local app = X4FO

Читай это как «модуль работает, только если основное приложение существует; дальше используем короткое имя app». Поле app.state.role отличает роль host от join, но окончательный допуск действия не должен зависеть только от клиентской переменной.

Откуда начинается Python#

x4_online/__main__.py разбирает команду запуска. Режим service передаёт управление service.serve; режимы host и join запускают bridge.run. Обычная установка организует запуск службы; это не предложение вручную поднимать второй экземпляр на уже занятом pipe.

Дальше полезны четыре роли:

Снимок для участника собирается в session_snapshot.py. Разбор и отображение форматов движка вынесены также в engine_wire.py и engine_render.py. Не угадывай местоположение по названию: пользуйся поиском конкретного сообщения.

В словаре COMMAND_HANDLERS регистрация вида 'object_rename': handle_object_names означает: при таком типе пакета вызвать указанную функцию. Это механизм нашего проекта, а не синтаксис X4.

Как найти одно игровое семейство#

Семейство здесь — несколько файлов одной механики. У переименования это Lua, MD, Python и тесты с близкими именами. Но совпадение имён — подсказка, а не доказательство, что файл подключён и используется.

Название world не означает «можно отдать всё всем». В проекте физическое представление сектора (physical_world) отделено от личных знаний и доступных данных (personal_world). Видеть геометрию объекта и иметь право видеть его трюм — разные условия.

Ищем от действия, а не читаем подряд#

Команды PowerShell выполняются из корня проекта и только читают файлы. Для rg нужен ripgrep; альтернативный поиск обычно есть в редакторе.

Set-Location D:\X4FoundationsOnline
rg --files extension x4_online tests | rg object_names
rg -n 'requestObjectRename|SetComponentName' extension/ui/x4_online_object_names.lua
rg -n 'OBJECT_RENAME|OBJECT_NAME_EXECUTE' x4_online extension
rg -n 'object_rename|handle_object_names' x4_online/session_commands.py

Алгоритм один: найти обработчик действия → имя исходящего сообщения → получателя → фактическую операцию → обратное чтение → тест. Когда поиск привёл в большой файл, прочитай небольшой участок вокруг найденного имени.

Почему столько проверок и идентификаторов#

request_id отличает одну операцию от другой. Повторная доставка той же операции должна вернуть тот же исход. revision показывает, к какой версии состояния относится запрос. epoch и connection помогают отвергать сообщения прежнего контекста или соединения.

Постоянный ID связывает объект между участниками и загрузками, а локальная ссылка указывает на конкретное представление внутри данного процесса X4. Нельзя передавать число из памяти гостя как универсальный ID хосту. Подробнее — права хоста и журнал запросов.

x4_online/defaults.py содержит подписи нового профиля: Дмитрий, X4FOnline. Это пример маленького и понятного файла, но имя игрока не используется как ключ аутентификации или собственности.

Где кончается этот обзор#

Мы выяснили ответственность частей по исходникам. Это не подтверждает каждый игровой маршрут. Историческое имя документа stage5-* тоже не определяет актуальный этап: области были разделены, а полный порядок записан в roadmap.

Следующий шаг — проследить переименование корабля. Для возврата к последовательности используй стартовую страницу.