Требования к сценам

Этот документ задаёт целевые требования к новым сценам Vrata. Он опирается на текущий контракт runtime для Scene Bundle v1 и на диагностику старых сцен, экспортированных для staging. Старые сцены полезны только как технические пробы. Новые сцены должны быть оригинальными или иметь надлежащую лицензию. Копировать из старых сцен меши, текстуры, планировки, названия, фирменный стиль и узнаваемую визуальную композицию нельзя.

Основной процесс создания сцен силами проекта описан в docs/arch/2026-08-29-agentic-deterministic-scene-authoring.md. Эти требования проверяют готовую сцену и не зависят от того, какая LLM, какой оркестратор агентов, DCC-пакет или структура репозиториев использовались при её создании.

Цели

Каждая сцена также подчиняется общему контракту качества и шаблону постановки задачи. Техническая совместимость, воспроизводимость и пороги регрессии изображений не закрывают его проверки User/Builder/Physics и проверки визуального качества. Применяйте эти требования к комнатам любого типа.

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

Требования для человека

Оригинальность и права

• Сцена должна быть создана заново для Vrata, собрана из ассетов, принадлежащих Vrata, или из ассетов с явными коммерческими правами на использование в вебе и XR.
• Сцена не должна воспроизводить планировки сцен прежней компании, расстановку объектов, брендированные интерьеры, визуальную айдентику или характерную палитру материалов.
• Для каждого неоригинального ассета нужно записать лицензию, URL источника или ID у поставщика, автора, разрешённое использование и подтверждение того, что разрешены веб, staging, production, скриншоты и производная оптимизация.
• Пакет не должен содержать приватных локальных путей, имён сотрудников, путей проектов прежней компании и идентификаторов исходных систем, которые нельзя публиковать.

Опыт пользователя

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

Совместимость с runtime

• Сцена должна работать через стандартный путь Scene Bundle. Не добавляйте в runtime код под конкретные продуктовые сцены.
• Сцена должна оставаться пригодной к использованию, когда резервное окружение скрыто, а поверхность показа платформы остаётся видимой.
• Если renderMode равен clean, сцена должна оставаться читаемой при текущей настройке рассеянного освещения в режиме clean.
• Сцена не должна зависеть от скриптов Unity, шейдеров, работающих только в Unity, игровых триггеров, объёмов постобработки и поведения движка, которое веб-runtime не выполняет.

Структура пакета

Пакеты для production должны иметь такую структуру:

assets/scenes/<scene-id>/
  scene.json
  scene.glb
  preview.webp
  LICENSES.md

Правила:

• scene.json — единственный файл, на который указывает манифест комнаты.
• scene.glb — формат ассетов для production. .gltf допустим только для крошечных тестовых фикстур. .fbx остаётся только для старых сцен, в новых production-сценах его использовать нельзя.
• preview.webp или preview.jpg обязателен для показа в каталоге.
• LICENSES.md обязателен для любой сцены, которая не создана целиком внутри проекта.
• Все пути внутри пакета должны быть относительными и не должны содержать .., абсолютных путей и обратных косых черт.

Требования к манифесту

Сейчас runtime разбирает Scene Bundle v1. Валидаторы для новых сцен должны быть строже парсера runtime.

Рекомендуемый блок прав:

{
  "rights": {
    "owner": "vrata",
    "license": "internal-original",
    "clearedFor": ["staging", "production", "web-runtime", "screenshots", "optimization"],
    "sourceAssets": [
      {
        "id": "asset-library-or-ticket-id",
        "type": "mesh|texture|hdr|audio|font",
        "author": "Vrata",
        "licenseRef": "LICENSES.md"
      }
    ]
  }
}

Требования к координатам и масштабу

• Одна единица сцены должна равняться одному метру.
• Основной пол, по которому ходят пользователи, должен находиться на y=0 с допуском +-0.05m.
• Высота глаз игрока — примерно 1.6m; точки появления и места не должны помещать камеру внутрь потолков, реквизита или стен.
• Продуктовые сцены в помещении обычно должны укладываться в 4m <= width/depth <= 80m и 2.4m <= height <= 20m.
• Габариты (bounding box), которые вычисляет runtime, должны быть конечными и для обычных сцен в помещении не должны превышать 200m ни по одной оси.
• Габариты, вычисленные runtime, должны отличаться от bounds манифеста не больше чем в 1.5x по каждой оси. Большее отношение даёт предупреждение, а отношение выше 3x — ошибку, если сцена не объявляет и не документирует особый профиль масштаба мира.
• Позиции в scene.json должны быть заданы в координатах runtime — после всех преобразований осей в DCC и при экспорте. В стандартном пути создания в Blender с осью Y вверх смысловые координаты (x, y, z) переходят в координаты runtime (x, y, -z); валидаторы должны сравнивать точки появления, места и медиаповерхности через один явный адаптер.
• Удалите из GLB для runtime вспомогательные объекты, меши коллайдеров, камеры, элементы управления ригом, скрытые плоскости экспорта, тестовые кубы и гигантскую фоновую геометрию или исключите их из экспорта.
• Узлы с экстремальными значениями масштаба, позиции или поворота следует отклонять, кроме случаев, когда они намеренно задокументированы и не влияют на габариты и взаимодействие.

Требования к точкам появления

Сейчас точкой входа в runtime служит первая точка появления.

Проверки точек появления на staging должны использовать ?debug=1&scenefit=0. С ?debug=1 по умолчанию включается отладочная автоподгонка, которая заменяет точку появления из манифеста. Поэтому скриншот или поза, снятые без scenefit=0, не подтверждают точку появления.

Якоря мест и взаимодействия

Якоря мест — это метаданные предметной области, а не декоративные имена мешей.

• ID мест должны быть уникальными строками в нижнем kebab-case; желательно начинать их с ID сцены или зоны комнаты.
• position — целевая позиция корня аватара. Она должна быть рядом с видимой поверхностью сиденья, и до неё должно быть можно дойти по полу.
• yaw задаётся в радианах, нормализуется в [-pi, pi] и должен разворачивать аватар в задуманном направлении — к собеседникам или к центру внимания.
• seatHeight прибавляется к position.y для корня сидящего аватара и обычно должен быть от 0 до 0.8.
• radius обычно должен быть от 0.35 до 0.8 метра.
• Центры якорей мест не должны перекрываться. Расстояние между двумя центрами должно быть не меньше max(radiusA, radiusB) * 1.5, если скамья явно не допускает более плотной посадки.
• У видимого стула, скамьи или дивана, которые обещает сцена, должен быть якорь, либо они должны быть явно неинтерактивными.
• Якоря не должны помещать аватар внутрь столов, стен, подлокотников или других сидящих аватаров.
• Пол для телепорта и якоря мест должны использовать тот же масштаб координат, что и GLB.

Требования к геометрии

• Экспортируйте только видимую геометрию runtime и намеренно добавленные прокси-объекты для коллизий и взаимодействия, если runtime явно их поддерживает.
• Держите число объектов и мешей низким: объединяйте статичные меши, если это не мешает отсечению, материалам и процессу работы над сценой.
• Удалите дублирующиеся невидимые меши, вспомогательные объекты редактора, неиспользуемые камеры, источники света и анимации.
• Избегайте тонких односторонних плоскостей для стен, полов и крупной мебели, если видимость обратной стороны не обработана намеренно.
• Прозрачную листву и стекло нужно проверять в runtime, а не только во вьюпорте DCC или Unity.
• Ни один меш не должен содержать NaN, бесконечных значений, преобразований с нулевым масштабом и вырожденных ограничивающих рамок.

Требования к материалам и освещению

• Предпочтительны PBR-материалы glTF, совместимые с THREE.MeshStandardMaterial.
• Используйте запечённые текстуры base color и emissive, если внешний вид зависит от авторского освещения.
• KHR_materials_unlit используйте только для намеренно неосвещаемых или запечённых поверхностей, подписей в стиле интерфейса и вывесок.
• Не используйте в новых экспортах устаревший путь материалов spec-gloss. KHR_materials_pbrSpecularGlossiness сейчас даёт предупреждение, а для продуктовых сцен должен стать ошибкой.
• Не полагайтесь на Unity Shader Graph, собственные шейдеры Unity, материалы только с картами освещения, постобработку, пробы отражений и эффекты камеры, которые не экспортируются в данные материалов, совместимые с вебом.
• Имена материалов должны быть стабильными и осмысленными. Имена вроде Hidden/UnityGLTF/..., Tantular SDF Material, Material.024 или неконвертированные шейдеры-заглушки должны давать предупреждения: они усложняют точечную проверку и отладку.
• Не меньше 60% видимых материалов runtime должны иметь текстуры или намеренно заданный цвет — проверенный и не чёрный.
• Этот процент — лишь технический минимум. Отделка материалов, масштаб деталей, ориентация, реакция на освещение и вид вблизи должны пройти общий контракт качества: однотонная игрушечная сцена может уложиться в этот показатель и всё равно потребовать доработки.
• Широкие переопределения материалов по маске запрещены для продуктовой приёмки. Исправляйте материалы при экспорте или в исходниках.
• Крупные чёрные материалы допустимы, только если объект чёрный по смыслу и сцена всё равно остаётся читаемой из точки появления.

Требования к текстурам

• Текстуры должны быть встроены в GLB или подключены по относительным путям внутри пакета.
• Отсутствующие ассеты runtime — безусловная ошибка.
• Предпочтительны WebP, PNG, JPEG или KTX2/Basis, если конвейер их поддерживает.
• Размеры текстур должны быть степенями двойки, если нет задокументированной причины поступить иначе.
• Максимальный размер текстуры по умолчанию — 2048x2048; 4096x4096 допустим только для ключевых поверхностей и считается предупреждением.
• Избегайте множества почти одинаковых вариантов материалов и текстур. По возможности собирайте их в атласы или используйте повторно.
• Для base color используйте sRGB, а для карт normal, roughness, metalness и AO — линейные данные.

Бюджеты производительности

Бюджеты задаются для профиля пакета сцены. Валидаторы должны поддерживать выбор профиля и по умолчанию использовать desktop-standard для комнат на staging.

Примечания:

• Эти бюджеты намеренно требуют, чтобы новые сцены были легче самых тяжёлых старых сцен.
• Сцена может превысить бюджет предупреждения только при задокументированной причине и после того, как человек одобрит её внешний вид и производительность.
• Сцену, которая превышает бюджет ошибки, нельзя отмечать как готовую к production.

Визуальная приёмка в runtime

Приёмку нужно проводить в настоящем браузерном runtime Vrata, а не только статическим разбором GLB.

Обязательная форма команд для автоматических проверок:

open /rooms/<room-id>?debug=1&scenefit=0
wait until window.__VRATA_DEBUG__.sceneBundleState is loaded or failed
read window.__VRATA_DEBUG__.sceneDebug

Безусловные ошибки:

• sceneBundleState !== "loaded".
• sceneDebug.failureReason !== null.
• sceneDebug.missingAssets.length > 0.
• sceneDebug.screenshot.averageColor.a < 250 для обычных непрозрачных сцен.
• sceneDebug.screenshot.darkPixelRatio > 0.70, если не одобрен visual.intentionalDark.
• Средняя яркость скриншота ниже 40 для обычных сцен.
• Габариты, вычисленные runtime, превышают 200m по любой оси для обычных сцен в помещении.
• Первый вид открывается изнутри геометрии, за пределами комнаты или непонятен человеку, даже если числовые пороги пройдены.

Предупреждения:

• sceneDebug.screenshot.darkPixelRatio > 0.35.
• Средняя яркость скриншота ниже 55.
• Больше 25% основных образцов материалов — почти чёрные материалы без текстур.
• В именах основных образцов материалов видны неконвертированные шейдеры-заглушки.
• Время загрузки в runtime превышает бюджет предупреждения профиля.

Намеренно тёмные сцены:

• Должны объявить в метаданных visual.intentionalDark: true.
• Всё равно должны показывать пол, по которому можно ходить, силуэты, выходы и зоны внимания, места и интерактивные поверхности.
• Должны содержать в первом виде хотя бы одну яркую зону внимания или подсказку направления.
• Должны пройти проверку человеком на компьютере и в VR до вывода на staging.

Поддерживаемые возможности glTF

Разрешено для продуктовых сцен:

• Базовый glTF 2.0 .glb.
• KHR_texture_transform.
• KHR_materials_unlit, если используется намеренно.
• KHR_materials_emissive_strength, если проверено в runtime.
• KHR_lights_punctual, если он не нужен для базовой видимости.
• KHR_draco_mesh_compression, если декодирование проверено в runtime.
• EXT_meshopt_compression, если декодирование проверено в runtime.
• KHR_texture_basisu, если транскодирование KTX2 проверено в runtime.

Предупреждения для продуктовых сцен:

• KHR_animation_pointer: сцены комнат сейчас считаются статичными, если поддержка анимации явно не входит в задачу.
• KHR_materials_pbrSpecularGlossiness: это устаревший путь, и он уже встречался в проблемных экспортах.
• Встроенные камеры и неиспользуемые источники света.

Ошибки для продуктовых сцен:

• Обязательные расширения, которые не поддерживает загрузчик runtime.
• Внешние скрипты, исполняемое содержимое или поведение, привязанное к конкретному движку.
• Абсолютные внешние URI ассетов, если пакет явно не является неизменяемым проверенным пакетом ассетов, размещённым на CDN.

ID правил валидатора

Агенты и валидаторы должны сообщать стабильные ID правил. Предлагаемые ID:

Машиночитаемый профиль

Ниже приведён исходный профиль валидатора в формате JSON. Он намеренно строже, чем набор старых сцен на staging.

{
  "sceneRequirementsVersion": 1,
  "defaultProfile": "desktop-standard",
  "format": {
    "schemaVersion": 1,
    "productionAssetExtensions": [".glb"],
    "fixtureAssetExtensions": [".glb", ".gltf"],
    "legacyOnlyExtensions": [".fbx"],
    "requiredProductFiles": ["scene.json", "scene.glb", "preview.webp|preview.jpg"],
    "forbiddenPathPatterns": ["..", "^/", "^[A-Za-z]:", "\\\\"]
  },
  "rights": {
    "required": true,
    "requiredClearedFor": ["staging", "production", "web-runtime", "screenshots", "optimization"],
    "forbidUnlicensedThirdPartyAssets": true,
    "forbidPriorCompanyTradeDress": true
  },
  "profiles": {
    "mobile-lite": {
      "maxBundleMb": 15,
      "maxGlbMb": 15,
      "maxRuntimeTriangles": 90000,
      "maxRuntimeObjects": 500,
      "maxRuntimeMeshes": 250,
      "maxRuntimeMaterials": 96,
      "maxRuntimeTextures": 48,
      "maxLoadMs": 20000
    },
    "desktop-standard": {
      "warnBundleMb": 25,
      "maxBundleMb": 40,
      "warnRuntimeTriangles": 150000,
      "maxRuntimeTriangles": 220000,
      "warnRuntimeObjects": 600,
      "maxRuntimeObjects": 1000,
      "warnRuntimeMeshes": 300,
      "maxRuntimeMeshes": 600,
      "warnRuntimeMaterials": 128,
      "maxRuntimeMaterials": 256,
      "warnRuntimeTextures": 64,
      "maxRuntimeTextures": 96,
      "warnLoadMs": 15000,
      "maxLoadMs": 30000
    },
    "xr": {
      "maxBundleMb": 25,
      "maxGlbMb": 25,
      "maxRuntimeTriangles": 120000,
      "maxRuntimeObjects": 500,
      "maxRuntimeMeshes": 300,
      "maxRuntimeMaterials": 128,
      "maxRuntimeTextures": 64,
      "maxLoadMs": 20000
    }
  },
  "scale": {
    "unit": "meter",
    "floorYDefault": 0,
    "floorYTolerance": 0.05,
    "normalIndoorMaxAxisM": 200,
    "manifestBoundsWarnRatio": 1.5,
    "manifestBoundsFailRatio": 3.0,
    "normalIndoorMinWidthDepthM": 4,
    "normalIndoorMaxWidthDepthM": 80,
    "normalIndoorMinHeightM": 2.4,
    "normalIndoorMaxHeightM": 20
  },
  "spawn": {
    "mainSpawnRequired": true,
    "floorToleranceM": 0.1,
    "wallMarginM": 0.5,
    "freeRadiusM": 0.75,
    "headClearanceM": 2.0
  },
  "seating": {
    "idPattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
    "yawMin": -3.141593,
    "yawMax": 3.141593,
    "radiusMinM": 0.35,
    "radiusMaxM": 0.8,
    "seatHeightMinM": 0,
    "seatHeightMaxM": 0.8,
    "minDistanceMultiplier": 1.5
  },
  "visual": {
    "requireLoadedState": true,
    "requireNoFailureReason": true,
    "maxMissingAssets": 0,
    "minAverageAlpha": 250,
    "warnDarkPixelRatio": 0.35,
    "maxDarkPixelRatio": 0.70,
    "warnAverageLuminance": 55,
    "minAverageLuminance": 40,
    "intentionalDarkRequiresHumanReview": true
  },
  "gltf": {
    "allowedExtensions": [
      "KHR_texture_transform",
      "KHR_materials_unlit",
      "KHR_materials_emissive_strength",
      "KHR_lights_punctual",
      "KHR_draco_mesh_compression",
      "EXT_meshopt_compression",
      "KHR_texture_basisu"
    ],
    "warnExtensions": [
      "KHR_animation_pointer",
      "KHR_materials_pbrSpecularGlossiness"
    ],
    "forbidUnsupportedRequiredExtensions": true
  }
}

Порядок приёмки

1. Статическая проверка манифеста: поля, пути, метаданные прав, структура пакета.
2. Статическая проверка ассетов: разбор GLB, ссылки на ресурсы, поддержка расширений, размеры файлов, размеры текстур, материалы, преобразования узлов, исходная статистика.
3. Локальная проверка в runtime: загрузка через runtime Vrata с ?debug=1&scenefit=0, проверка состояния loaded, читаемости скриншота, статистики runtime и отсутствующих ассетов.
4. Проверка на staging: публикация неизменяемого URL пакета, привязка тестовой комнаты и запуск тех же проверок runtime на staging.
5. Проверка человеком: убедиться, что сцена оригинальна, читаема, удобна для общения и визуально не происходит от старых сцен, защищённых авторским правом.

Критерии готовности новой сцены

• У сцены чистая история прав и нет творческого контента, скопированного у прежней компании.
• Есть scene.json, scene.glb, изображение превью и запись о лицензии и происхождении.
• Статические валидаторы не возвращают ошибок.
• Валидаторы runtime не возвращают ошибок для выбранного профиля.
• У каждого предупреждения есть явный владелец, причина и тикет на доработку.
• Проверяющий может понять назначение комнаты по первому виду из точки появления.
• Сцену можно добавить в комнату, изменив только метаданные, без изменений кода runtime.