rechka/fish-station
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
fish-station/.github/gdd.md
Vigers Ray 78212a1703
Refactor GDD by removing redundant sections 
Removed introductory and concluding sections from the GDD.
2025-11-15 03:45:25 +01:00

39 KiB
Raw Blame History

Введение

Sunrise Station — это крупный форк и серверная сборка игры Space Station 14, вдохновлённой культовой Space Station 13. Проект развивается как открытое сообщество, ориентированное на создание глубокой, хаотичной и весёлой ролевой среды в научно-фантастическом сеттинге космической станции. Данный документ предназначен для использования ИИ-агентами, осуществляющими автоматическую проверку пулл-реквестов (PR) и предоставляющими рекомендации по улучшению кода и контента. GDD структурирован так, чтобы обеспечить чёткие критерии оценки изменений, облегчить автоматизацию ревью и поддерживать высокое качество проекта.

1. Цели проекта

1.1 Основные задачи

  • Создание уникального игрового опыта: развитие форка SS14 с акцентом на глубокую механику, ролевое взаимодействие и разнообразие сценариев.
  • Поддержка и развитие сообщества: обеспечение открытости кода, прозрачности процессов и вовлечения новых участников.
  • Совместимость с upstream: регулярная синхронизация с основным репозиторием Space Wizards Federation для получения обновлений и исправлений.
  • Высокое качество кода и контента: внедрение строгих стандартов, автоматических тестов и CI/CD для предотвращения деградации качества.
  • Масштабируемость и модульность: архитектура, позволяющая легко добавлять новые механики, карты, ассеты и сценарии.

1.2 Ключевые игровые цели

  • Постройка и поддержка функционирующей станции с множеством отделов (инженерный, научный, медицинский, служба безопасности и др.).
  • Выполнение сменных задач: от строительства шаттлов и генераторов до исследования артефактов и обеспечения выживания экипажа.
  • Ролевое взаимодействие: поддержка сложных сценариев, антагонистов, событий и уникальных профессий.

2. Основные игровые механики

2.1 Обзор

Sunrise Station реализует широкий спектр механик, охватывающих симуляцию физиологии персонажей, взаимодействие с окружением, управление станцией и социальные аспекты. Особое внимание уделяется глубине и взаимосвязанности систем, что обеспечивает богатый игровой опыт.

2.2 Подсистемы физиологии

2.2.1 Здоровье

  • Показатель здоровья отражает степень ранения персонажа. Диапазон от 0 (здоров) до 200+ (смерть).
  • Типы урона: механический (удары, порезы, уколы), термический, электрический, токсический, генетический, удушье, кровотечение, структурный, взрывной, стаминный.
  • Кровотечение: отдельная шкала, зависящая от типа урона. Максимум — 10 единиц, влияет на потерю крови и состояние персонажа.
  • Регенерация: при уроне <20 — восстановление по 0,07 механического и ожогового урона в секунду.
  • Модификаторы: при 60+ урона — замедление, при 100+ — критическое состояние, пассивный урон.

2.2.2 Выносливость

  • Базовое значение — 100 единиц.
  • Урон по выносливости: при 50+ — замедление на 80% (3 сек), при 100+ — падение (6 сек).
  • Регенерация: 3 единицы в секунду, если не получал урон по выносливости 3 сек.
  • Влияние веществ: стимуляторы, дезоксиэфедрин, эфедрин изменяют длительность оглушения и максимальную выносливость.

2.2.3 Голод и жажда

  • Голод: шкала сытости (0–200), влияет на скорость переваривания, замедление при сильном голоде.
  • Жажда: шкала насыщения (0–150), влияет на скорость обработки жидкости и замедление.
  • Вещества: витамины, протеин, другие реагенты оказывают различные эффекты на организм.

2.2.4 Дыхание

  • Потребность в газе: разные расы требуют кислород или азот, отсутствие — урон удушьем.
  • Таблица соответствия: для каждой расы указан тип газа и урон при его отсутствии.

2.2.5 Защита

  • Броня и скафандры: уменьшают урон определённых типов по формуле: Урон - Урон * защита% = итоговый урон.
  • Взрывной урон: игнорирует большинство видов защиты, кроме специальной.

2.3 Архитектура станции и карты

  • Станции определяются YAML-прототипами, включающими метаданные, компоненты, распределение профессий, параметры биома и освещения.
  • Биомы: задают визуальные и геймплейные эффекты (цвет освещения, параллакс, атмосфера).
  • Рабочие места: для каждого отдела определён диапазон доступных позиций.

3. Архитектура и структура кода

3.1 Общая структура репозитория

Папка/Файл Назначение
.github/ CI/CD, workflows, шаблоны PR/ISSUE
BuildChecker/ Скрипты и утилиты для сборки
BuildFiles/ Файлы для сборки под разные ОС
Content.Client/ Клиентская часть
Content.Server/ Серверная часть
Content.Shared/ Общие компоненты и системы
Content.IntegrationTests/ Интеграционные тесты
Content.Tests/ Юнит-тесты
Content.Benchmarks/ Бенчмарки производительности
Content.MapRenderer/ Рендеринг карт
Content.Packaging/ Сборка и упаковка ассетов
Content.YAMLLinter/ Линтер YAML-файлов
Resources/ Ассеты, карты, локализация
RobustToolbox/ Игровой движок (подмодуль)
Sunrise/ Специфичные для Sunrise расширения
Tools/ Вспомогательные инструменты
README.md, README.ru.md Документация
LICENSE.TXT, CLA.txt Лицензии и соглашения

Пояснения:

  • Вся логика разделена на клиентскую, серверную и общую части (Client/Server/Shared), что облегчает поддержку и расширение.
  • Тесты и бенчмарки вынесены в отдельные папки для автоматизации проверки качества.
  • Ассеты и карты структурированы по типу и назначению, YAML-файлы проходят автоматическую валидацию.

3.2 Модули и ключевые компоненты

  • Content.Server: логика сервера, обработка событий, симуляция мира.
  • Content.Client: интерфейс пользователя, визуализация, клиентские системы.
  • Content.Shared: общие компоненты ECS, прототипы, сетевые сообщения.
  • RobustToolbox: движок, реализующий ECS, сетевой стек, рендеринг, физику.
  • Content.IntegrationTests/Content.Tests: тестовые сценарии, покрывающие как отдельные компоненты, так и интеграцию систем.
  • Content.YAMLLinter: автоматическая проверка YAML-файлов на корректность и стиль.

4. Используемые технологии и зависимости

4.1 Языки и платформы

  • C#: основной язык разработки, поддержка .NET 7+.
  • .NET: кроссплатформенная среда выполнения, сборка и запуск на Windows, Linux, MacOS.
  • YAML: описание карт, прототипов, ассетов.

4.2 Системы сборки и зависимости

  • NuGet: управление внешними пакетами, централизовано через Directory.Packages.props.
  • Nix: reproducible-сборки, управление окружением для разработчиков (flake.nix, shell.nix).
  • CI/CD: GitHub Actions, автоматическая сборка, тестирование, обновление кредитов, проверка CRLF и др.
  • RobustToolbox: подмодуль, обновляется автоматически через скрипт RUN_THIS.py.
  • Скрипты запуска: runserver.sh, runclient.sh (и .bat-версии) для локального тестирования и разработки.

4.3 Внешние инструменты

  • YAMLLinter: проверка стиля и структуры YAML-файлов.
  • DocFX: генерация документации.
  • BenchmarkDotNet: бенчмарки производительности.
  • Git: контроль версий, поддержка ветвления и PR.

5. Принципы дизайна и кодирования

5.1 Стиль кода

  • Соблюдение C# Coding Conventions: отступы, именование, оформление блоков.
  • Единый стиль для всех файлов: enforced через .editorconfig, автоматическая проверка на CI.
  • Документирование: XML-комментарии для публичных методов и классов, README для модулей.
  • Минимизация дублирования: выносить общие компоненты в Shared, использовать наследование и композицию.

5.2 Архитектурные принципы

  • ECS (Entity-Component-System): все игровые объекты реализованы как сущности с компонентами, системы обрабатывают логику.
  • Модульность: новые механики и контент добавляются через отдельные модули/прототипы.
  • Сетевое разделение: чёткое разграничение клиентской и серверной логики, минимизация дублирования.
  • Конфигурируемость: параметры вынесены в YAML/JSON, легко изменяются без перекомпиляции.

5.3 Соглашения по именованию

  • Папки и файлы: PascalCase для C# файлов, snake_case для ассетов и YAML.
  • Классы и интерфейсы: PascalCase, интерфейсы с префиксом I.
  • Методы и свойства: PascalCase.
  • Переменные: camelCase.
  • Константы: ALL_CAPS.

6. Критерии качества для Pull Request (PR)

6.1 Автоматические проверки

  • Сборка без ошибок: PR не должен ломать сборку ни на одной поддерживаемой платформе.
  • Прохождение всех тестов: юнит, интеграционные, игровые тесты.
  • Проверка форматирования: соответствие .editorconfig, отсутствие лишних пробелов, правильные отступы.
  • Валидация YAML: автоматическая проверка структуры и стиля YAML-файлов.
  • Отсутствие конфликтов с upstream: PR должен быть синхронизирован с последним master/main.
  • Проверка лицензий: новые ассеты и код должны иметь корректные лицензии и соответствовать CLA.

6.2 Ручная и полуавтоматическая проверка

  • Код-ревью: анализ логики, читаемости, архитектурных решений.
  • Покрытие тестами: новые функции должны сопровождаться тестами.
  • Документация: наличие описания изменений, комментариев, обновление README при необходимости.
  • Обратная совместимость: изменения не должны ломать существующий функционал без веской причины.

6.3 Критерии приёма изменений

Критерий Обязателен Примечания
Сборка проходит ✔ На всех поддерживаемых ОС
Все тесты проходят ✔ Включая интеграционные и игровые
Нет конфликтов ✔ С master/main и upstream
Документация обновлена ✔ README, комментарии, changelog
Лицензии соблюдены ✔ Для кода и ассетов
Нет деградации качества ✔ Производительность, безопасность, стиль
Покрытие тестами ✔ Для новых/изменённых функций
Обратная совместимость ✔ Если не указано иное в описании PR

7. Автоматическая проверка изменений: правила для ИИ

7.1 Общие принципы

  • Сравнивать изменения с текущим master/main: анализировать diff, выявлять потенциальные проблемы.
  • Проверять соответствие стилю и архитектуре: использовать встроенные линтеры и анализаторы.
  • Оценивать влияние на производительность и безопасность: выявлять потенциальные bottleneck'и, утечки, уязвимости.
  • Проверять наличие и качество тестов: новые функции должны сопровождаться тестами.
  • Анализировать документацию: изменения должны быть отражены в README, комментариях, changelog.

7.2 Алгоритм автоматической проверки

  1. Извлечь diff PR: определить изменённые файлы и области кода.
  2. Проверить сборку и тесты: убедиться в отсутствии ошибок.
  3. Запустить линтеры и форматтеры: проверить стиль кода и YAML.
  4. Проверить лицензии и CLA: новые файлы должны иметь корректные лицензии.
  5. Проверить документацию: наличие и актуальность описаний.
  6. Проверить обратную совместимость: нет ли breaking changes без обоснования.
  7. Сравнить с примерами хороших/плохих изменений: выявить паттерны и антипаттерны.
  8. Сформировать рекомендации: указать на найденные проблемы, предложить улучшения.

8. Примеры хороших и плохих изменений

8.1 Примеры хороших изменений (паттерны)

Изменение Почему хорошо
Добавлен новый компонент с тестами и документацией Повышает покрытие, облегчает поддержку
Оптимизация алгоритма с бенчмарком Улучшает производительность, подтверждено метриками
Исправление бага с подробным описанием Улучшает стабильность, облегчает ревью
Рефакторинг с сохранением обратной совместимости Повышает читаемость, не ломает существующий код
Добавление новых YAML-прототипов с валидацией Расширяет контент, не нарушая структуру

Анализ:
Хорошие изменения сопровождаются тестами, документацией, не ломают существующий функционал, проходят все проверки и улучшают проект по одному из критериев: производительность, стабильность, расширяемость, удобство поддержки.

8.2 Примеры плохих изменений (антипаттерны)

Изменение Почему плохо
Изменение логики без тестов и документации Усложняет поддержку, повышает риск багов
Ломает обратную совместимость без обоснования Приводит к деградации пользовательского опыта
Добавление ассетов без лицензии Нарушает юридические требования
Игнорирование стиля и форматирования Усложняет ревью, снижает читаемость
Изменение в core-модулях без обсуждения Риск конфликтов и деградации архитектуры

Анализ:
Плохие изменения часто сопровождаются отсутствием тестов, документации, нарушают стиль, ломают существующий функционал или не учитывают юридические аспекты. Такие изменения должны быть отклонены или доработаны.

9. Тестирование

9.1 Виды тестов

  • Юнит-тесты: проверяют отдельные компоненты и системы на корректность работы.
  • Интеграционные тесты: моделируют взаимодействие между модулями, проверяют сценарии использования.
  • Игровые тесты: автоматизированные сценарии, эмулирующие поведение игроков, загрузку карт, запуск раундов.
  • Бенчмарки: измеряют производительность критичных участков кода.

9.2 Инфраструктура тестирования

  • PoolManager: управление парами сервер-клиент для интеграционных тестов.
  • PostMapInitTest: валидация карт, прототипов, YAML-файлов.
  • CI/CD: автоматический запуск тестов при каждом PR.
  • Отчёты о покрытии: анализируются на CI, минимальный порог покрытия обязателен для новых функций.

9.3 Критерии успешного тестирования

  • 100% прохождение тестов: PR не должен ломать существующие тесты.
  • Покрытие новых функций: все новые/изменённые компоненты должны иметь тесты.
  • Валидация YAML и карт: автоматическая проверка структуры и корректности.

10. Документация и комментарии в коде

10.1 Требования к документации

  • README.md/README.ru.md: актуальное описание проекта, инструкции по сборке и запуску.
  • XML-комментарии: для всех публичных методов, классов, интерфейсов.
  • Комментарии в коде: пояснения к сложной логике, TODO/FIXME только при необходимости.
  • Документация для новых модулей: отдельные файлы или разделы в README.

10.2 Автоматизация

  • DocFX: генерация HTML-документации из XML-комментариев.
  • Проверка на CI: наличие и актуальность документации для новых функций.

11. Лицензирование и CLA

11.1 Лицензии

  • MIT: для кода, заимствованного из Space Wizards Federation.
  • CLA (Contributor License Agreement): для всех изменений, внесённых в Sunrise Station. Подразумевает передачу прав на использование и модификацию кода проекту, запрещает коммерческое использование без разрешения, требует передачи изменений обратно в проект.
  • CC-BY-SA 3.0: для большинства ассетов (графика, звуки), если не указано иное в метаданных.

11.2 Правила использования кода

  • Коммерческое использование: запрещено без отдельного разрешения.
  • Публичный хостинг: только с разрешения владельцев проекта.
  • Внесение изменений: любые модификации должны быть переданы обратно в проект на условиях CLA.
  • Лицензии ассетов: каждый ассет должен иметь явное указание лицензии в метаданных.

12. Процесс работы с пулл-реквестами и ветвлением

12.1 Ветвление

  • Основная ветка: master (или main).
  • Фичевые ветки: для каждой новой функции или исправления создаётся отдельная ветка.
  • Синхронизация с upstream: регулярное обновление ветки от основного репозитория Space Wizards Federation.
  • Запрет на PR из master: все изменения должны идти из отдельных веток.

12.2 Процесс PR

  1. Создание ветки: от master/main.
  2. Внесение изменений: с соблюдением всех критериев качества.
  3. Добавление тестов и документации.
  4. Проверка локально: сборка, тесты, линтеры.
  5. Открытие PR: с подробным описанием изменений.
  6. Автоматическая проверка: CI, тесты, линтеры.
  7. Код-ревью: ручная или полуавтоматическая проверка.
  8. Мерж или доработка: после одобрения и устранения замечаний.

13. Безопасность и политика безопасности

13.1 Общие принципы

  • Ответственное раскрытие уязвимостей: сообщения о проблемах безопасности принимаются через Discord или email, публичное раскрытие запрещено до разрешения.
  • Проверка кода на уязвимости: автоматические анализаторы, ручной аудит для критичных изменений.
  • Ограничение доступа: права доступа к CI/CD, секретам и инфраструктуре только у доверенных участников.
  • Логирование и аудит: все действия по безопасности должны быть зафиксированы.

13.2 Политика обработки инцидентов

  • Быстрое реагирование: при обнаружении уязвимости — немедленное исправление и уведомление участников.
  • Документирование инцидентов: ведение журнала инцидентов и принятых мер.
  • Обновление зависимостей: регулярная проверка и обновление внешних библиотек.

14. Производительность и оптимизация

14.1 Профилирование

  • Бенчмарки: регулярное измерение производительности критичных систем (загрузка карт, обработка событий, сетевой стек).
  • Анализ bottleneck'ов: выявление и устранение узких мест.
  • Мониторинг логов: анализ ошибок и предупреждений для выявления деградации.

14.2 Оптимизация

  • Асинхронность: использование асинхронных операций для I/O и сетевых задач.
  • Кэширование: для часто используемых данных и ресурсов.
  • Минимизация аллокаций: оптимизация работы с памятью, особенно в горячих путях.
  • Логирование: структурированное, с учётом производительности и объёма данных.

15. Модули и ключевые компоненты

15.1 Server, Client, Shared

  • Server: обработка симуляции, событий, логики NPC, взаимодействие с базой данных.
  • Client: визуализация, UI, обработка пользовательского ввода.
  • Shared: компоненты ECS, прототипы, сетевые сообщения, общие утилиты.

15.2 Дополнительные модули

  • Content.Benchmarks: тесты производительности.
  • Content.MapRenderer: визуализация карт.
  • Content.Packaging: упаковка ассетов и билдов.
  • Content.YAMLLinter: автоматическая проверка YAML.
  • Pow3r, Tools: вспомогательные утилиты и инструменты.

16. Система сборки и упаковки

16.1 BuildFiles и Packaging

  • BuildFiles/: специфичные для платформ файлы сборки (Mac, Windows, Linux).
  • Content.Packaging/: скрипты и конфиги для упаковки ассетов, генерации билдов.
  • RUN_THIS.py: автоматизация инициализации подмодулей и зависимостей.
  • Скрипты запуска: runserver.sh, runclient.sh для локального тестирования.

16.2 Локальная сборка и запуск

  • Инструкции: описаны в README.ru.md, поддерживаются для всех основных ОС.
  • Требования: установленный Git, Python 3.7+, .NET 7+, Nix (опционально).
  • Процесс: клонирование репозитория, запуск скрипта и сборка через dotnet.

17. Критерии приёма изменений: функциональность и совместимость

17.1 Функциональность

  • Изменения должны быть обоснованы: каждая новая функция или исправление должно иметь чёткое описание и цель.
  • Покрытие тестами: обязательное для всех новых функций.
  • Документация: обновление README, комментариев, changelog.

17.2 Обратная совместимость

  • Не ломать существующий функционал: breaking changes допускаются только с веской причиной и обсуждением.
  • Сохранение форматов данных: YAML, прототипы, карты должны быть совместимы с предыдущими версиями.
  • Синхронизация с upstream: регулярное обновление и разрешение конфликтов.

18. Локализация и ресурсы

18.1 Локализация

  • README.ru.md: основной файл документации на русском.
  • Локали: все игровые строки вынесены в отдельные файлы локализации, поддержка нескольких языков.
  • Требования к новым строкам: обязательное добавление в локализационные файлы, поддержка fallback на английский.

18.2 Ассеты и YAML

  • Стиль оформления: карты, ассеты, YAML-файлы должны соответствовать единому стилю и структуре.
  • Линтеры: автоматическая проверка на CI.
  • Лицензии: каждый ассет должен иметь явное указание лицензии.

19. Мониторинг и логирование

19.1 Серверные логи

  • Структурированное логирование: использование формата JSON или аналогичного для автоматического анализа.
  • Уровни логов: INFO, WARN, ERROR, FATAL, DEBUG.
  • Агрегация и централизованное хранение: все логи собираются в единую систему для анализа и мониторинга.
  • Политика хранения: ротация, удаление старых логов, защита от утечек данных.
  • Не логировать чувствительные данные: пароли, токены, персональные данные должны быть исключены из логов.

19.2 Мониторинг

  • Метрики производительности: загрузка процессора, памяти, сетевой трафик, время отклика.
  • Алерты: автоматическое оповещение о сбоях, ошибках, превышении пороговых значений.
  • Дашборды: визуализация состояния сервера и ключевых метрик.

20. Совместимость с upstream Space Wizards Federation

20.1 Синхронизация

  • Регулярное обновление: слияние изменений из основного репозитория Space Wizards Federation.
  • Разделение кода: собственные изменения Sunrise Station выделены, чтобы облегчить мержи и разрешение конфликтов.
  • Соблюдение лицензий: заимствованный код — под MIT, собственные изменения — под CLA.
  • Обратная совместимость: поддержка форматов данных и протоколов, используемых в upstream.

20.2 Политика обновлений

  • Тестирование после мержей: обязательный прогон всех тестов после синхронизации.
  • Документирование конфликтов: ведение журнала изменений и конфликтов при обновлениях.
  • Обратная связь с upstream: при необходимости — отправка багфиксов и улучшений обратно в основной репозиторий.

21. Приложения: чек-листы для автоматической проверки

21.1 Чек-лист для ИИ-ревью

  • Сборка проходит на всех платформах
  • Все тесты (юнит, интеграционные, игровые) проходят
  • Нет конфликтов с master/main и upstream
  • Изменения покрыты тестами
  • Документация обновлена (README, комментарии)
  • YAML-файлы валидны и соответствуют стилю
  • Лицензии и CLA соблюдены
  • Нет деградации производительности
  • Нет утечек или уязвимостей безопасности
  • Логирование структурировано, не содержит чувствительных данных
  • Обратная совместимость сохранена

21.2 Примеры сообщений для ИИ

Положительный пример:

✅ Изменения соответствуют стилю, покрыты тестами, документация обновлена. Производительность не ухудшена, обратная совместимость сохранена.

Отрицательный пример:

❌ Внесённые изменения ломают обратную совместимость (формат карты изменён без миграции). Нет тестов для новых функций. YAML-файлы не проходят валидацию.

22. Заключение

Данный GDD служит основой для автоматической и ручной проверки изменений в проекте Sunrise Station. Соблюдение описанных стандартов, критериев качества и процессов обеспечивает стабильное развитие, высокое качество кода и контента, а также безопасность и удобство для всех участников сообщества. ИИ-агенты, использующие этот документ, должны строго следовать указанным правилам, обеспечивая объективную и прозрачную оценку каждого пулл-реквеста.