Перейти к содержанию

Архитектура проекта

База исходников: локальная 2.6.0, dev на 463d21ca (2026-11-14), плюс инженерный аудит Core. Тег 2.5.1 — a7f2d9da; дальнейшие изменения ветки выделены в истории. Описание относится к репозиторию: оно не означает, что все коммиты уже опубликованы в Workshop.

Области выполнения

Область Ответственность Загрузка
Сервер Популяция, тело/мозг, ИИ, навигация, урон, розыск/арест, медики, провайдеры транспорта sv_ и серверные ветви sh_
Клиент Меню, голоса/субтитры, визуальная толпа, HUD розыска, редактор/отладка cl_ и клиентские ветви sh_
Общий код Классы, конфигурация, определения API, сериализация, полученные записи акторов sh_; данные каждого Lua-окружения независимы

Префикс файла определяет загрузку, а не возможность управлять NPC на клиенте. См. справочник по областям.

Порядок загрузки

lua/autorun/background_npcs.lua отправляет и включает background_npcs_core/sh_init.lua. Загрузчик сортирует файлы, обходит в каталоге sh_, sv_, cl_, затем подкаталоги; повторные явные включения исключаются. Языки реплик и переводы опций меню подключаются вручную. tests/ только отправляется клиентам; его подключают bgn_selftest / bgn_selftest_cl при запуске.

  1. Ядро: уведомления, классы, сеть, утилиты, планировщик, остальные помощники.
  2. Конфигурация, акторы, реплики, состояния; пользовательский config, адаптер старого конфига.
  3. API, cvars, команды; пользовательский preload, снимок настроек по умолчанию.
  4. Класс актора, компоненты, адаптеры тела, события, обновление, синхронизация.
  5. Навигация, провайдеры, ввод/вывод; провайдер DV.
  6. Команды/розыск, модуль ареста, остальные системы; мозги, спавнеры, интеграции.
  7. Языки меню, интерфейс, отладка; пользовательский postload, BGN_PostLoadScripts.

Порядок важен: обработчики нарушителей и состояний сохраняют ссылку на зарегистрированный модуль ареста. bgn_scripts_reload повторяет загрузку; для чистой проверки изменённых тел и состояния мира нужна перезагрузка карты.

Общий счётчик UID переживает reload; SERVER использует его же для монотонных номеров снимков. CLIENT помечает удалённого актора до отложенной регистрации. Тик планировщика обходит снимок ID задач, поэтому удаление/замена не нарушает обход. Постоянные службы сами повторяют цикл; возврат из задачи завершает её. См. контракты и ограничения аудита.

Файлы и ответственность

Пути ниже относительно корня репозитория. Внутри lua/background_npcs_core/:

Путь Назначение и связи
sh_init.lua Версия, хранилища, порядок загрузки.
core/ Классы, бюджет задач, сетевой кодек/чанки, cvars/команды, запуск самопроверок (bgNPC.Test), уведомления, утилиты.
config/ Настройки; actors/ — типы/наследование, states/ — данные диалогов/сцен/ареста, replics/language/ — реплики/голоса.
custom_modules/config, preload, postload Этапы расширения; файлы отдельного аддона доступны через объединённые Lua-пути GMod.
api/ Реестры акторов, конфиг, точки, состояния, режимы, видимость, статистика, проверки, бой. compat/sh_legacy.lua — старые вызовы через двоеточие.
cvars/, commands/ Регистрация настроек, значения по умолчанию, административные действия.
actor/sh_actor.lua, components/ Идентичность/здоровье/жизненный цикл; состояния, враги, цели, команды, движение, оружие, анимации, речь, транспорт.
actor/body/ Серверные адаптеры NPC/NextBot к движку.
actor/update, events, sync Обновление симуляции, урон/смерть/сохранение, сетевые снимки и привязка клиента.
nav/ Фасад провайдеров, граф/A*, custom/navmesh/nodegraph; generator/ — генерация, io/ — редактор/сохранение/компиляция/дубликации, legacy/ — конверсия.
brain/fsm/, brain/goap/ Выполнение состояний и планирование боя; состояния вызывают Actor, тело выполняет движковые действия.
spawner/ Проверки видимости, создание/рециклинг популяции, отдельные радиусы машин, подкрепление погони, очистка.
systems/ Розыск/арест, нарушители, медики/тела, команды/общие враги, войны/помощь/группы банд и пауза стычек, диалоги, сиденья, сцены, толпа, режимы.
modules/ Необязательные интеграции DV, DarkRP, StormFox, NPC-моды. dv/ — доступ, манёвры машин, обход пешеходами, возврат, урон.
ui/ Меню настроек, Classic-панели, мастер/приветствие, spawnmenu, обновления, переводы.
debug/ Подписки администратора на UID и ограниченный журнал решений/зрения/сигналов (SERVER); кеш mesh/HUD, камера и маркеры сцен/рук (CLIENT); диагностика и автоматические проверки.
tests/ Самопроверки чистой логики, разделённые по префиксу реалма (sh_, sv_, cl_). С аддоном не загружаются: bgNPC.Test.Run подключает их при каждом запуске bgn_selftest (SERVER) / bgn_selftest_cl (CLIENT), поэтому исправленные тесты работают без смены карты. Тест читает только публичные поля; нужный ему помощник выносится в поле модуля с комментарием read by tests/.

Остальная структура:

Путь Содержимое
lua/entities/ NextBot и сущности/контроллеры DV; область задают init/shared/client-файлы сущности.
lua/weapons/ Инструменты, в том числе редактор маршрутов.
lua/autorun/ Начальное подключение аддона.
lua/ulx/ Необязательная административная интеграция ULX.
materials/, models/, sound/, resource/ Графика, модели/скины банд, голоса, локализация интерфейса.
tools/ Python-регрессии, добровольно запускаемые DV-фикстуры/клиент моста, генераторы ассетов/голоса. Игра автоматически их не загружает.
docs/, mkdocs.yml, requirements-docs.txt Исходники EN/RU, навигация/переводы, зависимости сборки.
.github/ CI и публикация сайта.
addon.json, version.txt, LICENSE, README.md Метаданные аддона, номер релиза, лицензия, входная страница.
site/ Игнорируемый результат сборки; вручную не редактировать.
quarantine/ Сохранённые файлы вне активного загрузчика; не точка расширения.

Локальные планы и лабораторные записи не являются контрактом релиза. Машинные пути и временный мост не относятся к установке продукта.

При первом появлении игрока spawner/sv_pre_spawn_cache.lua прогревает ресурсы: один раз создаёт и удаляет каждый NPC (класс/модель) и машину из конфига. Отношения к NextBot определяются по отношениям к игрокам без создания пробных сущностей; см. мозги.

Взаимосвязи

config -> кеш разрешённых Config -> копия конфига конкретного актора
навигация + видимость игроков -> спавнер -> реестр Actor
Actor -> мозг FSM/GOAP -> callbacks состояния -> методы Actor -> тело -> сущность движка
системы/события -> реакции / розыск / арест / вызов медика -> переход состояния
Actor <-> провайдер транспорта -> контроллер DV + шасси + визуальная модель пассажира
серверный Actor -> снимок PVS + поколение -> клиентский реестр -> интерфейс / звук / рендер

Посадка сохраняет актора и UID, но заменяет сущность и адаптер тела. Реестры, ссылки врагов/целей, розыск и статистика следуют за заменой. Собственные данные стороннего аддона переносите через BGN_ActorEntityChanged(actor, old, new). SERVER отправляет игроку идентичность снимка только при первом появлении в PVS или перепривязке, затем только изменившееся состояние, не больше 8 снимков за тик; номер пакета не даёт задержанному пакету идентичности затереть на CLIENT более новое состояние.

Удерживанием двери управляет сервер (systems/sv_door_hold.lua, brain/fsm/states/sv_hold_door.lua), действие выбирает GOAP. Временное knocked_down сохраняет исходную сущность и адаптер тела, скрывает/замораживает их, а серверный регдолл обеспечивает физику и передачу урона. Цикл обновления актора выполняет только восстановление; для подъёма нужен свободный хитбокс. Синхронизация и клиентская оптимизация отрисовки сохраняют серверный флаг скрытого тела.

systems/siege/ отвечает за ограниченный поиск замкнутой области NavMesh, общее резервирование прохода, расстановку осады и спецсредства на SERVER. GOAP выбирает siege; brain/fsm/states/sv_siege.lua исполняет этапы для обоих типов тел. Существующие донорские анимации не дают штатным событиям броска/выпуска NPC создавать дубликаты. CLIENT получает обычные обновления состояния/анимации. См. осаду помещений.

debug/sv_scenic.lua отвечает за админское размещение сцен, владельцев/Undo и один цикл проверки двери GOAP. lua/weapons/gmod_tool/stools/bgn_scenic_debug.lua даёт выбор сцены и HUD осмотра через существующий Tool RPC с сервера на клиент. При ручном создании и отложенной постановке проверяется администратор-владелец; только этот путь обходит проверку скрытой позиции. Модели всех акторов по-прежнему определяют обычный спавнер и его хуки.

systems/sh_carry_items.lua содержит общие определения предметов, проверки моделей/анимаций и выбор по шансу. SERVER управляет временем жизни предметов настоящих акторов; адаптеры тел исключают эти предметы из запросов боевого оружия. Для переноски используются только таблицы активностей NextBot. Ходьба HL2 NPC не меняется; CLIENT крепит кейс к кости руки на обоих типах тела. Кейс не становится физическим объектом. systems/cl_carry_items.lua управляет клиентскими предметами настоящих акторов через carry_visual в существующих PVS-снимках. Газета скрывает паёк NextBot, управляющий позой, и располагает штатную модель бумаги между обеими кистями. Призраки и появляющиеся из них акторы всегда без предметов. Размещение сцен остаётся на SERVER, включая трассировки комнат/уступов, габариты мебели и целостность пары на диване.

Настройки и данные

systems/sv_lethal_weapons.lua управляет серверным кешем изученного оружия и опциональным таймером обнаружения раз в секунду. background_npcs/lethal_weapons.json читается один раз при запуске сервера/карты; перезагрузка скриптов сохраняет кеш, полный файл перезаписывается только при изучении нового класса. См. оружие в руках.

Значения cvars — в cvars/sh_cvars.lua, sv_cvars.lua, cl_cvars.lua; инфраструктура прав/регистрации — core/sh_cvars.lua. Серверные настройки меняют администраторы, голоса/интерфейс локальны. Конфиг разрешает inherit и @type, кешируется, копируется при создании актора. После правок определения очищайте кеш; существующие акторы сохраняют свои копии.

ui/spawnmenu/sv_spawnmenu.lua загружает custom.dat при инициализации/reload, а не при создании сущности, и очищает кеш конфигов после изменения сопоставлений. Меню и Actor spawner Tool передают владельца общему спавнеру: PlayerSpawnNPC может запретить создание заранее, PlayerSpawnedNPC обеспечивает учёт gamemode после создания актора. Автоматическая популяция не передаёт владельца. Формат сетевых частей и лимиты клиентских загрузок описаны в аудите.

Пути DATA относятся к garrysmod/data/, а не каталогу аддона: background_npcs/nodes, graph, seats, compile (создаёт загрузчик), отчёт background_npcs/test_report.txt. Точки DV отделены от пешеходных. Сохраняйте пользовательские маршруты; импорт старых данных/дубликаций не должен затирать посторонние точки. Скомпилированные маршруты — генерируемые Lua-файлы для распространения.

Разработка и проверки

Проверки со стабами не доказывают физику GMod, права на реальном сервере и совместимость со всеми аддонами. Для игровых результатов указывайте условия проверки.

Серверная обработка боевого урона: systems/sv_first_attacker_found.lua получает подтверждённый урон движка/пассажирам, записывает инициатора пары, проверяет пороги текущего ареста и вызывает BGN_ConfirmedDamage для начала ареста и свидетелей. systems/arrest/sv_arrest.lua проверяет подчинение ведущему офицеру каждые 0.25 секунды. Память существует только на SERVER; см. розыск.

Входы урона определяют владельца спецсредства осады через Combat.ResolveVehicleAttacker(attacker, inflictor) до проверок команд/защиты/реакций, независимо от порядка нативных хуков. Давность поиска берётся из времени наблюдения/переданного донесения, а не записей управления преследованием в движковую память NPC. Actors.Rebind переносит позицию/время и ссылки на боевую цель/недавнего нападающего до обновления врага тела. Вход в осаду исключает hold_fire-акторов переговоров. См. дерево продолжения боя.