otherplane 0.1.0

package/engine/src/components/scene/Artifacts.tsx

@@ -0,0 +1,85 @@
+'use client';
+
+// Artifacts. Lives inside the Canvas. Detects when the player is near an artifact
+// AND looking at it (gaze from the camera/eye, 3D — artifacts can be above/below
+// eye level), reports it active so a DOM hint can show, and opens its URL when E
+// is pressed. The doorway/object in the splat IS the artifact — no visual marker.
+
+import { useEffect, useMemo, useRef } from 'react';
+import { useFrame, useThree } from '@react-three/fiber';
+import * as THREE from 'three';
+import { useRapierWorld } from '@/physics';
+import { usePointerLock } from '@/providers/pointerLock';
+import type { Artifact } from '@/data/room';
+
+const INTERACT_CODE = 'KeyE';
+const GAZE_DOT = Math.cos((45 * Math.PI) / 180); // within ~45° of looking at it
+
+export default function Artifacts({
+  artifacts,
+  onOpen,
+  onActiveChange,
+}: {
+  artifacts: Artifact[];
+  onOpen: (url: string) => void;
+  onActiveChange: (active: boolean) => void;
+}) {
+  const { playerBody } = useRapierWorld();
+  const { camera } = useThree();
+  const { isLocked } = usePointerLock();
+  const activeRef = useRef<string | null>(null);
+  const fwd = useMemo(() => new THREE.Vector3(), []);
+  const eye = useMemo(() => new THREE.Vector3(), []);
+
+  const setActive = useMemo(
+    () => (url: string | null) => {
+      if (activeRef.current !== url) {
+        activeRef.current = url;
+        onActiveChange(url != null);
+      }
+    },
+    [onActiveChange],
+  );
+
+  useFrame(() => {
+    if (!playerBody || artifacts.length === 0 || !isLocked) {
+      setActive(null);
+      return;
+    }
+    camera.getWorldPosition(eye);
+    camera.getWorldDirection(fwd); // normalized
+
+    let active: string | null = null;
+    for (const a of artifacts) {
+      const r = a.radius || 1.0;
+      const dx = a.pos[0] - eye.x;
+      const dy = a.pos[1] - eye.y;
+      const dz = a.pos[2] - eye.z;
+      const dist2 = dx * dx + dy * dy + dz * dz;
+      if (dist2 > r * r) continue;
+      const dLen = Math.sqrt(dist2) || 1;
+      const dot = (dx / dLen) * fwd.x + (dy / dLen) * fwd.y + (dz / dLen) * fwd.z;
+      if (dot >= GAZE_DOT) {
+        active = a.url;
+        break;
+      }
+    }
+    setActive(active);
+  });
+
+  // Interact key opens the active artifact's URL.
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.code !== INTERACT_CODE) return;
+      const url = activeRef.current;
+      if (url) {
+        setActive(null);
+        onOpen(url);
+      }
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [onOpen, setActive]);
+
+  return null;
+}

package/engine/src/components/scene/Exits.tsx

@@ -0,0 +1,92 @@
+'use client';
+
+// Exits. Lives inside the Canvas. Given the current room's exits, it (1) detects
+// when the player is near an exit AND looking at it, reporting it as "active" so a
+// DOM hint ("Press E") can show, and (2) follows the exit's link when E is pressed
+// while one is active. No visual marker — the doorway in the splat IS the exit.
+
+import { useEffect, useMemo, useRef } from 'react';
+import { useFrame, useThree } from '@react-three/fiber';
+import * as THREE from 'three';
+import { useRapierWorld } from '@/physics';
+import { usePointerLock } from '@/providers/pointerLock';
+import type { Exit } from '@/data/room';
+
+const INTERACT_CODE = 'KeyE';
+const GAZE_DOT = Math.cos((45 * Math.PI) / 180); // within ~45° of looking at it
+
+export default function Exits({
+  exits,
+  onExit,
+  onActiveChange,
+}: {
+  exits: Exit[];
+  onExit: (to: string) => void;
+  onActiveChange: (active: boolean) => void;
+}) {
+  const { playerBody } = useRapierWorld();
+  const { camera } = useThree();
+  const { isLocked } = usePointerLock();
+  const activeRef = useRef<string | null>(null);
+  const armAt = useRef(0); // suppress interaction until performance.now() >= this
+  const fwd = useMemo(() => new THREE.Vector3(), []);
+
+  const setActive = useMemo(
+    () => (to: string | null) => {
+      if (activeRef.current !== to) {
+        activeRef.current = to;
+        onActiveChange(to != null);
+      }
+    },
+    [onActiveChange],
+  );
+
+  // On room switch, clear the active exit and suppress interaction for a beat
+  // while the player settles into the new room.
+  useEffect(() => {
+    armAt.current = performance.now() + 600;
+    setActive(null);
+  }, [exits, setActive]);
+
+  useFrame(() => {
+    if (!playerBody || exits.length === 0 || !isLocked || performance.now() < armAt.current) {
+      setActive(null);
+      return;
+    }
+    const p = playerBody.translation();
+    camera.getWorldDirection(fwd);
+    const fhLen = Math.hypot(fwd.x, fwd.z) || 1;
+
+    let active: string | null = null;
+    for (const e of exits) {
+      const r = e.radius || 1.3;
+      const dx = e.pos[0] - p.x;
+      const dz = e.pos[2] - p.z;
+      if (dx * dx + dz * dz > r * r) continue;
+      // gaze: is the exit roughly in front of where we're looking?
+      const dLen = Math.hypot(dx, dz) || 1;
+      const dot = (dx / dLen) * (fwd.x / fhLen) + (dz / dLen) * (fwd.z / fhLen);
+      if (dot >= GAZE_DOT) {
+        active = e.to;
+        break;
+      }
+    }
+    setActive(active);
+  });
+
+  // Interact key follows the active exit's link.
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.code !== INTERACT_CODE) return;
+      const to = activeRef.current;
+      if (to && performance.now() >= armAt.current) {
+        setActive(null);
+        onExit(to);
+      }
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [onExit, setActive]);
+
+  return null;
+}

package/engine/src/components/scene/PointerLockBridge.tsx

@@ -0,0 +1,28 @@
+'use client';
+
+import { useEffect } from 'react';
+import { useThree } from '@react-three/fiber';
+import { PointerLockControls } from 'three/examples/jsm/controls/PointerLockControls.js';
+import { usePointerLockRegistration } from '@/providers/pointerLock';
+
+export default function PointerLockBridge() {
+  const { camera, gl } = useThree();
+  const { register } = usePointerLockRegistration();
+
+  useEffect(() => {
+    const controls = new PointerLockControls(camera, gl.domElement);
+
+    // optional tuning
+    controls.pointerSpeed = 1.0;
+    controls.minPolarAngle = 0;           // looking straight up/down clamp
+    controls.maxPolarAngle = Math.PI;     // leave default free
+
+    register(controls);
+    return () => {
+      register(null);
+      controls.dispose();
+    };
+  }, [camera, gl, register]);
+
+  return null;
+}

package/engine/src/components/scene/WorldScene.tsx

@@ -0,0 +1,164 @@
+'use client';
+
+import React, { useCallback, useRef } from 'react';
+import { Canvas } from '@react-three/fiber';
+
+import SparkLayer from '@/components/spark/SparkLayer';
+import SplatWorld from '@/components/spark/SplatWorld';
+import PlayerController from '@/components/controls/PlayerController';
+import PointerLockBridge from '@/components/scene/PointerLockBridge';
+import TouchLookController from '@/components/controls/TouchLookController';
+import EditCapture from '@/components/edit/EditCapture';
+import Markers from '@/components/edit/Markers';
+import Exits from '@/components/scene/Exits';
+import ArtifactsLayer from '@/components/scene/Artifacts';
+import type { WorldDef } from '@/data/presets';
+import type { Exit, Artifact } from '@/data/room';
+
+type Props = {
+  world: WorldDef;
+  playerMoveSpeed?: number;
+  onLoadingChange?: (isLoading: boolean, error?: string) => void;
+  mobileInputRef?: React.MutableRefObject<{x:number;y:number}>;
+  exits?: Exit[];
+  onExit?: (to: string) => void;
+  onActiveExitChange?: (active: boolean) => void;
+  artifacts?: Artifact[];
+  onArtifactOpen?: (url: string) => void;
+  onActiveArtifactChange?: (active: boolean) => void;
+  spawnYaw?: number;
+  spawnKey?: string;
+};
+
+function SceneInner({
+  world,
+  playerMoveSpeed,
+  onLoadingChange,
+  mobileInputRef,
+  exits,
+  onExit,
+  onActiveExitChange,
+  artifacts,
+  onArtifactOpen,
+  onActiveArtifactChange,
+  spawnYaw,
+  spawnKey }: Props) {
+  const localMobileInputRef = useRef<{x:number;y:number}>({x:0,y:0});
+  const inputRef = mobileInputRef || localMobileInputRef;
+
+  const handleLoadingChange = useCallback((loading: boolean, error?: string) => {
+    onLoadingChange?.(loading, error);
+  }, [onLoadingChange]);
+
+  return (
+    <>
+      {/* FPS-style player controls */}
+      <PlayerController
+        mobileInputRef={inputRef}
+        moveSpeed={playerMoveSpeed}
+        spawnYaw={spawnYaw}
+        spawnKey={spawnKey}
+      />
+
+      {/* Edit-mode marking capture + marker orbs (no-op unless edit mode) */}
+      <EditCapture />
+      <Markers />
+
+      {/* Exits → links to other rooms */}
+      {exits && onExit && (
+        <Exits
+          exits={exits}
+          onExit={onExit}
+          onActiveChange={onActiveExitChange ?? (() => {})}
+        />
+      )}
+
+      {/* Artifacts → open a web URL in an overlay */}
+      {artifacts && onArtifactOpen && (
+        <ArtifactsLayer
+          artifacts={artifacts}
+          onOpen={onArtifactOpen}
+          onActiveChange={onActiveArtifactChange ?? (() => {})}
+        />
+      )}
+
+      {/* Touch-based camera look for mobile */}
+      <TouchLookController />
+
+      {/* Spark renderer + the current Splat world */}
+      <SparkLayer />
+      <SplatWorld
+        key={world.url}
+        url={world.url}
+        position={world.position}
+        quaternion={world.quaternion}
+        scale={world.scale}
+        onLoadingChange={handleLoadingChange}
+      />
+
+      {/* Usual lighting for mesh-based objects */}
+      <ambientLight intensity={0.5} />
+      <directionalLight position={[5, 10, 5]} intensity={0.8} />
+    </>
+  );
+}
+
+export default function WorldScene({
+  world,
+  playerMoveSpeed,
+  onLoadingChange,
+  mobileInputRef,
+  exits,
+  onExit,
+  onActiveExitChange,
+  artifacts,
+  onArtifactOpen,
+  onActiveArtifactChange,
+  spawnYaw,
+  spawnKey }: Props) {
+  const handleLoadingChange = useCallback((loading: boolean, error?: string) => {
+    onLoadingChange?.(loading, error);
+  }, [onLoadingChange]);
+
+  // Cap DPR more aggressively on mobile for performance
+  const dprCap = typeof window !== 'undefined' && matchMedia('(pointer: coarse)').matches ? 1.0 : 1.5;
+
+  return (
+    <div className="canvas-root absolute inset-0">
+      <Canvas
+      // Spark guidance: leave antialias off for better performance with splats
+      gl={{
+        antialias: false,
+        // Avoid preserveDrawingBuffer; it increases memory pressure
+        preserveDrawingBuffer: false,
+        // Enable context loss recovery
+        failIfMajorPerformanceCaveat: false,
+        // Power preference for better compatibility
+        powerPreference: "high-performance"
+      }}
+      dpr={[1, dprCap]}
+      // Disable shadows for now to reduce GPU pressure
+      shadows={false}
+      camera={{ fov: 60, near: 0.1, far: 1000, position: [0, 1.2, 3] }}
+    >
+      <PointerLockBridge />
+      <TouchLookController />
+
+      <SceneInner
+        world={world}
+        playerMoveSpeed={playerMoveSpeed}
+        onLoadingChange={handleLoadingChange}
+        mobileInputRef={mobileInputRef}
+        exits={exits}
+        onExit={onExit}
+        onActiveExitChange={onActiveExitChange}
+        artifacts={artifacts}
+        onArtifactOpen={onArtifactOpen}
+        onActiveArtifactChange={onActiveArtifactChange}
+        spawnYaw={spawnYaw}
+        spawnKey={spawnKey}
+      />
+    </Canvas>
+    </div>
+  );
+}

package/engine/src/components/spark/SparkLayer.tsx

@@ -0,0 +1,112 @@
+'use client';
+
+import { useEffect, useRef, useCallback } from 'react';
+import { useThree } from '@react-three/fiber';
+import type { SparkRenderer } from '@sparkjsdev/spark';
+
+/**
+ * Adds a SparkRenderer and parents it to the camera.
+ * Per docs, putting SparkRenderer under the camera improves precision across large scenes.
+ */
+export default function SparkLayer() {
+  const { gl, camera, scene, invalidate } = useThree();
+  const sparkRef = useRef<SparkRenderer | null>(null);
+  // Keep a symbol on WebGLRenderer to avoid double SparkRenderer attachment
+  const SPARK_TAG = '__spark_attached__' as const;
+  const contextLostRef = useRef(false);
+
+  const initializeSparkRenderer = useCallback(async () => {
+    try {
+      // Clean up existing renderer if it exists
+      if (sparkRef.current) {
+        camera.remove(sparkRef.current);
+        sparkRef.current = null;
+      }
+
+      // Ensure we only attach one SparkRenderer per WebGLRenderer
+      if ((gl as unknown as Record<string, unknown>)[SPARK_TAG]) {
+        console.log('SparkRenderer already attached to this WebGLRenderer');
+        return;
+      }
+
+      // Create SparkRenderer with the existing WebGL context (conservative settings)
+      const { SparkRenderer } = await import('@sparkjsdev/spark');
+      const spark = new SparkRenderer({
+        renderer: gl,
+        // Lower splat pixel radius to reduce overdraw and memory pressure
+        maxPixelRadius: 256,
+        // Slightly reduce kernel width to limit very large splats
+        maxStdDev: Math.sqrt(6),
+        // Keep alpha threshold modest to limit long tails
+        minAlpha: 1 / 255,
+      });
+      
+      sparkRef.current = spark;
+      camera.add(spark); // follows camera; improves float16 locality
+      (gl as unknown as Record<string, unknown>)[SPARK_TAG] = true;
+      
+      // ensure camera is in the scene graph
+      if (!camera.parent) scene.add(camera);
+      
+      console.log('SparkRenderer initialized successfully');
+      // Log GL caps/extensions for diagnostics
+      try {
+        const webgl2 = (gl.domElement as HTMLCanvasElement).getContext('webgl2') as WebGL2RenderingContext | null;
+        const webgl = webgl2 ?? ((gl.domElement as HTMLCanvasElement).getContext('webgl') as WebGLRenderingContext | null);
+        const glCtx: WebGLRenderingContext | WebGL2RenderingContext | null = webgl;
+        const debugInfo = glCtx ? {
+          version: glCtx.getParameter(glCtx.VERSION),
+          shadingLanguageVersion: glCtx.getParameter(glCtx.SHADING_LANGUAGE_VERSION),
+          vendor: glCtx.getParameter(glCtx.VENDOR),
+          renderer: glCtx.getParameter(glCtx.RENDERER),
+          maxTextureSize: gl.capabilities.maxTextureSize,
+          isWebGL2: 'bindBufferBase' in glCtx,
+        } : null;
+        console.log('GL diagnostics', debugInfo);
+      } catch {}
+      contextLostRef.current = false;
+      
+    } catch (error) {
+      console.error('Failed to initialize SparkRenderer:', error);
+    }
+  }, [gl, camera, scene]);
+
+  useEffect(() => {
+    initializeSparkRenderer();
+
+    // Add WebGL context loss handlers
+    const handleContextLost = (event: Event) => {
+      console.warn('WebGL context lost, preventing default behavior');
+      contextLostRef.current = true;
+      event.preventDefault();
+    };
+
+    const handleContextRestored = () => {
+      console.log('WebGL context restored, reinitializing...');
+      // Small delay to ensure context is fully restored
+      setTimeout(() => {
+        initializeSparkRenderer();
+        invalidate(); // Force a re-render
+        // Dispatch a custom event to notify other components
+        window.dispatchEvent(new CustomEvent('webgl-context-restored'));
+      }, 100);
+    };
+
+    gl.domElement.addEventListener('webglcontextlost', handleContextLost);
+    gl.domElement.addEventListener('webglcontextrestored', handleContextRestored);
+
+    return () => {
+      gl.domElement.removeEventListener('webglcontextlost', handleContextLost);
+      gl.domElement.removeEventListener('webglcontextrestored', handleContextRestored);
+      
+      if (sparkRef.current) {
+        camera.remove(sparkRef.current);
+        sparkRef.current = null;
+      }
+      // Clear the tag so a new SparkRenderer can be attached after dispose
+      delete (gl as unknown as Record<string, unknown>)[SPARK_TAG];
+    };
+  }, [gl, camera, scene, initializeSparkRenderer, invalidate]);
+
+  return null;
+}

package/engine/src/components/spark/SplatWorld.tsx

@@ -0,0 +1,156 @@
+'use client';
+
+import { useEffect, useRef, useState, useCallback } from 'react';
+import { useThree } from '@react-three/fiber';
+import type { SplatMesh } from '@sparkjsdev/spark';
+
+type Props = {
+  url: string;
+  position?: [number, number, number];
+  quaternion?: [number, number, number, number]; // x,y,z,w
+  scale?: number;
+  onLoadingChange?: (isLoading: boolean, error?: string) => void;
+};
+
+/**
+ * Imperatively adds a SplatMesh to the scene (simplest interop).
+ * You could also "extend" Spark classes to use JSX <primitive />, but this is robust & minimal.
+ */
+export default function SplatWorld({ url, position = [0, 0, 0], quaternion, scale = 1, onLoadingChange }: Props) {
+  const { scene } = useThree();
+  const meshRef = useRef<SplatMesh | null>(null);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+
+  const loadSplatMesh = useCallback(async () => {
+    // token to ignore stale async completions
+    const loadToken = crypto.randomUUID();
+    (loadSplatMesh as unknown as { currentToken?: string }).currentToken = loadToken;
+
+    setLoadError(null);
+    setIsLoading(true);
+
+    // Clean up existing mesh first
+    if (meshRef.current) {
+      scene.remove(meshRef.current);
+      try { 
+        meshRef.current.dispose?.(); 
+      } catch (error) {
+        console.warn('Error disposing existing splat mesh:', error);
+      }
+      meshRef.current = null;
+    }
+    
+    try {
+      const t0 = performance.now();
+      console.log(`Loading splat mesh from: ${url}`);
+        
+        // Check if URL is accessible (for local files)
+        let abortController: AbortController | null = null;
+        if (url.startsWith('/')) {
+          try {
+            abortController = new AbortController();
+            const response = await fetch(url, { method: 'HEAD', signal: abortController.signal });
+            if (!response.ok) {
+              throw new Error(`Failed to load ${url}: ${response.status} ${response.statusText}`);
+            }
+          } catch (fetchError) {
+            console.error('Failed to fetch splat file:', fetchError);
+            setLoadError(`Failed to load splat file: ${url}`);
+            setIsLoading(false);
+            return;
+          }
+        }
+
+        // If a newer call started, bail out before heavy work
+        if ((loadSplatMesh as unknown as { currentToken?: string }).currentToken !== loadToken) {
+          abortController?.abort();
+          return;
+        }
+
+        const { SplatMesh } = await import('@sparkjsdev/spark');
+        const mesh = new SplatMesh({ url });
+        meshRef.current = mesh;
+        const t1 = performance.now();
+        // Wait for mesh to be initialized before setting transform
+        try {
+          await mesh.initialized;
+          const t2 = performance.now();
+          
+          // If a newer load started or component unmounted, dispose and stop
+          if ((loadSplatMesh as unknown as { currentToken?: string }).currentToken !== loadToken || !meshRef.current) {
+            try { mesh.dispose?.(); } catch {}
+            return;
+          }
+          
+          console.log('Splat mesh initialized successfully', { createMs: Math.round(t1 - t0), initMs: Math.round(t2 - t1) });
+          
+          mesh.position.set(...position);
+          if (quaternion) {
+            mesh.quaternion.set(quaternion[0], quaternion[1], quaternion[2], quaternion[3]);
+          }
+          if (scale !== 1) {
+            mesh.scale.setScalar(scale);
+          }
+          
+          scene.add(mesh);
+          setIsLoading(false);
+          
+        } catch (initError) {
+          console.error('Failed to initialize splat mesh:', initError);
+          setLoadError(`Failed to initialize splat mesh: ${initError instanceof Error ? initError.message : 'Unknown error'}`);
+          setIsLoading(false);
+          try { mesh.dispose?.(); } catch {}
+        }
+        
+      } catch (error) {
+        console.error('Error creating splat mesh:', error);
+        setLoadError(`Error loading splat: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        setIsLoading(false);
+      }
+    }, [scene, url, position, quaternion, scale]);
+
+  useEffect(() => {
+    loadSplatMesh();
+
+    // Listen for WebGL context restoration
+    const handleContextRestored = () => {
+      console.log('SplatWorld: WebGL context restored, reloading splat mesh');
+      setTimeout(() => {
+        loadSplatMesh();
+      }, 200); // Small delay to ensure SparkRenderer is ready
+    };
+
+    window.addEventListener('webgl-context-restored', handleContextRestored);
+
+    return () => {
+      // Invalidate any in-flight load calls by bumping the token
+      (loadSplatMesh as unknown as { currentToken?: string }).currentToken = crypto.randomUUID();
+      window.removeEventListener('webgl-context-restored', handleContextRestored);
+      if (meshRef.current) {
+        scene.remove(meshRef.current);
+        // Free GPU memory
+        try { 
+          meshRef.current.dispose?.(); 
+        } catch (error) {
+          console.warn('Error disposing splat mesh:', error);
+        }
+        meshRef.current = null;
+      }
+    };
+  }, [loadSplatMesh, scene]);
+
+  // Log loading state for debugging and notify parent
+  useEffect(() => {
+    if (loadError) {
+      console.error('SplatWorld load error:', loadError);
+    } else if (!isLoading) {
+      console.log('SplatWorld loaded successfully');
+    }
+    
+    // Notify parent component about loading state changes
+    onLoadingChange?.(isLoading, loadError || undefined);
+  }, [loadError, isLoading, onLoadingChange]);
+
+  return null;
+}

package/engine/src/config/audio.ts

@@ -0,0 +1,11 @@
+// Audio configuration
+export const AUDIO_CONFIG = {
+  MUSIC_VOLUME: 0.3, // 0.0 to 1.0
+  MUSIC_FILES: {
+    SUNLIT_GROVE: '/music/Sunlit_Grove_Ambient.mp3',
+  },
+  // Add more configuration as needed
+  FADE_DURATION: 1.0, // seconds for fade in/out
+} as const;
+
+export type MusicTrack = keyof typeof AUDIO_CONFIG.MUSIC_FILES;