Архитектура проекта¶
База исходников: локальная 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 при запуске.
- Ядро: уведомления, классы, сеть, утилиты, планировщик, остальные помощники.
- Конфигурация, акторы, реплики, состояния; пользовательский
config, адаптер старого конфига. - API, cvars, команды; пользовательский
preload, снимок настроек по умолчанию. - Класс актора, компоненты, адаптеры тела, события, обновление, синхронизация.
- Навигация, провайдеры, ввод/вывод; провайдер DV.
- Команды/розыск, модуль ареста, остальные системы; мозги, спавнеры, интеграции.
- Языки меню, интерфейс, отладка; пользовательский
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-файлы для распространения.
Разработка и проверки¶
- Сборка и участие: EN/RU и строгая сборка сайта.
- Тестирование: диагностика, Python/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-акторов переговоров. См. дерево продолжения боя.