С чего начать именно тебе#
Цель первого прохода — понять, где рождается действие игрока, кто разрешает его выполнить и где появляется настоящий результат. Для этого не нужно сразу читать весь проект. Начни с одной небольшой цепочки и научись находить соседние файлы.
В этой вики X4Online, X4FO и X4FoundationsOnline обозначают наш проект. Папка проекта — D:\X4FoundationsOnline. Код и ограничения сверены по рабочей копии 26 октября 2026 года: кандидат 0.70.28, игра X4 9.00 (611726). Незакоммиченные изменения тоже могут быть новее последнего коммита.
Что представляет собой мод#
X4FO строит кооператив вокруг мира хоста. Хост — участник, чья X4 ведёт общую симуляцию. Гость получает доступное ему состояние и отправляет намерения: «переименовать корабль», «купить товар», «изменить приказ».
Слово «намерение» важно. Гость не сообщает хосту готовый факт «я уже списал деньги». Он просит выполнить действие. Хост проверяет права и актуальность, а операция должна дойти до настоящего движка X4.
Штатные игровые действия остаются в обычных окнах, кнопках и контекстных меню X4. Отдельный интерфейс уместен для новых сетевых функций: подключения, чата, списка игроков и netgraph. Netgraph показывает состояние соединения.
Маршрут чтения по порядку#
Время ниже — ориентир для спокойного первого знакомства. Можно пройти маршрут за несколько подходов и возвращаться к исходникам позже.
| Шаг | Что открыть | Что должно стать понятно |
|---|---|---|
| 1 · 15–25 минут | Как работает код X4 | Данные, MD, AI и Lua выполняют разные роли |
| 2 · 20–30 минут | Операторы и основные функции | Как читать local, $Value, do_if, таблицы и события |
| 3 · 15–20 минут | Карта кода X4FO | Какие папки нужны для конкретной задачи |
| 4 · 25–40 минут | Путь переименования корабля | Как одно действие проходит через все основные слои |
| 5 · 20–30 минут | Как читать Python нашего мода | Что делают классы, словари, проверки и request/pump/observe |
| 6 · 20–40 минут | Первая самостоятельная задача | Как выбрать небольшое изменение и проверить его |
Если программирование совсем новое, на первом проходе достаточно шагов 1–3. Затем возвращайся к переименованию и держи рядом памятку синтаксиса.
Что открыть в редакторе первым#
Для поиска конкретного имени теперь есть справочник вызовов и событий X4FO: параметры, отправители, получатели и примеры подписок. Если последовательный курс пока понятнее, продолжай шаги ниже и используй справочник по мере необходимости.
wiki/content/x4fo-rename-walkthrough.md— объяснение цепочки.extension/ui/x4_online_object_names.lua— обработка обычного переименования в UI.x4_online/object_names.py— допуск запроса и ожидание результата.extension/md/x4_online_object_names.xml— операция над объектом мира.tests/test_object_names.py— примеры допустимых запросов, повторов и отказов.
Не начинай с полного чтения session.py, bridge.py или native/attention.cpp: в них много связей, смысл которых станет понятен после небольшого семейства. Позже открывай в больших файлах только найденный обработчик.
Внизу статей есть блок «Источники и проверка». Он открывает текстовые снимки перечисленных файлов. Они обновляются при сборке вики; для изменения кода используй исходный файл в репозитории. Номер строки может поменяться, поэтому в курсе даны имена функций и строки для поиска.
Чего не следует выводить из наличия кода#
Сейчас подготовлен код этапов 5–11, но общая игровая приёмка остаётся открытой. Последний кандидат добавляет доставку запасов NPC-станций и доступных трюмов; приёмка этой редакции также открыта. Материалы курса объясняют устройство кода и не принимают этапы разработки.
Нужно различать три результата:
| Результат | Что он действительно показывает |
|---|---|
| Нашли функцию в исходнике | Есть предполагаемый путь исполнения |
| Прошёл автономный тест | В проверенных входах сработал контракт модели или адаптера |
| Проверили эффект в двух X4 и восстановление | Подтверждён конкретный игровой сценарий указанной версии |
Актуальные ограничения читай в снимке status. Там важнее верхний текущий пакет, а исторические результаты относятся к своим версиям. Полный порядок ручной разработки есть в developer-guide.
Небольшой словарь перед чтением#
| Термин | Простыми словами |
|---|---|
| Хост | Участник, чья игра ведёт общий мир |
| Гость | Подключённый участник со своим клиентским представлением |
| Intent | Запрос на действие, ещё не подтверждённый факт |
| Authority | Код, который проверяет право и условия выполнения |
| Adapter | Переход между двумя способами работы: например, UI и протоколом |
| IPC | Обмен процессов на одном компьютере; в проекте используется named pipe |
| Snapshot | Снимок состояния; дельта передаёт изменения к нему |
| Readback | Независимое чтение того, что получилось в движке |
| ACK | Подтверждение конкретного этапа доставки или применения |
| Revision | Номер версии состояния, позволяющий заметить устаревший запрос |
| Epoch | Маркер текущего контекста мира/сессии, защищающий от старых сообщений |
Имя — подпись для человека. Постоянный ID — ключ для связи объектов и владения. Имена могут совпадать. Для нового профиля начальные подписи — Дмитрий и X4FOnline; они не должны перезаписывать сохранённые пользовательские имена.
Как понять, что старт пройден#
Попробуй без подсказки ответить: какой файл принимает переименование, где проверяются права, какая инструкция меняет реальный объект и откуда гость узнаёт новое имя. Если ответы находятся в исходниках, у тебя уже есть рабочий способ изучать проект.
Дальше переходи к карте кода или сразу к переименованию. Возвращаться на эту страницу можно из каждого нового материала курса.