81 lines
6.7 KiB
Markdown
81 lines
6.7 KiB
Markdown
# Lua-рантайм Source RS
|
||
|
||
## 1. Базовая линия
|
||
|
||
- GMod использует **LuaJIT** (семантика Lua 5.1) → берём `mlua` с feature
|
||
`luajit` + `vendored`, JIT включён.
|
||
- Понимание реальности: **PAC3 и Starfall — это аддоны, исполняемые в GMod Lua.**
|
||
Starfall дополнительно тащит внутрь собственный Lua-интерпретатор. Значит,
|
||
«поддержать Starfall/PAC3» = реализовать движковый API (`render`, RT, кости,
|
||
материалы, meshes), который эти аддоны вызывают; их собственную логику пишем не мы.
|
||
- Источники требований:
|
||
- дампы клиентского Lua с реальных серверов через `~/glua-steal` (gluasteal);
|
||
- wiki.facepunch.com/gmod;
|
||
- базовые lua-файлы из установки GMod (референс bootstrap-порядка);
|
||
- наш инструмент `lua-api-report` (сканирует дампы и строит рейтинг используемых,
|
||
но не реализованных API).
|
||
|
||
## 2. Порядок реализации
|
||
|
||
| Очередь | Цель | Ключевые модули |
|
||
|---|---|---|
|
||
| 1 | HUD/UI аддоны сервера | `hook`, `net`, `timer`, `util`, `concommand`, `surface`, `draw`, `render`, `cam`, `input`, `render targets` |
|
||
| 2 | Derma-меню | `vgui`, `derma`, шрифты, layout, анимации, клиппинг, скролл |
|
||
| 3 | PAC3 | кости/аттачменты моделей, RT, материал-оверрайды, цвет/материалы, бюджеты |
|
||
| 4 | Starfall (клиентсайд) | API-паритет с тем, что использует аддон; усиленный sandbox |
|
||
|
||
Правило: API строится «рельсами» — каждый модуль регистрируется декларативно
|
||
(функции, сигнатуры, проверки аргументов), чтобы добавлять покрытие быстро и единообразно.
|
||
|
||
## 3. Sandbox (защита от крашедла)
|
||
|
||
Цель: аддон/сервер не может уронить клиент.
|
||
|
||
1. **Память:** лимит на Lua-state (аллокатор-встрел), счётчики по аддонам.
|
||
2. **Время/инструкции:** count-hook (например, каждые N тысяч инструкций) + watchdog-поток;
|
||
превышение → ошибка «больше функций недоступно этому файлу», файл помечается опасным.
|
||
Примечание: включение хуков на функциях отключает JIT для них — поэтому хуки
|
||
активны только для **недоверенного серверного** кода; локальный код может
|
||
исполняться без хуков (конвар).
|
||
3. **Запреты:** `io`, `os` (кроме безопасного минимума), `ffi`, `require` вне whitelist,
|
||
`debug` (или строго ограниченный), path traversal при любых файловых API.
|
||
4. **Лимиты ресурсов:** размеры render targets, количество материалов/мешей/партиклов/
|
||
таймеров на аддон; квоты на кадр.
|
||
5. **Изоляция ошибок:** каждый hook/колбек в `catch_unwind`; ошибка Lua не роняет кадр;
|
||
после N ошибок колбек отключается (как в GMod сообщение в консоль).
|
||
6. **Safe mode:** перед загрузкой файла пишем маркер «сейчас грузится X»; если прошлый
|
||
запуск завершился нечисто — X в чёрный список, клиент стартует без него и сообщает.
|
||
7. **Chaos-тесты:** бесконечный цикл, рекурсия, гигабайтный mesh, битый RT,
|
||
thousands of timers, path traversal — всё в CI.
|
||
|
||
## 4. Загрузка кода с сервера
|
||
|
||
- Lua-файлы приходят по сетевому каналу GMod (LZMA); храним в download-кэше по хэшу.
|
||
- Загрузка — только из разрешённых корней («lua/», «addons/…»), никаких абсолютных путей.
|
||
- Порядок bootstrap — как в GMod: engine/gamemode-файлы сервера, затем `lua/autorun`,
|
||
затем клиентские аддоны; ошибки любого файла — не фатальны.
|
||
- Повторный заход на сервер не качает то, что уже в кэше (см. `NETWORK.md`).
|
||
|
||
## 5. Мосты к движку
|
||
|
||
- **Vector/Angle:** userdata с метатаблицами как в GMod (арифметика, методы).
|
||
- **Entity-фасад:** ленивое создание Lua-объекта сущности; `GetPos/SetPos/GetAngles…`;
|
||
в hot paths — никаких аллокаций, если аддон не трогает сущность.
|
||
- **net:** `net.Start/Write/Read/Receive` с совместимой сериализацией и stringtable-сжатием имён.
|
||
- **render targets:** объекты с лимитами и учётом VRAM; `cam.Start3D2D`, `render.SetRenderTarget`.
|
||
- **Материалы:** `Material()`, `CreateMaterial`, `render.SetMaterial`, blend-режимы — строго
|
||
с compat-семантикой рендера.
|
||
- **Meshes (для Starfall/аддонов):** VertexBuffer/ObjectBuffer API (если требуется аддонами).
|
||
|
||
## 6. Производительность Lua
|
||
|
||
- LuaJIT + минимум C-мостов в hot paths (batch-вызовы, кэш userdata).
|
||
- Hooks: быстрый вызов по числовому ID; списки — массивы без аллокаций.
|
||
- Тяжёлые аддоны: опционально выносить в отдельные состояния/потоки (архитектурная
|
||
заготовка с M7), но по умолчанию — как в GMod (главный поток).
|
||
|
||
## 7. Что честно не обещаем
|
||
|
||
- 1:1 Derma во всех деталях с первого раза — итерации по реальным аддонам.
|
||
- Нативные бинарные модули Lua (`.dll`/`.so` аддонов) — не поддерживаем.
|
||
- Полный паритет API «всё из wiki сразу» — идём по приоритетам и дампам.
|