rpg2d

php

Фреймворк 2D MMORPG: исполняет код механик игры в изолированном PHP-процессе на каждой карте и держит её мир — сущности с компонентами и событиями, позиции, тайловую карту и соседние карты открытого мира.

Работает на ~60 FPS. Каждая микросекунда на счету.

The Mana World: порт Тулимшара, открыт инвентарь

Жизненный цикл

  1. Сервер собирает для карты справочники игры (компоненты, группы команд, виды сущностей, префабы, сущности, карты) и код её механик и поднимает процесс песочницы.
  2. Обработчик ошибок переводит в ErrorException любую ошибку PHP, включая замечание (Notice) и устаревание (Deprecated). Файлы библиотек и фреймворка сливаются, сортируются по зависимостям классов и загружаются как PHP-код.
  3. Код инициализации (init.php) оборачивается в замыкание с именованными параметрами и вызывается:
    • объявляет константы окружения (APP_DEBUG, GAME_ID, MAP_ID, STEP и др.);
    • собирает объекты справочников: Component, EventParam → Events → EventGroup;
    • поднимает ComponentCollection и Data (компоненты и уровни сравнения), EventCollection, EntityEventGroup и Frame (группы, паузы и код команд, код кадра), World (код входа и выхода сущностей, код смены положения), Map2D (тайловые карты и соседние карты);
    • добавляет сущности карты в мир (World::add).
  4. PHP::listen() — бесконечный цикл: приём сообщения по IPC → команды игроков и соседних карт → Frame::tick() → пакет изменений обратно серверу.

Время

Время игровых сроков — монотонная шкала Data::monotime(), по ней ведутся все таймеры: сроки событий, отложенное создание сущностей, отметки последней активности, сроки внутри значений компонентов. Системные часы (microtime) годятся только для календарной метки в журнале: их корректирует синхронизация времени, а скачок часов сдвинул бы все игровые сроки разом. Точка отсчёта шкалы берётся при старте процесса карты, у каждого процесса она своя и обычным часам не равна.

Наружу шкала уходит двумя способами: время событий переводится в остаток секунд перед отправкой, а само текущее время карты уезжает игроку полем time (со снимком мира при входе и первой рассылкой после перезапуска карты) — им читатель сопоставляет сроки, лежащие в значениях компонентов.

Основные классы

Ядро

Класс Назначение
Frame Кадр (tick()): собирает сущности кадра, вызывает код кадра игры, создаёт отложенные сущности и запускает команды сущностей по группам в порядке сортировки. Команды сервера до кадра разбирает RemoteCommand, пакет изменений после кадра собирает World
World Реестр всех сущностей на карте. add(), removeEntity(), get(), filter() (поиск сущностей в радиусе). Хранит замыкания кода входа и выхода сущностей, собирает пакет изменений кадра
Data Уникализация пакетов — сравнивает текущее состояние с предыдущим, убирает неизменившиеся данные из пакета обновления. Рекурсивное diff-сравнение
Block Защита от рекурсии и коллизий. Статические флаги, блокирующие определённые операции во время выполнения кода механик

Block — система блокировок

Во время выполнения кода команды нельзя вызывать операции, которые приведут к рекурсии или повреждению данных:

Флаг Что блокирует Зачем
$timeout Запрещает расчёт таймаутов Таймаут вычисляется один раз при добавлении события
$events Запрещает добавлять события Предотвращает зацикливание (событие добавляет событие, которое добавляет событие...)
$objects Запрещает добавлять сущности Предотвращает бесконечное создание объектов из кода команды
$positions Запрещает менять позиции Позиция меняется только в move-механиках
$components Запрещает менять компоненты других сущностей (string = key разрешённой) Предотвращает коллизию: два события одновременно меняют HP одного объекта
$object_change Запрещает менять свойства сущности Во время readonly-операций (отправка пакета)

Block::current() сохраняет текущее состояние в Recover-объект, код устанавливает нужные блокировки, после выполнения — восстанавливает.

Сущности

Класс Назначение
EntityAbstract Базовый класс сущности. Magic __get/__set для свойств (position, forward, map, action). Хранит ComponentCollection и EventCollection
Player Игроки. Метод send() — отправка пакета конкретному игроку. close() — отключение
Entity Все «не-игроки»: животные, враги, объекты окружения (порталы, алтари, снаряды). Различение видов — через поле kind

Компоненты и события

Класс Назначение
ComponentCollection Коллекция компонентов сущности. get(slug), add(slug, value), isset(slug). Проверяет значение по типу компонента и принадлежность компонента типу entity. Копия сущности соседней карты получает лишь изменившееся и сливает его с прежним значением merge() — до глубины сравнения компонента, тем же правилом, что клиент
EventCollection События сущности ($entity->events) и справочник групп (list()). add(group, action, data) — поставить команду, заменив ждущую в группе; push(group, action, data) — поставить за ждущей, так ставят команду другой сущности; сущности другой карты push уходит пакетом, и за ждущей заявку ставит родная карта этой сущности; заявка, не заставшая адресата на его карте, пропадает с записью в журнал предупреждений; за постоянной командой (isPersist) заявка не встаёт — ошибка. get(group), remove(group)
EntityEventGroup Группа команд одной сущности: одно ждущее событие и очередь заявок за ним; очередь не сохраняется и с сущностью на другую карту не уходит. finish() — завершить текущую, следующая заявка очереди становится текущей; remove() — снять текущую вместе с очередью. Управляет таймаутами и пересылкой данных
EntityEvent Одно событие в очереди: action, time, data, from_client

Позиционирование

Класс Назначение
Position Координаты (x, y, z). tile() — округление до клетки. distance() — расстояние до другой позиции
Forward Направление взгляда (x, y, z): ненулевой вектор длиной не больше единицы, каждая составляющая от −1 до 1; диагональ — (0.71, 0.71). Длину направления, присланного значением (команда игрока и т.п.), конструктор проверяет в любом режиме, направления, читаемого у сущности, — лишь под APP_DEBUG
Map2D Тайловая карта. getCurrentMapTiles() — проходимые клетки. Данные соседних карт для бесшовного мира

Системные

Класс Назначение
PHP Точка входа. listen() — IPC receive/send цикл. log() — запись в журнал
Channel Очередь команд песочницы серверу карты: сообщение игроку, создание сущности на соседней карте, пакет изменений кадра. Очередь уходит серверу в конце кадра
IPCQueue Очередь сообщений IPC между песочницей и сервером своей карты: упаковка сообщения и разбиение длинного на части
RemoteCommand Разбор команд сервера: вход и выход игроков, команды игроков, пакеты и доступность соседних карт
Perfomance Замеры производительности: FPS, время обработки пакетов, размеры пакетов

Перечисления

Значения — в коде перечислений (enum/).

Enum Назначение
EntityTypeEnum Вид записи сущности: игрок либо прочая сущность
EntityChangeTypeEnum Группа рассылки изменений сущности
SystemActionEnum Системное действие сущности
ComponentTypeEnum Тип значения компонента
ComponentListEntityTypeEnum Виды сущностей, по которым отбирается перечень компонентов
EventSendingEnum Уровень пересылки данных события клиентам

Поток данных (один кадр)

IPC receive (кадр: команды игроков и пакеты соседних карт)
    ↓
RemoteCommand: player_add / player_command / update_from_remote_location
    ↓
Frame::tick()
    ├── Собрать сущности кадра: живые (lifeRadius) текущей карты и соседи в их радиусе
    ├── Вызвать tick-код (код кадра игры) — до команд
    ├── Создать отложенные сущности (World::releaseDelayed)
    └── Для каждой группы команд в порядке сортировки — для каждой сущности кадра:
        └── Время пришло → finish() группы → код команды (closure)
            ├── Block разрешает менять только эту сущность
            └── Block снимает блокировки
    ↓
Собрать пакет изменений кадра
    ↓
IPC send (пакет изменений → сервер для рассылки игрокам и соседним картам)

Правила для кода механик

  • Код механик не имеет доступа к файловой системе, сети, БД — только к API фреймворка
  • Любая ошибка (включая Warning) останавливает всю карту, кроме ошибки в коде команды игрока этой карты: такую фреймворк пишет в журнал предупреждений и отключает этого игрока, карта работает дальше
  • Не использовать @ для подавления ошибок — проверять через isset()
  • Кешировать повторные обращения в локальные переменные (60 FPS = каждый вызов функции на счету)
  • Команду другой сущности ставить push, не add: заменой вторая заявка того же кадра стёрла бы первую. add — когда новая команда по смыслу отменяет ждущую (следующий шаг ходьбы, повтор подхода) либо совпадает с ней. За постоянной командой (isPersist) — add либо своя группа: push за ней отказывает ошибкой
  • Заявка, вставшая в очередь, проверяет своё условие при срабатывании: цель к тому времени бывает мертва либо ушла
  • Заявку, которую за ждущей без порчи не применить, считать после срабатывания ждущей либо отклонить тихо — return с $object->warning(...) до любого списания; тихий отказ законен у любой команды, его называет описание отказывающей команды

Библиотеки

Библиотек фреймворк не знает и без них поднимается. Что он открывает библиотекам: матрицу проходимости целиком (Map2D::terrain — её при первом поиске берёт библиотека поиска пути), принадлежность двух точек одной связной области (Map2D::sameArea), разделитель координат позиции (Position::DELIMETR), журнал (PHP) и замер производительности (Perfomance). Манифеста зависимостей у библиотек пока нет: что библиотека берёт у фреймворка, описано словами в её описании.

Цена кадра
0.004 + 0.0004 * (entities + players + foreignAlive) + (players + alive + foreignAlive) * (0.005 + 0.0001 * Math.min(entities + players + foreignAlive, (2 * lifeRadiusMax + 1) * (2 * lifeRadiusMax + 1)))
Миллисекунд на один проход, без цены механик: работу самих команд оценивает игра, а не фреймворк. Цена записана формулой, потому что зависит от обстановки на карте — сколько там игроков, прочих сущностей и запущенных соседних карт. Сколько раз в секунду проход случается, задаёт сама игра своей частотой кадра.
Величины обстановки, доступные формуле:
players — сколько игроков на карте
alive — сколько сущностей на карте, кроме игроков, живёт полной жизнью — двигается и думает
entities — сколько на карте сущностей, кроме игроков, вместе со спящими
inRadius — сколько сущностей, кроме игроков, в среднем попадает в область обзора игрока, выставившего самый дальний обзор
targets — сколько живых — игроков и прочих сущностей — в среднем попадает в эту область
walkable — сколько на карте проходимых клеток
neighbours — сколько соседних карт запущено рядом
foreignAlive — сколько живых на запущенных соседних картах: карта видит их всех и собирает вокруг каждого соседей, но думают и двигаются они на своей карте
fps — сколько кадров в секунду считает карта
lifeRadiusMax — до скольких клеток сервер разрешает радиус жизни любой сущности, игрока тоже; число одно на все игры сервера. Это не радиус того, кто выполняет команду: его радиус бывает меньше, а игра может задать своим сущностям и игрокам пределы уже этого

Бесплатно

Отдельно не устанавливается — приходит с игрой Git-репозиторий
Используется в играх