gmod-rs/docs/LUA.md

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 сразу» — идём по приоритетам и дампам.