Публичные репозитории с примерами

Это руководство определяет, как создаются, проверяются, подготавливаются, выпускаются и поддерживаются совместимыми репозитории с примерами FOnline. Машиночитаемый первоисточник находится в Examples/PublicRepositories.json, а его проверяемая проекция находится в сгенерированном реестре.

Статус контракта

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

Портфель пока находится на допубликационной стадии. Все четыре удалённых репозитория существуют как приватные staging-репозитории. Для двух примеров готов исходный код внутри Engine, один из них размещён в удалённом staging-репозитории, но ни один ещё не прошёл полный публичный выпускной шлюз. Имена репозиториев описывают их будущую публичную роль, а не текущую видимость.

Граница полномочий

Публичные примеры являются исполняемыми учебными материалами. Они показывают один поддерживаемый вариант компоновки на одной точной ревизии Engine, но не определяют поведение Engine.

Если пример расходится с Engine, используйте источники в следующем порядке:

1. исходный код и тесты Engine;
2. владеющая страница документации Engine и сгенерированная модель контракта;
3. репозиторий примера на зафиксированном теге и его gitlink Engine;
4. документация подключающего проекта и исторические примеры.

Переиспользуемый дефект сначала исправляется в cvet/fonline. Код, представление, руководства и материалы, относящиеся только к примеру, исправляются в его репозитории. Документация Engine не должна нормативно зависеть от неопубликованных веток, Last Frontier, TLA или проектной политики примера.

Портфель

Программа намеренно состоит из нескольких небольших репозиториев, а не из одной демонстрационной игры.

Существование удалённого репозитория, готовность исходного кода и публичный выпуск являются разными состояниями. remote.visibility = private означает созданный администратором staging-репозиторий, который ещё нельзя представлять как публичную документацию. remote.state = reserved означает, что существует только оболочка репозитория, а source-staged означает, что проверенный кандидат исходного кода уже отправлен. Не публикуйте ссылки на репозиторий, пока его статус в реестре равен planned, blocked или source-ready. Состояния жизненного цикла и remote меняются на published, а видимость на public только после проверки защищённой основной ветки, настроек безопасности, обязательных checks, первого тега и публичного артефакта.

Контракт исходного кода Content Showcase

Examples/ContentShowcase является исполняемой галереей, принадлежащей Engine, для третьей записи портфеля. Она содержит сцену на одной карте, анимированный маяк FOFRM, скриптовую панель-спрайт, частицы SPARK с рендерингом через эффект .fofx, сгенерированный звуковой сигнал WAV, оригинальные проектные входы TGA, прототип и минимальный клиент-серверный скрипт для проверки загрузки и взаимодействия. Авторские входы находятся в ShowcaseAssets/; сгенерированные деревья Resources/, ServerResources/, Baking/, Build/ и Workspace/ никогда не попадают в staged-репозиторий.

Запускайте python validate.py для native-проверки исходников, baking и процессов, а python validate.py --web для быстрой Web-проверки исходников и компиляции. python validate.py --web-package добавляет force-bake на native-хосте, точную проверку raw/ZIP payload, WebAssembly и Resources.data, а также равенство архива. После npm ci и npx playwright install chromium в WebTests/ команда python validate.py --web-runtime добавляет native-сервер, поставку пакета через HTTP, обязательные ответы и lifecycle-маркеры, настоящий контекст WebGL 2, проверки ошибок консоли, страницы и сети и пиксельное доказательство композитора. Эти example routes необязательны и не входят в обязательный реестр проверок или workflow Engine. В Windows команда cmake --build --preset windows-capture запускает настоящий клиент Direct3D 11. В Linux запускайте linux-capture под Xvfb с программным Mesa, когда требуется Linux OpenGL evidence; сохраняйте PNG, process report, точный SHA Engine и backend record в workflow владеющего проекта. Оба native-маршрута записывают двенадцать прогретых образцов, независимо проверяют области заголовка, runtime, галереи и подвала и сохраняют самый полный кадр. assets/provenance.json, quality/performance-budget.json и captures/capture-contract.json являются входами выпуска: обновляйте их в одном изменении с любым изменением материала, раскладки, рендерера, бюджета или поддерживаемого backend. Снимки Direct3D 11 и WebGL 2 являются сохранёнными локальными доказательствами backend; Linux OpenGL является сохранённым историческим CI-доказательством из run 30937990249 репозитория cvet/fonline-content-showcase, для которого перед добавлением независимо проверены digest артефакта, хэш PNG, process report, привязка Engine и области пикселей.

Вспомогательные fixtures внутри репозитория

Не каждое узкое доказательство должно становиться отдельным публичным игровым репозиторием. Examples/GameplayTestHarness изолирует семантику запуска процессов, а Examples/AiControlSample изолирует транспорт AiControl, авторизацию, курсор событий и жизненный цикл команд. Пример AiControl намеренно не встраивает FOnline и не задаёт игровую схему, поэтому он публикуется вместе с документацией Engine, а не выдаётся за пятую минимальную игру.

Если в будущем отдельный репозиторий AiControl окажется оправданным, добавляйте его в Examples/PublicRepositories.json только после того, как он получит точную привязку к Engine, настоящий проектный native listener и интеграцию с циклом клиента, сохранит обычную серверную авторитетность, пройдёт pinned/current-линии Windows и Linux, докажет отсутствие listener в поставочном клиенте и получит те же файлы управления и безопасности, что остальной портфель. Одного протокольного Python smoke для такого заявления недостаточно.

Аудит удалённого staging

Аутентифицированная проверка GitHub от 2026-08-03 дала снимок, записанный в полях remote машинного реестра:

Привязка Engine у шаблона является достижимым предком origin/master, но предшествует появлению BuildTools/docs_examples.py. Поэтому workflow пропускают команду проверки репозитория, если этого файла нет. Аудит от 2026-08-03 повторно подтвердил успешный pinned-запуск 29739863448 в Windows и Ubuntu и успешный current-Engine-запуск 29740066760 в Ubuntu; ни один запуск не сохранил артефакт, обязательный commit status не наблюдался. Эти запуски доказывают старый основной smoke-путь, но не текущий контракт репозитория и не publication gate. Перед выпуском заново подготовьте кандидата на проверенной точной ревизии Engine, содержащей валидатор, а затем получите полные результаты pinned/current и сохраняемые артефакты.

Из самого факта существования репозитория нельзя делать выводы о защите ветки, доступности Security Advisories, политике секретов, настройке Pages, тегах выпусков или хранении артефактов. Это отдельные наблюдения, принадлежащие администраторам; они остаются непроверенными, пока владелец публикации не зафиксирует результат.

Решение о публикации

Репозиторий может стать публичным только тогда, когда один конкретный commit кандидата удовлетворяет всем условиям:

1. реестр, example-repository.json, gitlink Engine, сгенерированный README и remote head указывают на один и тот же репозиторий и точную ревизию Engine;
2. чистый clone проходит валидатор репозитория, основную проверку и все обязательные pinned/current-линии платформ без fallback-пропусков;
3. защита ветки требует заявленные checks и CODEOWNERS review, прямые release-push запрещены, а Security Advisories включены;
4. каждый распространяемый материал проходит побайтовую проверку происхождения;
5. первый неизменяемый тег и адресованный commit артефакт собраны из того же commit и содержат требуемые доказательства;
6. документы поддержки, безопасности, участия и известных ограничений проверены с точки зрения публичного читателя;
7. администратор меняет видимость, после чего сопровождающие переводят реестр в published и перегенерируют сайт и AI-артефакты.

Если хотя бы одно условие неизвестно, репозиторий остаётся приватным, а состояние checks остаётся not-observed. Оболочка репозитория, локальный зелёный запуск или готовый исходный fixture не заменяют наблюдаемые удалённые шлюзы.

Владение

Внешний репозиторий владеет своим кодом, выпусками и трекером задач. Репозиторий Engine владеет общей политикой, валидатором, управляющим overlay и канонической заготовкой исходного кода. Только администраторы репозиториев имеют право создавать репозитории, менять видимость, предоставлять доступ, настраивать секреты, включать Pages и публиковать выпуски.

Обязательный контракт репозитория

В корне каждого публичного примера находятся:

• example-repository.json со стабильным ID программы, каноническим именем репозитория, URL clone Engine, точным 40-символьным commit Engine, путём submodule Engine/, основной проверкой и путём к происхождению материалов;
• .gitmodules с каноническим HTTPS URL Engine и .gitattributes с общей политикой окончаний строк;
• Engine/, зафиксированный как git submodule на этой точной ревизии;
• общие LICENSE, CONTRIBUTING.md, SECURITY.md, SUPPORT.md, THIRD_PARTY_NOTICES.md, CODEOWNERS, шаблон pull request и два workflow совместимости;
• assets/provenance.json с записью для каждого распространяемого изображения, звука, модели, шрифта или другого некодового материала;
• короткий ориентированный на задачу README, который называет ревизию Engine и ссылается на глубокие переиспользуемые контракты на fonline.ru;
• одна специфичная для репозитория команда, доказывающая его основное поведение без административных сервисов и приватных credentials.

Проверяйте checkout кандидата из его корня:

python Engine/BuildTools/docs_examples.py --verify-repository . --engine-mode pinned

Валидатор отклоняет неразрешённые шаблонные placeholders, неизвестные ID репозиториев, неточные ревизии, расхождение metadata и реестра, неверный путь или URL Engine в .gitmodules, обычный каталог вместо submodule Engine/, несовпадение gitlink и checkout, отсутствующие управляющие файлы, отсутствующие материалы из provenance и несовпадение SHA-256 с фактическими байтами материала.

Создание репозитория

Владелец публикации действует в следующем порядке:

1. Повторно проверяет remote и обновляет в реестре verified_on, основную ветку, head commit, наблюдаемый Engine pin и состояние обязательных checks. Затем подтверждает зависимости и выходной шлюз записи и фиксирует владельца кандидата.
2. Подтверждает чистоту рабочего дерева Engine и доступность выбранного commit через program.engine_clone_url. Исходный код не может использовать незакоммиченное поведение Engine.

3. Материализует одобренный исходный код вместе с управляющим overlay в новом каталоге:

   engine_revision="$(git rev-parse HEAD)"
   candidate="Workspace/fonline-minimal-multiplayer"
   python BuildTools/docs_examples.py --stage-repository minimal-multiplayer --engine-revision "$engine_revision" --output "$candidate"
   

   Команда требует, чтобы запрошенная ревизия совпадала с чистым checkout Engine и входила в одну из полученных remote-tracking веток. Она отказывается использовать существующий выходной каталог, исключает сгенерированные и локальные пути из реестра, сохраняет исходное пошаговое руководство как TUTORIAL.md, подставляет все placeholders, записывает точный pin в metadata и привязывает URL происхождения материалов Engine к этому pin. Команда не создаёт commit, не выполняет push и не меняет удалённый репозиторий.

4. Инициализирует кандидата и создаёт точный gitlink Engine:

   git -C "$candidate" init -b main
   git -C "$candidate" submodule add --force https://github.com/cvet/fonline.git Engine
   git -C "$candidate/Engine" checkout "$engine_revision"
   git -C "$candidate" add .
   

5. Проверяет всё staged-дерево. Нельзя добавлять материал, для которого не подтверждены источник, лицензия, digest и право распространения. Сгенерированный короткий README является публичной точкой входа, а TUTORIAL.md владеет полным проектным руководством.
6. Создаёт commit кандидата, запускает валидатор репозитория и основную проверку из чистого clone, затем отправляет commit в приватный staging-репозиторий для первых pinned/current-запусков CI.
7. Включает GitHub Security Advisories, требует CODEOWNERS review, защищает main, делает checks из реестра обязательными и запрещает прямые release-push.
8. Проверяет README и сгенерированные ссылки документации из чистого clone. Создаёт первый неизменяемый тег и артефакт кандидата, проверяет их и только после этого меняет видимость репозитория.
9. Меняет статус и remote-состояние реестра Engine на published, записывает публичную видимость и проходящие checks, добавляет только проверенные публичные ссылки и ссылки на тег, перегенерирует документацию и повторяет проверку сайта и AI-артефактов.

Создание удалённого репозитория и изменение его настроек являются операциями с владельческим шлюзом. Локальная правка документации не даёт разрешения создавать, отправлять, публиковать или передавать репозиторий GitHub.

Ревизии Engine и совместимость

Артефакты выпуска и теги руководств собираются на точном gitlink Engine, записанном в example-repository.json. Они никогда не получают плавающую основную ветку. Благодаря этому логи, сгенерированные metadata, снимки экрана, содержимое пакета и заявления о поддержке воспроизводимы.

Каждый репозиторий также еженедельно запускает линию current-engine на Engine master. Она отвечает, готово ли обновление, но не изменяет release pin. Зелёный результат может породить проверяемый pull request обновления Engine. Ошибка остаётся видимой вместе с протестированным commit Engine и назначается владельцу изменившейся границы.

При обновлении проверяются три границы совместимости:

• версия игровой совместимости, включая сетевые и сериализованные контракты;
• поколение протокола updater;
• ABI native client host/runtime.

Поколение протокола updater 2 и ABI client host/runtime 3 отклоняют старые небезопасные native-клиенты до передачи или загрузки нового runtime. Пример, распространяющий native-клиент через эту границу, обязан выпустить новый полный пакет клиента и указать, что установкам поколения 1/ABI 2 требуется одна ручная переустановка. Нельзя представлять внутрипроцессную перезагрузку runtime или плавающий пакет клиента как путь совместимости. См. Разделение client runtime и updater.

Линии CI

pinned-engine запускается для каждого pull request и обновления защищённой ветки. Она проверяет управление репозиторием, идентичность gitlink и metadata, основное поведение примера и все специфичные для репозитория платформенные шлюзы. Шаблон проекта и исходный код Minimal Multiplayer требуют smoke-задачи Windows и Linux; Minimal Multiplayer дополнительно требует приёмку пакетов Windows/Linux и сохраняемые доказательства пакетов, адресованные commit.

Linux-задачи подготавливают системные зависимости командой Engine/BuildTools/prepare-workspace.sh linux-packages linux из полученной ревизии. Не копируйте список apt-пакетов в workflow примеров: принадлежащая Engine команда является версионируемым платформенным контрактом и удерживает prerequisites pinned- и compatibility-линий одинаковыми.

Content Showcase использует web-packages web для принадлежащих Engine Web prerequisites; нужные визуальной линии пакеты Xvfb/Mesa остаются в собственном workflow репозитория примера. Запускайте helper с принадлежащим примеру Workspace, выбранным через FO_WORKSPACE; BuildTools выводит закреплённый путь Workspace/emsdk и не учитывает посторонний override FO_EMSDK. Загружайте PNG Linux OpenGL, capture contract и process evidence до более длинной WebGL 2 runtime-линии, чтобы последующий сбой Web не стирал уже достоверное backend evidence, при этом вся обязательная job остаётся неуспешной до прохождения всех линий.

current-engine запускается еженедельно и по запросу. Она временно извлекает Engine master, записывает протестированный commit и запускает то же основное поведение. Она не должна перезаписывать example-repository.json, gitlink, сгенерированные файлы, теги или артефакты выпусков.

Общий сборщик доказательств сохраняет отчёты, снимки, манифесты пакетов, архивы выпуска и Web runtime payload. Он намеренно исключает рекурсивные копии Build/**/Binaries: эти деревья дублируют промежуточный результат сборки, могут исчерпать таймаут job и не являются контрактом выпуска. Если репозиторию нужен другой артефакт, добавьте узкий именованный шаблон; не расширяйте сборщик до всего дерева сборки.

Дополнительные шлюзы задаются записью реестра:

• репозитории руководств воспроизводят каждый тег урока или fixture;
• content showcase проверяет происхождение, бюджеты производительности и воспроизведение захватов;
• пример native-расширения запускает сфокусированные native-тесты и сгенерированные проверки контракта расширений.

Пример, публикующий архивы native-клиента или сервера, должен добавить принадлежащую проекту package-линию по образцу Examples/PackagingMatrix: force-bake встроенной конфигурации, равенство инвентаря архива и payload, packaged updater handshake, точную ревизию Engine, SHA-256 manifest и адресованный commit CI-артефакт. Examples/MinimalMultiplayer содержит исходный код такой линии и локальное Windows-доказательство; Linux job, неизменяемый внешний артефакт и публичный тег ещё требуют наблюдения. Общий fixture Engine доказывает только механику упаковки и не квалифицирует автоматически артефакт выпуска отдельного примера.

Изменения общих workflow сначала делаются в overlay Engine и проверяются там, а затем распространяются через проверяемые pull request. Нельзя копировать в общий шаблон названия CI, credentials, deployments или приватные сервисы подключающего проекта.

Выпуски и руководства

Используйте неизменяемые теги для контрольных точек уроков и опубликованных примеров. Не поддерживайте расходящиеся ветки руководств. Руководство называет репозиторий, тег, файл и ревизию Engine, на которых оно протестировано.

Артефакт выпуска включает или раскрывает:

• commit и тег репозитория примера;
• точную ревизию Engine;
• host/target и конфигурацию сборки;
• результат основной проверки;
• digest происхождения материалов, если они присутствуют;
• известные ограничения и состояние поддержки.

Если исправление безопасности или совместимости делает старый тег руководства недействительным, оставьте тег неизменным и опубликуйте уведомление о замене или исправленный тег. Не переписывайте учебную историю незаметно.

Происхождение материалов

Каждая запись распространяемого материала содержит стабильный ID, относительный к репозиторию путь, разрешённый SPDX-подобный идентификатор лицензии, URL источника или project-original и SHA-256 в нижнем регистре. Валидатор отклоняет отсутствующие файлы, повторяющиеся идентичности, неизвестные лицензии, внешние источники без HTTPS, неверные digests и несовпадение байтов с digest.

Шаблон и пример native-расширения должны оставаться без материалов. Multiplayer-пример должен предпочитать оригинальные проектные материалы или материалы с разрешительными лицензиями. Showcase принимает только проверенные public-domain, CC0, CC-BY, MIT-совместимые или оригинальные проектные материалы с явными правами распространения и изменения.

Снимки экрана и сгенерированные захваты являются артефактами выпуска, произведёнными из сборки с тегом. Записывайте исходный тег, ревизию Engine, backend и команду захвата; не считайте снимки экрана исходным материалом.

Проектные доказательства и правила извлечения

Last Frontier и fonline-tla доказывают, что реальным играм нужны чёткое владение между Engine и проектом, воспроизводимые сборки, native-расширения, приёмка пакетов, многоязычный контент, каталоги материалов и долгоживущие пути обновления. Они не являются исходными деревьями для публикации. Их проектные сервисы, приватные workflow, игровые схемы, материалы, баланс, credentials и ограничения рефакторинга не должны проникать в пример Engine.

Практика из производственного проекта переносится только в следующем порядке:

1. переиспользуемая проблема формулируется в терминах Engine и проекта;
2. поведение проверяется по актуальному исходному коду и тестам Engine;
3. практика сокращается до принадлежащего Engine fixture, валидатора или документированного контракта без проектных зависимостей;
4. сокращённый путь доказывается на точной ревизии Engine и в линии current-Engine;
5. практика добавляется только в тот пример, где поддерживает единственную ответственность и выходной шлюз репозитория.

Запись внешних доказательств asset-provenance-and-public-examples разрешает конкретный вывод: публичным примерам нужны минимальные распространяемые материалы, точные привязки к Engine, побайтовая проверка происхождения, неизменяемые теги уроков и доказательства pinned/current-совместимости. Она не предоставляет прав на распространение материалов какого-либо из двух проектов. Сопровождающие могут проверить внутренний сгенерированный индекс доказательств; он хранится в исходном коде, но исключён из публичного сайта и AI delivery.

Постоянный рефакторинг TLA следует считать входом совместимости, а не шаблоном лучших практик. Производственные проверки Last Frontier являются кандидатами на практики, которым всё равно требуется сокращение до принадлежащего Engine доказательства. Так примеры остаются полезными разработчикам-людям и AI-агентам, не становясь зависимыми от одной из игр.

Поддержка и безопасность

Поддержка охватывает последнюю версию примера с тегом, закреплённый commit Engine и комбинации, выполненные обязательным CI. Успешная запланированная проверка current-Engine является доказательством прямой совместимости, но не обещанием поддержки каждого commit Engine master.

Публичная задача должна содержать ревизию примера, ревизию Engine, host, target, точную команду и полный относящийся к проблеме лог. Уязвимости передаются через GitHub Security Advisories и никогда не публикуются вместе с деталями эксплуатации или credentials в публичных задачах.

Триггеры сопровождения

Сверяйте реестр, overlay, сгенерированные результаты, удалённый аудит и затронутые репозитории при изменении любого из следующих элементов:

• публичные контракты CMake, CLI, package, native-extension, prototype, map, scripting, updater или совместимости;
• Examples/MinimalProject, Examples/MinimalMultiplayer, Examples/ContentShowcase, Examples/NativeExtensionSample, их smoke-маркеры, prerequisites, контракты захвата или поддерживаемые платформы;
• Examples/AiControlSample, BuildTools/AiControlProtocol.json, эталонный клиент, протокольный smoke или решение повысить native-пример до публичного;
• исключения source-staging, отображаемые имена, основные проверки, сгенерированный TUTORIAL.md или команда материализации кандидата;
• обязательные файлы репозитория, защита веток, версии GitHub Actions, политика безопасности или лицензии материалов;
• состояние жизненного цикла репозитория, видимость и состояние remote, наблюдаемые ветка/head/checks, владелец, зависимость, исходный путь, выходной шлюз, тег, артефакт или публичный URL;
• обновление ревизии Engine в staged- или опубликованном примере;
• доказательства Last Frontier или TLA, которыми обоснована перенесённая практика.

Запустите:

python BuildTools/docs_examples.py --write
python BuildTools/docs_examples.py --check
python BuildTools/docs_external_evidence.py --check
python BuildTools/docs_site.py --write
python BuildTools/docs_ai_delivery.py --write
python BuildTools/docs_validate.py

Сгенерированная модель является компактным машиночитаемым портфелем для AI. Эта страница владеет обоснованием и рабочей процедурой. Внешние README остаются краткими и ссылаются сюда вместо дублирования политики. Дату и доказательства каждой удалённой проверки записывайте в активный план документации; никогда не обновляйте required_checks_state на основании предположения.

См. также

• ADR-0005: владение публичными репозиториями примеров
• Упаковка и выпуск
• Руководство по обновлению Engine
• Матрица поддержки