📋 Configuration Schema Reference¶

interface ExperienceConfig {
  experience: ExperienceMetadata;
  stages: ExperienceStage[];
  navigation?: NavigationConfig;
}

interface ExperienceMetadata {
  title: string;              // Experience name
  description?: string;       // Brief description
  author?: string;            // Creator name
  thumbnailUrl?: string;      // Preview image URL
  createdAt?: string;         // ISO 8601 timestamp
  updatedAt?: string;         // ISO 8601 timestamp
}

interface ExperienceStage {
  id: string;                     // Unique identifier
  name: string;                   // Display name
  skybox?: SkyboxConfig;          // 360° background
  models?: ModelConfig[];         // 3D models
  planes?: PlaneConfig[];         // 2D planes (images/videos)
  lights?: LightConfig[];         // Scene lighting
  hotspots?: HotspotConfig[];     // Interactive hotspots
  audioUrl?: string;              // Background audio
  audioVolume?: number;           // 0-1, default 1
  audioLoop?: boolean;            // Loop audio, default true
  location?: GeoCoordinates;      // Geographic position
  initialCameraTarget?: Vector3Config;  // Where camera looks (first stage only)
}

interface Vector3Config {
  x: number;  // X coordinate
  y: number;  // Y coordinate
  z: number;  // Z coordinate
}

interface GeoCoordinates {
  lat: number;  // Latitude (-90 to 90)
  lng: number;  // Longitude (-180 to 180)
}

interface SkyboxConfig {
  type: 'video' | 'image' | 'color';
  url?: string;                   // Media URL (required for video/image)
  hlsUrl?: string;                // HLS manifest URL (.m3u8) for streaming
  thumbnailUrl?: string;          // Preview image (video only)
  color?: string;                 // Hex color (type='color')
  autoplay?: boolean;             // Video: auto-play, default true
  loop?: boolean;                 // Video: loop, default true
  rotation?: number;              // Rotation in degrees, default 0

  // Multi-variant support (advanced)
  variants?: {
    desktop?: TextureVariant;
    mobile?: TextureVariant;
    tablet?: TextureVariant;
    vr?: TextureVariant;
    fallback: TextureVariant;     // Required
  };
}

interface TextureVariant {
  url: string;
  format: 'ktx2-uastc' | 'ktx2-etc1s' | 'jpg' | 'png';
  resolution?: string;            // e.g., "4096x2048"
  quality?: number;               // ETC1S quality (1-255)
  fileSize?: number;              // Bytes
}

interface HotspotConfig {
  id: string;                     // Unique ID
  position: Vector3Config;        // 3D position
  type: 'info' | 'audio' | 'both' | 'navigation';

  // Visual customization
  color?: string;                 // Hex color, default "#4A90E2"
  size?: number;                  // Radius in meters
  opacity?: number;               // 0-1, default 0.9
  label?: string;                 // Text label
  customIconUrl?: string;         // Custom PNG icon URL

  // Portal-specific (navigation type)
  targetStageId?: string;         // Which stage to navigate to
  portalEffectStyle?: PortalEffectStyle;
  portalRestSize?: number;        // Scale at rest
  portalHoverSize?: number;       // Scale on hover
  portalColor?: string;           // Hex color
  initialViewDirection?: Vector3Config;  // Camera look direction

  // Info content (info/both types)
  infoTitle?: string;
  infoBody?: string;
  infoImageUrl?: string;
  infoImageAspectRatio?: number;  // Width/height
  infoVideoUrl?: string;
  infoLinks?: InfoLink[];

  // Audio (audio/both types)
  audioUrl?: string;
  audioLoop?: boolean;            // Default true
  audioVolume?: number;           // 0-1, default 1
  audioSpatial?: boolean;         // 3D spatial audio, default true
  audioRolloffFactor?: number;    // Distance attenuation, default 1
  audioMaxDistance?: number;      // Max audible distance, default 100
}

type PortalEffectStyle =
  | 'liquid'      // Flowing liquid metal
  | 'shimmer'     // Shimmering particles
  | 'warp'        // Space-time warp
  | 'minimal';    // Simple glow

interface InfoLink {
  label: string;     // Link text
  url: string;       // URL
  icon?: string;     // Icon name
}

interface NavigationConfig {
  type: 'floorplan' | 'map' | 'none';
  showMinimap?: boolean;          // Show corner minimap, default true
  markers: NavigationMarker[];

  // Map-specific
  mapConfig?: {
    tileLayer?: string;           // 'streets' | 'satellite' | 'outdoors' | 'dark'
    initialZoom?: number;         // Default 15
    maxZoom?: number;             // Default 18
    minZoom?: number;             // Default 10
  };

  // Floor plan-specific
  floorPlan?: FloorPlanConfig;    // Single floor
  floorPlans?: FloorPlanConfig[]; // Multi-floor

  // Legacy (deprecated)
  displayMode?: 'minimap' | 'fullscreen' | 'both' | 'none';
  minimapPosition?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
  minimapSize?: 'small' | 'medium' | 'large';
}

interface NavigationMarker {
  stageId: string;                // Which stage?
  label?: string;                 // Display name

  // Geographic (maps)
  geoPosition?: GeoCoordinates;

  // Floor plan
  floorPlanPosition?: FloorPlanPosition;

  // Visual
  icon?: 'default' | 'star' | 'info' | 'camera' | 'video' | 'audio';
  customIconUrl?: string;
  color?: string;

  // Metadata
  placeName?: string;             // From geocoding
}

interface FloorPlanPosition {
  x: number;  // 0-1 (0=left, 1=right)
  y: number;  // 0-1 (0=top, 1=bottom)
}

interface FloorPlanConfig {
  floor?: number;                 // Floor number (1-indexed)
  name?: string;                  // Floor name
  imageUrl: string;               // Floor plan image
}

interface ModelConfig {
  id?: string;                    // Optional ID
  url: string;                    // Model URL
  position?: Vector3Config;       // Position, default {0,0,0}
  rotation?: Vector3Config;       // Rotation (radians), default {0,0,0}
  scale?: Vector3Config | number; // Scale, default 1
}

interface PlaneConfig {
  type: 'image' | 'video';
  url: string;
  hlsUrl?: string;                // HLS for video
  position?: Vector3Config;
  rotation?: Vector3Config;       // Radians
  scale?: { width: number; height: number };
  autoplay?: boolean;             // Video only
  loop?: boolean;                 // Video only
  muted?: boolean;                // Video only
}

interface LightConfig {
  type: 'hemispheric' | 'directional' | 'point' | 'spot';
  intensity?: number;             // 0-2, default 1
  diffuse?: string;               // Hex color, default "#FFFFFF"
  specular?: string;              // Hex color, default "#FFFFFF"

  // Hemispheric only
  groundColor?: string;

  // Directional/Hemispheric
  direction?: Vector3Config;

  // Point/Spot
  position?: Vector3Config;
  range?: number;

  // Spot only
  angle?: number;                 // Radians
  exponent?: number;              // 0-128
}