Фреймворк 2D MMORPG: исполняет код механик игры в изолированном PHP-процессе на каждой карте и держит её мир — сущности с компонентами и событиями, позиции, тайловую карту и соседние карты открытого мира.
Работает на ~60 FPS. Каждая микросекунда на счету.
Жизненный цикл
Сервер собирает для карты справочники игры (компоненты, группы команд, виды сущностей, префабы, сущности, карты) и код её механик и поднимает процесс песочницы.
Обработчик ошибок переводит в ErrorException любую ошибку PHP, включая замечание (Notice) и устаревание (Deprecated). Файлы библиотек и фреймворка сливаются, сортируются по зависимостям классов и загружаются как PHP-код.
Код инициализации (init.php) оборачивается в замыкание с именованными параметрами и вызывается:
объявляет константы окружения (APP_DEBUG, GAME_ID, MAP_ID, STEP и др.);
собирает объекты справочников: Component, EventParam → Events → EventGroup;
поднимает ComponentCollection и Data (компоненты и уровни сравнения), EventCollection, EntityEventGroup и Frame (группы, паузы и код команд, код кадра), World (код входа и выхода сущностей, код смены положения), Map2D (тайловые карты и соседние карты);
добавляет сущности карты в мир (World::add).
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). Манифеста зависимостей у библиотек пока нет: что библиотека берёт у фреймворка, описано словами в её описании.