Индекс публичных контрактов FOnline
Эта страница является привязанной к ревизии точкой входа в переиспользуемые интерфейсы и форматы данных FOnline Engine. Она генерируется из тех же машиночитаемых моделей, которые используются contract-diff проверками. Доступный символ или принимаемый файл не создаёт обещание совместимости автоматически; авторитетна метка стабильности владеющего контракта.
Решение о контракте
Разрешайте каждое расхождение строго в четырёхуровневом порядке: 1) владеющий исходник Engine и его metadata задают поведение и стабильность; 2) машинная модель той же ревизии задаёт точный inventory и diff; 3) сгенерированный human reference служит навигацией; 4) handwritten guides дают workflow и контекст, но не переопределяют первые три уровня. Доступный символ сам по себе не равен обещанию совместимости. Этот индекс не определяет написание annotations или механизм pin во встраивающем проекте; не выдумывайте их, если владеющий исходник или проект их не предоставляют.
Native script API является ревизионно привязанным experimental inventory: текущий проверенный inventory-pinned scope классифицирует весь inventory, поэтому не требуйте отдельный tag для каждого symbol. Если scope отсутствует или не проходит проверку, unannotated native symbols remain internal. Фиксируйте exact Engine revision, но если embedding project не документирует хранение pin, не предлагайте dedicated file, CI variable, config field, FO_ENGINE_ROOT, FO_WORKSPACE или другой механизм. При обновлении зафиксируйте exact commit, сравните все сгенерированные домены контрактов и выполните Engine Upgrade Guide до переноса pin.
Поверхности контрактов
| Домен | Поверхность контракта | Текущая стабильность | Справочник для людей | Машинная модель |
|---|---|---|---|---|
| Нативный script API | engine-native-codegen |
experimental |
Справочник | api.json |
| Project interface CMake | cmake-project-interface |
experimental |
Справочник | cmake.json |
| BuildTools CLI | buildtools-cli |
internal |
Справочник | cli.json |
| Интерфейс пакетов | package-interface |
internal |
Справочник | package.json |
| Helper CLI | helper-cli |
internal |
Справочник | helper-cli.json |
| Нативные расширения | native-extension-interface |
experimental |
Справочник | native-extension.json |
| Формат прототипов | prototype-format |
experimental |
Справочник | prototype-format.json |
| Формат карт | map-format |
experimental |
Справочник | map-format.json |
| Формат моделей | model-format |
experimental |
Справочник | model-format.json |
| Формат текста и локализации | text-format |
experimental |
Справочник | text-format.json |
| Формат эффектов | effect-format |
experimental |
Справочник | effect-format.json |
| Формат изображений | image-format |
experimental |
Справочник | image-format.json |
| Формат частиц | particle-format |
experimental |
Справочник | particle-format.json |
| Формат шрифтов | font-format |
experimental |
Справочник | font-format.json |
| Аудио | audio |
experimental |
Справочник | audio.json |
| Видео | video |
experimental |
Справочник | video.json |
| Протокол AiControl | ai-control-protocol |
experimental |
Справочник | ai-control-protocol.json |
Текущая ревизия содержит 17 моделируемых доменов контрактов: experimental 14, internal 3.
Состояние нативного script API
- Обнаруженные символы: 2555
- Символы с подтверждёнными исходниками описаниями: 2555
- Символы без описаний: 0
- Явно классифицированные символы: 2555
- Символы с классификацией
internalпо умолчанию: 0
Сгенерированный нативный справочник является полным inventory моделируемой поверхности code generation. Текущий закреплённый инвентарём scope явно классифицирован как experimental и требует точной фиксации ревизии Engine; это не обещание широкой совместимости stable. Если scope отсутствует или не проходит проверку, неаннотированные нативные символы остаются internal.
Словарь стабильности
stable: сопровождаемый контракт совместимости; несовместимые изменения требуют документированного процесса миграции.experimental: пригодно при точной фиксации ревизии Engine; совместимость может меняться с документированными примечаниями о миграции.deprecated: временно сохраняется для миграции и запланировано к удалению через процесс управления изменениями.internal: деталь реализации без обещания downstream-совместимости.
Правила классификации описаны в ADR-0002, а требования к review, diff, deprecation и миграции — в Управлении изменениями контрактов.
Порядок источников истины
- Владеющий исходник Engine и его явная metadata контракта определяют поведение и стабильность.
- Машинная модель фиксирует извлечённый контракт для закреплённой ревизии и управляет автоматическими diff.
- Сгенерированный справочник для людей объясняет моделируемую поверхность и направляет к специализированным руководствам.
- Написанные вручную руководства дают workflows и примеры, но не расширяют гарантии совместимости молча.
При расхождении слоёв считайте утверждение непроверенным: исправьте metadata исходника или генератор, перегенерируйте затронутую модель и справочник и в том же изменении обновите руководство по миграции.
Границы владения проекта
Контракт Engine не определяет схему remote calls игры, конкретные прототипы, идентификаторы контента, правила gameplay, топологию deployment, credentials сервисов, политику signing или матрицу приёмки релиза. Подключаемые проекты обязаны документировать и проверять эти границы в собственных репозиториях. Руководства Engine могут использовать проектные свидетельства как ненормативный контекст, но должны оставаться применимыми без этого проекта.
Фиксация ревизии и обновления
Фиксируйте Engine точным commit в каждом игровом репозитории и публичном примере. До изменения pin сравните все сгенерированные домены контрактов, проверьте breaking и поведенческие изменения, следуйте руководству по обновлению Engine и повторно запустите build, bake, test, packaging и документационные проверки подключаемого проекта. Квалификация платформ ведётся отдельно в матрице поддержки.