Создание модуля: от исследования до выпуска
Полный порядок работы над надёжным игровым модулем: исследование, проверка на настоящем сервере, переносимые среды выполнения, изоляция, режимы консоли и проверка на настоящем ПК.
Создание модуля: от исследования до выпуска
Руководство по разработке модулей описывает, что входит в модуль. Эта страница описывает, как сделать модуль, который работает на настоящем ПК.
Модуль, который проходит все модульные тесты, всё равно может не работать на настоящем сервере. Пример — модуль Terraria. Он прошёл все модульные тесты и все проверки соответствия. На настоящем сервере в нём нашлось девять дефектов. Эта страница показывает порядок работы, который находит такие дефекты до выпуска.
1. Правила проектирования
Эти правила действуют для каждого модуля.
- Работу выполняет демон. Модуль только описывает игру. Не обходите контракт демона. Если в контракте нет нужной функции, сначала добавьте в демон общую точку расширения.
- Не ветвитесь по названию игры. В демоне и общих помощниках нет названий игр. Используйте ключи
module.toml, хуки и слоты. - Одна и та же среда выполнения везде. Не используйте среду выполнения, установленную на ПК. Модуль скачивает фиксированную версию и кладёт её в папку сервера (раздел 5).
- Каждое значение в одном месте. Значение настройки по умолчанию берётся из одного файла: файла, который создаёт игра, или файла-примера из загрузки.
- Весь текст для пользователей — в
locales/.en.json— эталонный файл.
2. Исследование игры
До написания кода создайте таблицу исследования в <game>/RESEARCH.md. Для каждого пункта укажите источник. Укажите также, документ это или измерение. Если источник не найден, оставьте пункт пустым и напишите «не проверено». Не угадывайте значения.
| Пункт | Где искать |
|---|---|
| Исполняемый файл сервера, аргументы запуска, порты по умолчанию | Официальные документы, справка сервера, скрипты запуска из загрузки |
| Все команды и их аргументы | Официальные документы по командам и вывод команды сервера help. Сравните их построчно |
| Все настройки (ключ, формат, диапазон, значение по умолчанию) | Файл настроек по умолчанию, который создаёт сервер. Если сервер его не создаёт, — файл-пример из загрузки |
| Синтаксис и кодировка файла настроек | Исходные байты этого файла |
| Сохранения мира и резервные копии, которые создаёт игра | Список файлов после запуска сервера и сохранения мира |
| Сообщения о готовности, остановке, входе и выходе | Исходный вывод консоли. Проверьте также, переводит ли эти сообщения языковая настройка сервера |
| Способ установки и проверка файлов | Официальный адрес загрузки и официальная контрольная сумма. Если суммы нет, напишите «нет» и источник |
| Требования к среде выполнения | Ссылки исполняемого файла сервера и официальные документы. Найдите то, чего нет в загрузке |
| Файлы вне папки экземпляра | Изменения в домашней папке и папке «Документы» после запуска сервера |
Вики может описывать старую версию. В вики Terraria есть команда death. Сервер Terraria 1.4.5.8 отвечает на неё «Invalid command.».
3. Изучение настоящих файлов
Если сервер можно скачать, изучите файлы сами.
- Выведите все элементы архива. Проверьте, есть ли папка для каждой операционной системы и встречается ли одно имя исполняемого файла в нескольких папках. В архиве Terraria файл
TerrariaServer.exeесть и в папкеLinux/, и в папкеWindows/. - Прочитайте файлы по умолчанию побайтно. Определите кодировку (UTF-8, BOM, cp1252), концы строк (LF, CRLF), закомментированные ключи-примеры и строки, которые не являются комментариями.
- Добавьте закомментированные ключи-примеры в список настроек. Строка, которая не является комментарием, задаёт значение по умолчанию.
4. Запуск настоящего сервера
Запустите сервер так же, как демон: подключите stdin и stdout через каналы (pipe). Запишите исходный вывод. Если среда сборки может запустить только сборку сервера для другой операционной системы, запустите её. Команды, сообщения и сохранение одинаковы, когда код игры один и тот же.
Запишите следующее:
- Строку готовности, строку после команды остановки и время сохранения.
- Вывод
help. Отправьте каждую команду, которую упоминает только документ, и запишите ответ. - Приглашение консоли. Некоторые серверы выводят его без перевода строки, и следующая строка начинается с приглашения. Terraria выводит
: Server started. - Ответ на команду, отправленную через канал. Если сервер не отвечает, проверьте снова с псевдоконсолью (раздел 7).
- Сообщения о готовности и остановке для каждого языка сервера.
- Файлы, которые сервер создаёт при запуске и сохранении. Terraria создаёт
world.wld.bakиworld.wld.bak2.
Для некоторых пунктов нужен игровой клиент, например для сообщений о входе и цели для кика. Оставьте такие пункты пустыми и напишите «не измерено».
5. Требования к среде выполнения: переносимые и фиксированные
Некоторым серверам нужна среда выполнения, которой нет в загрузке, например Java, XNA Framework или среда Visual C++. Не используйте среду, установленную на ПК. На каждом ПК её версия может быть разной.
Порядок действий:
- Запишите в таблицу исследования адрес, размер, подпись и SHA-256 официального файла.
- Найдите минимальный набор файлов, нужных серверу. Запустите сервер только с этими файлами, чтобы подтвердить набор. Для Terraria это четыре сборки XNA (
Microsoft.Xna.Framework,.Game,.Graphics,.Xact),XnaNative.dll,msvcr100.dllиmsvcp100.dll. - В
install_serverскачайте фиксированную версию. Сравните файл с официальной контрольной суммой. Если её нет, сравните с SHA-256, записанным для файла с действительной подписью издателя. - Положите только нужные файлы в папку сервера или экземпляра. Запускайте сервер с этим путём.
- В
validateпроверьте наличие этих файлов. Если какого-то нет, верните проблему сseverity: "critical"и отдельнымcode. Попросите пользователя переустановить сервер.
Не используйте права администратора, установку на всю систему и службы Windows.
Ограничение: .NET Framework сначала загружает сборку из глобального кэша сборок (GAC), если там есть то же имя и та же версия. Нативные DLL сначала загружаются из папки сервера.
6. Изоляция
В Windows модуль, полученный не из подписанного каталога Saba-chan, работает в Windows AppContainer. Каждый новый модуль работает в этой изоляции. Проверьте модуль в изоляции до открытия pull request.
В изоляции недоступно следующее:
| Недоступно | Что использовать |
|---|---|
| Подключения к loopback (API демона, REST API игрового сервера) | daemon_stdin_command, daemon_rest, loopback_http, loopback_exchange. Демон передаёт запрос |
Windows Installer (msiexec завершается с ошибкой 1601) и другие службы | Читайте установочный файл (MSI, CAB) средствами Python |
Папка, которую tempfile.mkdtemp создаёт в папке экземпляра | tempfile.mkstemp или папка, созданная через os.mkdir. Начиная с Python 3.13, mkdtemp даёт доступ только текущему пользователю, и изолированная учётная запись не может писать в эту папку |
| Запись вне разрешённых папок | Папки экземпляра, рабочая и установки, а также папки из data_roots |
Если общий помощник не работает в изоляции, не обходите сбой в модуле. Сообщите о нём как о проблеме демона.
7. Режимы консоли
По умолчанию демон подключает stdin и stdout сервера через каналы ([launch] console = "pipe"). Некоторые серверы ведут себя иначе, когда stdin — канал:
- Palworld накапливает вывод до остановки.
- Сервер Terraria для Windows не читает ввод из канала. Он не ответил ни на команды, ни на
exit. Демон принудительно остановил его через 60 секунд, без сохранения.
Для таких серверов задайте [launch] console = "pty". Тогда демон запускает сервер в псевдоконсоли (Windows ConPTY, pty в Unix).
Псевдоконсоль повторяет каждую отправленную команду. Переносы строк тоже могут измениться. В псевдоконсоли Terraria выводит приглашение : и Server started на разных строках. Пишите шаблоны для обоих случаев.
8. Шаблоны консоли
Пишите шаблоны готовности, входа, выхода и остановки только по измеренному выводу.
- Шаблоны готовности, входа и выхода помещайте в
[extensions.saba-core](ready_patterns,player_join_patterns,player_leave_patterns). Шаблон остановки — в[detection] graceful_exit_patterns. - Привязывайте каждый шаблон к началу и концу строки. Строка чата с теми же словами не должна совпадать, например
<Server> Server started. - Если перед сообщением может стоять приглашение, принимайте его через
^(?:<приглашение>)?. - Если языковая настройка сервера переводит сообщение, добавьте измеренное сообщение для каждого языка. Если добавить только английский, демон не увидит готовность сервера с другим языком.
- Добавьте тест. Измеренные строки должны совпадать с приглашением и без него. Строка чата не должна совпадать.
9. Установка и файлы настроек
Установка:
- Если в архиве есть папка для каждой операционной системы, выбирайте папку по названию операционной системы. Не выбирайте её по имени исполняемого файла, длине пути или первому элементу. Если папки нет или их больше одной, верните ошибку.
- Не заменяйте существующие настройки и миры. Распаковывайте файл настроек-пример, только если файла настроек ещё нет.
- Проверяйте каждый скачанный файл. Для каждого двоичного файла используйте официальную контрольную сумму. Если её нет, используйте HTTPS к фиксированному официальному хосту, CRC архива и наличие ожидаемого исполняемого файла. Запишите в таблицу исследования «нет официальной контрольной суммы» и источник. Не придумывайте сумму и не берите её из источников сообщества.
Файлы настроек:
- Читайте и записывайте файл по официальному синтаксису его формата. Например, в файлах Java
.propertiesесть экранирование\:и\=, а\в конце строки продолжает строку. - Не предполагайте кодировку. Читайте файл в его настоящей кодировке и записывайте обратно в той же кодировке и с теми же концами строк. Файл
serverconfig.txtTerraria для Windows использует cp1252, и в комментарии у него есть байт 0x92. Модуль, который читает только UTF-8, не может ни запустить этот сервер, ни сохранить его настройки, ни импортировать их. - Меняйте только изменившиеся ключи. Сохраняйте остальные ключи, комментарии и порядок.
- Если файл не удалось прочитать, не записывайте его. Отсутствующий файл, нечитаемый файл и файл, который нельзя разобрать, — три разных случая.
10. Тесты
Модульные тесты и набор проверок соответствия работают без изоляции и с файлами-образцами. Они не находят проблем, которые возникают только с настоящей загрузкой, в изоляции, в режиме консоли или в Windows. Выполняйте все три уровня тестов.
10.1 Модульные тесты
- Напишите тест для каждой функции в
test_lifecycle.pyдо того, как напишете функцию. - Запустите тест и убедитесь, что он не проходит.
- Напишите функцию.
- Выполните проверки:
saba-core module validate mygame
saba-core module audit mygame
pytest conformance --module path/to/mygame --shared-libs path/to/saba-chan/modules
10.2 Проверка на настоящем сервере (до pull request)
После раздела 4 вызовите функции модуля на настоящей папке сервера.
- Выполните
install_serverс настоящей загрузкой. Убедитесь, что в папке только файлы для этой операционной системы. - Запустите сервер командой из
get_launch_command. Убедитесь, что шаблон готовности совпадает. - Отправьте каждый шаблон команды. Убедитесь, что сервер его принимает.
- Отправьте команду остановки. Убедитесь, что сервер сохраняется и останавливается.
- Сравните пути из
backup_pathsиreset_serverс файлами, которые создал сервер.
10.3 Проверка на настоящем ПК
Используйте обычную установку Saba-chan на ПК с Windows. Новый модуль работает в изоляции, поэтому эта проверка находит и проблемы изоляции.
- Скопируйте папку модуля в
modules\<имя>\в папке данных Saba-chan. - Выполните
saba-chan-cli module refresh. - Выполните
saba-chan-cli server add <сервер> -m <модуль>. - Запустите сервер. Убедитесь, что Saba-chan показывает готовность.
- Отправляйте команды через
saba-chan-cli run <сервер> <команда>. Читайте ответы черезsaba-chan-cli server console <сервер> --print. - Измените настройку и перезапустите сервер. Убедитесь, что сервер использует новое значение.
- Создайте резервную копию через
saba-chan-cli backup create <сервер>. Изучите файлы в копии. - Остановите сервер. Убедитесь, что Saba-chan записал обычную остановку и сохранение мира на месте.
- Сбросьте мир. Посмотрите, какие файлы удалены, а какие остались.
Если [module.dependencies] saba-core требует версию, которая ещё не выпущена, обычная установка не загружает модуль. Проводите проверку на ПК после выпуска этой версии. Не понижайте версию в зависимости.
11. Контрольный список перед pull request
- В
RESEARCH.mdу каждого пункта есть источник, и у каждого источника указано «документ» или «измерение». - Вы изучили элементы архива и исходные байты файлов по умолчанию.
- Вы запустили настоящий сервер и записали исходный вывод, вывод
helpи файлы после сохранения. - Каждая объявленная команда есть в выводе
help. - Сервер отвечает на команды. Если нет, задано
[launch] console = "pty". - Каждый шаблон консоли взят из измеренного вывода и принимает приглашение и каждый перевод.
- Каждая среда выполнения — фиксированная переносимая версия, и модуль проверяет скачанные файлы.
- Установка распаковывает только папку для этой операционной системы.
- Файл настроек сохраняет кодировку и концы строк.
- Сброс мира удаляет только файлы, созданные сервером, включая его резервные копии.
- Модуль не использует
msiexec, службы Windows, папкиmkdtempи прямые подключения к loopback. - Вы провели проверки на настоящем сервере и на настоящем ПК или записали каждую проверку, которую не удалось провести.