Scene requirements

This document defines the target requirements for new Vrata scenes. It is based on the current Scene Bundle v1 runtime contract and on diagnostics from the legacy exported staging scenes. The legacy scenes are useful only as technical probes. New scenes must be original or properly licensed and must not copy their meshes, textures, layouts, names, trade dress, or distinctive visual composition.

The default project-authored workflow is defined by docs/arch/2026-08-29-agentic-deterministic-scene-authoring.md. These requirements validate the resulting scene and remain independent of the LLM, agent orchestrator, DCC, or repository topology used during authoring.

Goals

Every scene also follows the shared quality contract and task packet. Technical compatibility, reproducibility and image-regression thresholds cannot close its User/Builder/Physics or visual-quality gates. Inherit those requirements for every room type.

• Make scene requirements understandable to a human scene author: what a good room should feel like, where users spawn, what must be visible, and what must not be copied.
• Make scene requirements understandable to an agent or validator: exact fields, numeric budgets, severity levels, and runtime checks.
• Separate technical compatibility from legal clearance. A scene can be technically valid and still be forbidden if rights are not cleared.
• Prefer scenes that work in the main runtime path without custom runtime patches, broad material overrides, or one-off scene-specific code.

Human Requirements

Originality And Rights

• The scene must be newly authored for Vrata, generated from Vrata-owned assets, or built from assets with explicit commercial web/XR rights.
• The scene must not reproduce the prior company's scene layouts, object arrangements, branded interiors, visual identity, or distinctive material palette.
• Every non-original asset must have a recorded license, source URL or vendor ID, author, allowed usage, and proof that web, staging, production, screenshots, and derivative optimization are permitted.
• The bundle must not contain private local paths, employee names, prior-company project paths, or source-system identifiers that cannot be published.

User Experience

• On first load, the user must see a recognizable room, floor, nearby objects, and a plausible direction of travel from the main spawn.
• The first view must not be black, mostly empty, inside geometry, facing a wall at close range, or outside the room.
• The scene should have a clear social purpose: meeting room, gallery, classroom, hall, showroom, stage, office, lounge, or another explicit room type.
• Walkable floor, seating, display surfaces, and important focal objects should be visually distinguishable without debug modes.
• Desktop and mobile users must be able to orient themselves without VR-only assumptions.
• VR users must have enough head clearance around spawn and seating areas.

Runtime Fit

• The scene must work through the standard Scene Bundle path. Do not add scene-specific runtime code for product scenes.
• The scene must remain usable with the fallback environment hidden and the platform display surface still visible.
• If renderMode is clean, the scene must remain readable with the current clean-mode ambient-light setup.
• The scene must not rely on Unity scripts, Unity-only shaders, gameplay triggers, post-processing volumes, or engine behavior that the web runtime does not execute.

Bundle Layout

Production bundles should use this layout:

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

Rules:

• scene.json is the only file a room manifest points to.
• scene.glb is the production asset format. .gltf is acceptable only for tiny test fixtures. .fbx is legacy-only and must not be used for new production scenes.
• preview.webp or preview.jpg is required for catalog use.
• LICENSES.md is required for any scene that is not 100% internally authored.
• All paths inside the bundle must be relative and must not contain .., absolute paths, or backslashes.

Manifest Requirements

The runtime currently parses Scene Bundle v1. Validators for new scenes should be stricter than the runtime parser.

Recommended rights block:

{
  "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"
      }
    ]
  }
}

Coordinate And Scale Requirements

• One scene unit must equal one meter.
• The main walkable floor should be at y=0, with tolerance +-0.05m.
• Player eye height is approximately 1.6m; spawn and seats must not place the camera inside ceilings, props, or walls.
• Indoor product scenes should normally fit within 4m <= width/depth <= 80m and 2.4m <= height <= 20m.
• Runtime computed bounding boxes must be finite and must not exceed 200m on any axis for normal indoor scenes.
• Runtime computed bounds should be within 1.5x of manifest bounds on each axis. A larger ratio is a warning; a ratio above 3x is a failure unless the scene declares and documents a special world scale profile.
• scene.json positions must use runtime coordinates after all DCC/export axis transforms. For the standard Blender Y-up authoring path, semantic (x, y, z) maps to runtime (x, y, -z); validators must compare spawn, seats, and media surfaces through one explicit adapter.
• Remove or exclude helper objects, collider meshes, cameras, rig controls, hidden export planes, test cubes, and giant background geometry from the runtime GLB.
• Node transforms with extreme scale, position, or rotation should be rejected unless they are intentionally documented and do not affect bounds or interaction.

Spawn Requirements

The first spawn point is the runtime entry point today.

Spawn staging checks must use ?debug=1&scenefit=0. Debug auto-fit is enabled by default with ?debug=1 and replaces the manifest spawn, so a screenshot or pose captured without scenefit=0 is not spawn evidence.

Seating And Interaction Anchors

Seat anchors are domain metadata, not decorative mesh names.

• Seat IDs must be unique lower-kebab strings and should be prefixed by the scene ID or room area.
• position is the avatar root target. It must be close to the visual seat surface and reachable from the floor.
• yaw is radians, normalized to [-pi, pi], and should face the intended social/focal direction.
• seatHeight is added to position.y for the seated avatar root and should normally be between 0 and 0.8.
• radius should normally be between 0.35 and 0.8 meters.
• Seat anchor centers should not overlap. Distance between two centers should be at least max(radiusA, radiusB) * 1.5 unless bench seating explicitly allows closer spacing.
• A visible chair/bench/sofa promised by the scene should have an anchor or be clearly non-interactive.
• Anchors must not put the avatar inside tables, walls, arm rests, or other seated avatars.
• Teleport floor and seat anchors must use the same coordinate scale as the GLB.

Geometry Requirements

• Export only visible runtime geometry plus intentional collision/interaction proxy objects if the runtime explicitly supports them.
• Keep object count and mesh count low by merging static meshes when that does not harm culling, materials, or authoring workflow.
• Remove duplicate invisible meshes, editor helpers, unused cameras, unused lights, and unused animations.
• Avoid thin one-sided planes for walls, floors, and large furniture unless backface visibility is intentionally handled.
• Transparent foliage and glass must be tested in the runtime, not only in the DCC/Unity viewport.
• No mesh should contain NaN, infinite values, zero-scale transforms, or degenerate bounding boxes.

Material And Lighting Requirements

• Prefer glTF PBR materials compatible with THREE.MeshStandardMaterial.
• Use baked base-color/emissive textures when the look depends on authored lighting.
• Use KHR_materials_unlit only for intentionally unlit/baked surfaces, UI-like labels, or signage.
• Avoid legacy/spec-gloss material paths for new exports. KHR_materials_pbrSpecularGlossiness is a warning today and should become a failure for product scenes.
• Do not rely on Unity Shader Graph, custom Unity shaders, lightmap-only materials, post-processing, reflection probes, or camera effects that are not exported into web-compatible material data.
• Material names should be stable and meaningful. Names like Hidden/UnityGLTF/..., Tantular SDF Material, Material.024, or unconverted shader placeholders should be warnings because they make targeted validation and debugging harder.
• At least 60% of visible runtime materials should be textured or deliberately colored with validated non-black colors.
• This percentage is only a technical floor. Material finish, detail scale, orientation, lighting response and close-up appearance must pass the shared quality contract; a uniformly colored toy-like scene can satisfy the count and still require rework.
• Broad wildcard material overrides are forbidden for product acceptance. Fix materials at export/source level.
• Large black materials are allowed only when semantically black and when the scene still passes visual readability from spawn.

Texture Requirements

• Textures must be embedded in the GLB or referenced relatively inside the bundle.
• Missing runtime assets are a hard failure.
• Prefer WebP, PNG, JPEG, or KTX2/Basis where supported by the pipeline.
• Texture dimensions should be powers of two unless there is a documented reason.
• Default maximum texture size is 2048x2048; 4096x4096 is allowed only for hero surfaces and counts as a warning.
• Avoid many nearly identical material/texture variants. Atlas or reuse where possible.
• Use sRGB for base color and linear data for normal/roughness/metalness/AO maps.

Performance Budgets

Budgets are per scene bundle profile. Validators should support profile selection and default to desktop-standard for staging rooms.

Notes:

• These budgets intentionally push new scenes below the heaviest legacy scenes.
• A scene can exceed a warning budget only with a documented reason and a human visual/performance sign-off.
• A scene that exceeds a fail budget must not be marked production-ready.

Runtime Visual Acceptance

Runtime acceptance must be measured in the real Vrata browser runtime, not only through static GLB inspection.

Required command shape for automated checks:

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

Hard failures:

• sceneBundleState !== "loaded".
• sceneDebug.failureReason !== null.
• sceneDebug.missingAssets.length > 0.
• sceneDebug.screenshot.averageColor.a < 250 for normal opaque scenes.
• sceneDebug.screenshot.darkPixelRatio > 0.70 unless visual.intentionalDark is approved.
• Average screenshot luminance below 40 for normal scenes.
• Runtime computed bounds exceed 200m on any axis for normal indoor scenes.
• The first view is inside geometry, outside the room, or not human-readable even if numeric thresholds pass.

Warnings:

• sceneDebug.screenshot.darkPixelRatio > 0.35.
• Average screenshot luminance below 55.
• More than 25% of top material samples are untextured near-black materials.
• Top material sample names show unconverted shader placeholders.
• Runtime load time exceeds the profile warning budget.

Intentional dark scenes:

• Must declare visual.intentionalDark: true in metadata.
• Must still show navigable floor, silhouettes, exits/focal zones, seats, and interactable surfaces.
• Must include at least one bright focal region or guidance cue in the first view.
• Must pass human review on desktop and VR before staging promotion.

Supported glTF Features

Allowed for product scenes:

• Core glTF 2.0 .glb.
• KHR_texture_transform.
• KHR_materials_unlit, when intentional.
• KHR_materials_emissive_strength, when tested in runtime.
• KHR_lights_punctual, when not required for basic visibility.
• KHR_draco_mesh_compression, if decode is tested in runtime.
• EXT_meshopt_compression, if decode is tested in runtime.
• KHR_texture_basisu, if KTX2 transcode is tested in runtime.

Warnings for product scenes:

• KHR_animation_pointer, because current room scenes are expected to be static unless animation support is explicitly scoped.
• KHR_materials_pbrSpecularGlossiness, because it is a legacy path and has already appeared in problematic exports.
• Embedded cameras and unused lights.

Failures for product scenes:

• Required extensions not supported by the runtime loader.
• External scripts, executable content, or engine-specific behavior.
• Absolute external asset URIs unless the bundle is explicitly a CDN-hosted, immutable, reviewed asset package.

Validator Rule IDs

Agents and validators should report stable rule IDs. Suggested IDs:

Machine-Readable Profile

The following JSON is the initial validator profile. It is intentionally stricter than the legacy staging corpus.

{
  "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
  }
}

Acceptance Flow

1. Static manifest validation: fields, paths, rights metadata, bundle layout.
2. Static asset validation: GLB parse, resource references, extension support, sizes, texture dimensions, materials, node transforms, raw stats.
3. Runtime local validation: load through Vrata runtime with ?debug=1&scenefit=0, assert loaded state, screenshot readability, runtime stats, missing assets.
4. Staging validation: publish immutable bundle URL, bind a test room, run the same runtime checks against staging.
5. Human review: confirm the scene is original, readable, socially usable, and not visually derived from the legacy copyrighted scenes.

Definition Of Ready For A New Scene

• It has a clean rights record and no copied prior-company creative content.
• It has a scene.json, scene.glb, preview image, and license/provenance record.
• Static validators return no failures.
• Runtime validators return no failures under the selected profile.
• Any warnings have an explicit owner, reason, and follow-up ticket.
• A human reviewer can understand the room purpose from the first spawn view.
• The scene can be added to a room by changing metadata only, without runtime code changes.