minecraft-renderer 0.1.27 → 0.1.29

package/src/three/sceneOrigin.ts

@@ -0,0 +1,215 @@
+//@ts-nocheck
+import type { Object3D, Scene, Vector3 } from 'three'
+
+const IS_TRACKED_PROXY = Symbol('tracked-proxy')
+
+const MUTATING_METHODS = new Set([
+  'add', 'addScalar', 'addScaledVector', 'addVectors',
+  'sub', 'subScalar', 'subVectors',
+  'multiply', 'multiplyScalar', 'multiplyVectors',
+  'divide', 'divideScalar',
+  'applyEuler', 'applyAxisAngle', 'applyMatrix3', 'applyMatrix4', 'applyNormalMatrix', 'applyQuaternion',
+  'negate', 'floor', 'ceil', 'round', 'roundToZero',
+  'min', 'max', 'clamp', 'clampLength', 'clampScalar',
+  'project', 'unproject', 'reflect',
+  'lerp', 'lerpVectors',
+  'cross', 'crossVectors',
+  'setFromMatrixPosition', 'setFromMatrixColumn', 'setFromMatrix3Column',
+  'setFromEuler', 'setFromSpherical', 'setFromSphericalCoords', 'setFromCylindrical',
+  'fromArray', 'fromBufferAttribute',
+  'setComponent', 'randomDirection', 'random',
+])
+
+interface TrackOptions {
+  updateMatrix?: boolean
+}
+
+export class SceneOrigin {
+  private scene: Scene
+
+  // World coordinates of origin in float64 (JavaScript number)
+  private _x = 0
+  private _y = 0
+  private _z = 0
+
+  private readonly _tracked = new Set<Object3D>()
+  private readonly _worldCoords = new WeakMap<Object3D, { x: number; y: number; z: number }>()
+  private readonly _originalPositions = new WeakMap<Object3D, Vector3>()
+  private readonly _trackOptions = new WeakMap<Object3D, TrackOptions>()
+
+  constructor(scene: Scene) {
+    this.scene = scene
+  }
+
+  get x(): number { return this._x }
+  get y(): number { return this._y }
+  get z(): number { return this._z }
+
+  /** Update origin (called each frame with camera world position) */
+  update(worldX: number, worldY: number, worldZ: number): void {
+    this._x = worldX
+    this._y = worldY
+    this._z = worldZ
+
+    for (const obj of this._tracked) {
+      const worldData = this._worldCoords.get(obj)!
+      const realPos = this._originalPositions.get(obj)!
+      realPos.set(worldData.x - worldX, worldData.y - worldY, worldData.z - worldZ)
+      const opts = this._trackOptions.get(obj)
+      if (opts?.updateMatrix) obj.updateMatrix()
+    }
+  }
+
+  /** Track an Object3D so its position is automatically adjusted on origin changes */
+  track(obj: Object3D, options?: TrackOptions): void {
+    // If already tracked, use the stored original position to avoid nesting Proxies
+    const realPosition = this._originalPositions.get(obj) ?? obj.position
+    const worldData = { x: 0, y: 0, z: 0 }
+
+    this._originalPositions.set(obj, realPosition)
+    this._worldCoords.set(obj, worldData)
+    if (options) {
+      this._trackOptions.set(obj, options)
+    } else {
+      this._trackOptions.delete(obj)
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const origin = this
+    const opts = options
+
+    const proxy = new Proxy(realPosition, {
+      get(target, prop, receiver) {
+        if (prop === IS_TRACKED_PROXY) return worldData
+        if (prop === 'set') {
+          return (x: number, y: number, z: number) => {
+            worldData.x = x; worldData.y = y; worldData.z = z
+            target.set(x - origin._x, y - origin._y, z - origin._z)
+            if (opts?.updateMatrix) obj.updateMatrix()
+            return receiver
+          }
+        }
+        if (prop === 'copy') {
+          return (v: Vector3) => {
+            const srcWorld = (v as any)[IS_TRACKED_PROXY] as { x: number; y: number; z: number } | undefined
+            const wx = srcWorld ? srcWorld.x : v.x
+            const wy = srcWorld ? srcWorld.y : v.y
+            const wz = srcWorld ? srcWorld.z : v.z
+            worldData.x = wx; worldData.y = wy; worldData.z = wz
+            target.set(wx - origin._x, wy - origin._y, wz - origin._z)
+            if (opts?.updateMatrix) obj.updateMatrix()
+            return receiver
+          }
+        }
+        if (prop === 'setX') {
+          return (val: number) => {
+            worldData.x = val; target.x = val - origin._x
+            if (opts?.updateMatrix) obj.updateMatrix()
+            return receiver
+          }
+        }
+        if (prop === 'setY') {
+          return (val: number) => {
+            worldData.y = val; target.y = val - origin._y
+            if (opts?.updateMatrix) obj.updateMatrix()
+            return receiver
+          }
+        }
+        if (prop === 'setZ') {
+          return (val: number) => {
+            worldData.z = val; target.z = val - origin._z
+            if (opts?.updateMatrix) obj.updateMatrix()
+            return receiver
+          }
+        }
+        if (typeof prop === 'string' && MUTATING_METHODS.has(prop)) {
+          return () => { throw new Error(`Cannot call position.${prop}() on a tracked object. Use position.set(x, y, z) instead.`) }
+        }
+        const value = (target as any)[prop]
+        if (typeof value === 'function') return value.bind(target)
+        return value
+      },
+      set(target, prop, value) {
+        if (prop === 'x') {
+          worldData.x = value; target.x = value - origin._x
+          if (opts?.updateMatrix) obj.updateMatrix()
+          return true
+        }
+        if (prop === 'y') {
+          worldData.y = value; target.y = value - origin._y
+          if (opts?.updateMatrix) obj.updateMatrix()
+          return true
+        }
+        if (prop === 'z') {
+          worldData.z = value; target.z = value - origin._z
+          if (opts?.updateMatrix) obj.updateMatrix()
+          return true
+        }
+        ;(target as any)[prop] = value
+        return true
+      }
+    })
+
+    Object.defineProperty(obj, 'position', { value: proxy, configurable: true, enumerable: true })
+    this._tracked.add(obj)
+  }
+
+  /** Stop tracking an Object3D, restoring its original position Vector3 */
+  untrack(obj: Object3D): void {
+    const originalPos = this._originalPositions.get(obj)
+    if (!originalPos) return
+    Object.defineProperty(obj, 'position', { value: originalPos, configurable: true, enumerable: true })
+    this._tracked.delete(obj)
+    this._worldCoords.delete(obj)
+    this._originalPositions.delete(obj)
+    this._trackOptions.delete(obj)
+  }
+
+  /** Track an Object3D and add it to the scene */
+  addAndTrack(obj: Object3D, options?: TrackOptions): void {
+    this.track(obj, options)
+    this.scene.add(obj)
+  }
+
+  /** Untrack an Object3D and remove it from the scene */
+  removeAndUntrack(obj: Object3D): void {
+    this.untrack(obj)
+    this.scene.remove(obj)
+  }
+
+  /** Untrack an Object3D and all its descendants, then remove from the scene */
+  removeAndUntrackAll(obj: Object3D): void {
+    obj.traverse((child) => {
+      this.untrack(child)
+    })
+    this.scene.remove(obj)
+  }
+
+  /** Get stored world position for a tracked object */
+  getWorldPosition(obj: Object3D): { x: number; y: number; z: number } | undefined {
+    const w = this._worldCoords.get(obj)
+    return w ? { x: w.x, y: w.y, z: w.z } : undefined
+  }
+
+  /** Clear all tracked objects (call on scene reset) */
+  clear(): void {
+    for (const obj of this._tracked) {
+      this.untrack(obj)
+    }
+  }
+
+  /** Number of currently tracked objects (for debugging) */
+  get trackedCount(): number {
+    return this._tracked.size
+  }
+
+  /** Convert world coordinates → scene coordinates */
+  toSceneX(worldX: number): number { return worldX - this._x }
+  toSceneY(worldY: number): number { return worldY - this._y }
+  toSceneZ(worldZ: number): number { return worldZ - this._z }
+
+  /** Convert scene coordinates → world coordinates */
+  toWorldX(sceneX: number): number { return sceneX + this._x }
+  toWorldY(sceneY: number): number { return sceneY + this._y }
+  toWorldZ(sceneZ: number): number { return sceneZ + this._z }
+}

package/src/three/skyboxRenderer.ts

@@ -108,11 +108,11 @@ export class SkyboxRenderer {
 
     if (this.mesh) {
       // Update skybox position
-      this.mesh.position.copy(cameraPosition)
+      this.mesh.position.set(0, 0, 0)
     } else if (this.skyMesh) {
       // Update gradient sky position
-      this.skyMesh.position.copy(cameraPosition)
-      this.voidMesh?.position.copy(cameraPosition)
+      this.skyMesh.position.set(0, 0, 0)
+      this.voidMesh?.position.set(0, 0, 0)
       this.updateSkyColors() // Update colors based on time of day
     }
   }

package/src/three/threeJsMedia.ts

@@ -203,7 +203,7 @@ export class ThreeJsMedia {
       positionalAudio = new THREE.PositionalAudio(soundSystem.audioListener)
       positionalAudio.setRefDistance(6)
       positionalAudio.setVolume(volume)
-      scene.add(positionalAudio)
+      this.worldRenderer.sceneOrigin.addAndTrack(positionalAudio)
       positionalAudio.position.set(props.position.x, props.position.y, props.position.z)
 
       // Connect video to positional audio
@@ -461,9 +461,9 @@ export class ThreeJsMedia {
       if (mediaData.positionalAudio) {
         // mediaData.positionalAudio.stop()
         // mediaData.positionalAudio.disconnect()
-        scene.remove(mediaData.positionalAudio)
+        this.worldRenderer.sceneOrigin.removeAndUntrack(mediaData.positionalAudio)
       }
-      scene.remove(mediaData.mesh)
+      this.worldRenderer.sceneOrigin.removeAndUntrack(mediaData.mesh)
       mediaData.texture.dispose()
 
       // Get the inner mesh from the group
@@ -549,7 +549,8 @@ export class ThreeJsMedia {
     mesh.geometry.translate(0.5, 0.5, 0)
     mesh.geometry.attributes.position.needsUpdate = true
 
-    // Now place the mesh at the start position
+    // Now place the mesh at the start position (convert world → scene coords)
+    this.worldRenderer.sceneOrigin.track(mesh)
     mesh.position.set(startPosition.x, startPosition.y, startPosition.z)
 
     // Create a group to hold our mesh and markers
@@ -561,7 +562,7 @@ export class ThreeJsMedia {
       new THREE.BoxGeometry(0.1, 0.1, 0.1),
       new THREE.MeshBasicMaterial({ color: 0xff_00_00 })
     )
-    startMarker.position.copy(new THREE.Vector3(startPosition.x, startPosition.y, startPosition.z))
+    startMarker.position.set(startPosition.x, startPosition.y, startPosition.z)
     debugGroup.add(startMarker)
 
     // Add a marker at the end position (width units away in the rotated direction)
@@ -591,9 +592,14 @@ export class ThreeJsMedia {
     debugGroup.add(endCornerMarker)
 
     // Also add a visual helper to show the rotation direction
+    const sceneStartPos = new THREE.Vector3(
+      this.worldRenderer.sceneOrigin.toSceneX(startPosition.x),
+      this.worldRenderer.sceneOrigin.toSceneY(startPosition.y),
+      this.worldRenderer.sceneOrigin.toSceneZ(startPosition.z)
+    )
     const directionHelper = new THREE.ArrowHelper(
       new THREE.Vector3(Math.cos(rotation), 0, Math.sin(rotation)),
-      new THREE.Vector3(startPosition.x, startPosition.y, startPosition.z),
+      sceneStartPos,
       1,
       0xff_00_00
     )

package/src/three/threeJsParticles.ts

@@ -1,8 +1,10 @@
 //@ts-nocheck
 import * as THREE from 'three'
+import type { SceneOrigin } from './sceneOrigin'
 
 interface ParticleMesh extends THREE.Mesh {
   velocity: THREE.Vector3;
+  worldPos: THREE.Vector3;
 }
 
 interface ParticleConfig {
@@ -24,11 +26,13 @@ export class Fountain {
   private readonly particles: ParticleMesh[] = []
   private readonly config: { particleConfig: ParticleConfig }
   private readonly position: THREE.Vector3
+  private readonly sceneOrigin: SceneOrigin | undefined
   container: THREE.Object3D | undefined
 
-  constructor (public sectionId: string, options: FountainOptions = {}) {
+  constructor (public sectionId: string, options: FountainOptions = {}, sceneOrigin?: SceneOrigin) {
     this.position = options.position ? new THREE.Vector3(options.position.x, options.position.y, options.position.z) : new THREE.Vector3(0, 0, 0)
     this.config = this.createConfig(options.particleConfig)
+    this.sceneOrigin = sceneOrigin
   }
 
   private createConfig (
@@ -48,6 +52,18 @@ export class Fountain {
     return { particleConfig }
   }
 
+  private toSceneX (worldX: number): number {
+    return this.sceneOrigin ? this.sceneOrigin.toSceneX(worldX) : worldX
+  }
+
+  private toSceneY (worldY: number): number {
+    return this.sceneOrigin ? this.sceneOrigin.toSceneY(worldY) : worldY
+  }
+
+  private toSceneZ (worldZ: number): number {
+    return this.sceneOrigin ? this.sceneOrigin.toSceneZ(worldZ) : worldZ
+  }
+
 
   createParticles (container: THREE.Object3D): void {
     this.container = container
@@ -65,11 +81,12 @@ export class Fountain {
       const mesh = new THREE.Mesh(geometry, material)
       const particle = mesh as unknown as ParticleMesh
 
-      particle.position.set(
-        this.position.x + (Math.random() - 0.5) * this.config.particleConfig.xVelocityRange * 2,
-        this.position.y + this.config.particleConfig.fountainHeight,
-        this.position.z + (Math.random() - 0.5) * this.config.particleConfig.zVelocityRange * 2
-      )
+      const worldX = this.position.x + (Math.random() - 0.5) * this.config.particleConfig.xVelocityRange * 2
+      const worldY = this.position.y + this.config.particleConfig.fountainHeight
+      const worldZ = this.position.z + (Math.random() - 0.5) * this.config.particleConfig.zVelocityRange * 2
+
+      particle.worldPos = new THREE.Vector3(worldX, worldY, worldZ)
+      particle.position.set(this.toSceneX(worldX), this.toSceneY(worldY), this.toSceneZ(worldZ))
 
       particle.velocity = new THREE.Vector3(
         (Math.random() - 0.5) * this.config.particleConfig.xVelocityRange,
@@ -89,20 +106,26 @@ export class Fountain {
   render (): void {
     for (const particle of this.particles) {
       particle.velocity.y -= 0.01 + Math.random() * 0.1
-      particle.position.add(particle.velocity)
+      particle.worldPos.add(particle.velocity)
 
-      if (particle.position.y < this.position.y + this.config.particleConfig.resetHeight) {
-        particle.position.set(
-          this.position.x + (Math.random() - 0.5) * this.config.particleConfig.xVelocityRange * 2,
-          this.position.y + this.config.particleConfig.fountainHeight,
-          this.position.z + (Math.random() - 0.5) * this.config.particleConfig.zVelocityRange * 2
-        )
+      if (particle.worldPos.y < this.position.y + this.config.particleConfig.resetHeight) {
+        const worldX = this.position.x + (Math.random() - 0.5) * this.config.particleConfig.xVelocityRange * 2
+        const worldY = this.position.y + this.config.particleConfig.fountainHeight
+        const worldZ = this.position.z + (Math.random() - 0.5) * this.config.particleConfig.zVelocityRange * 2
+
+        particle.worldPos.set(worldX, worldY, worldZ)
         particle.velocity.set(
           (Math.random() - 0.5) * this.config.particleConfig.xVelocityRange,
           -Math.random() * this.config.particleConfig.yVelocityRange.max,
           (Math.random() - 0.5) * this.config.particleConfig.zVelocityRange
         )
       }
+
+      particle.position.set(
+        this.toSceneX(particle.worldPos.x),
+        this.toSceneY(particle.worldPos.y),
+        this.toSceneZ(particle.worldPos.z)
+      )
     }
   }
 
@@ -126,7 +149,12 @@ export class Fountain {
     for (let i = 0; i < count; i++) {
       const mesh = new THREE.Mesh(geometry, material)
       const particle = mesh as unknown as ParticleMesh
-      particle.position.copy(this.position)
+      particle.worldPos = this.position.clone()
+      particle.position.set(
+        this.toSceneX(this.position.x),
+        this.toSceneY(this.position.y),
+        this.toSceneZ(this.position.z)
+      )
       particle.velocity = new THREE.Vector3(
         Math.random() * this.config.particleConfig.xVelocityRange -
         this.config.particleConfig.xVelocityRange / 2,

package/src/three/threeJsSound.ts

@@ -45,11 +45,11 @@ export class ThreeJsSound implements SoundSystem {
       sound.setRefDistance(20)
       sound.setVolume(volume * this.baseVolume)
       sound.setPlaybackRate(pitch) // set the pitch
-      this.worldRenderer.scene.add(sound)
       // set sound position
+      this.worldRenderer.sceneOrigin.addAndTrack(sound)
       sound.position.set(position.x, position.y, position.z)
       sound.onEnded = () => {
-        this.worldRenderer.scene.remove(sound)
+        this.worldRenderer.sceneOrigin.removeAndUntrack(sound)
         if (sound.source) {
           sound.disconnect()
         }
@@ -68,7 +68,7 @@ export class ThreeJsSound implements SoundSystem {
       if (sound.source) {
         sound.disconnect()
       }
-      this.worldRenderer.scene.remove(sound)
+      this.worldRenderer.sceneOrigin.removeAndUntrack(sound)
     }
     this.activeSounds.clear()
     this.soundVolumes.clear()

package/src/three/waypointSprite.ts

@@ -21,6 +21,10 @@ export const WAYPOINT_CONFIG = {
     pixelSize: 50,
     paddingPx: 50,
   },
+  // Default visual scale factor (can be overridden globally or per-waypoint)
+  DEFAULT_VISUAL_SCALE: 1,
+  // Default opacity (can be overridden globally or per-waypoint)
+  DEFAULT_OPACITY: 1,
 }
 
 export type WaypointSprite = {
@@ -53,14 +57,31 @@ export function createWaypointSprite (options: {
   // Y offset in world units used by updateScaleWorld only (screen-pixel API ignores this)
   labelYOffset?: number,
   metadata?: any,
+  visualScale?: number,
+  opacity?: number,
 }): WaypointSprite {
   const color = options.color ?? 0xFF_00_00
   const depthTest = options.depthTest ?? false
   const labelYOffset = options.labelYOffset ?? 1.5
 
+  // Get visual scale from options, metadata, server metadata, or default
+  // Priority: options.visualScale > metadata.visualScale > window.serverMetadata?.waypointVisualScale > DEFAULT
+  const visualScale = options.visualScale
+    ?? options.metadata?.visualScale
+    ?? (typeof window === 'undefined' ? undefined : (window as any).serverMetadata?.waypointVisualScale)
+    ?? WAYPOINT_CONFIG.DEFAULT_VISUAL_SCALE
+
+  // Get opacity from options, metadata, server metadata, or default
+  // Priority: options.opacity > metadata.opacity > window.serverMetadata?.waypointOpacity > DEFAULT
+  const opacity = options.opacity
+    ?? options.metadata?.opacity
+    ?? (typeof window === 'undefined' ? undefined : (window as any).serverMetadata?.waypointOpacity)
+    ?? WAYPOINT_CONFIG.DEFAULT_OPACITY
+
   // Build combined sprite
-  const sprite = createCombinedSprite(color, options.label ?? '', '0m', depthTest)
+  const sprite = createCombinedSprite(color, options.label ?? '', '0m', depthTest, visualScale)
   sprite.renderOrder = 10
+  sprite.material.opacity = opacity
   let currentLabel = options.label ?? ''
 
   // Performance optimization: cache distance text to avoid unnecessary updates
@@ -81,7 +102,7 @@ export function createWaypointSprite (options: {
   group.position.set(x, y, z)
 
   function setColor (newColor: number) {
-    const canvas = drawCombinedCanvas(newColor, currentLabel, '0m')
+    const canvas = drawCombinedCanvas(newColor, currentLabel, '0m', visualScale)
     const texture = new THREE.CanvasTexture(canvas)
     const mat = sprite.material
     mat.map?.dispose()
@@ -91,7 +112,7 @@ export function createWaypointSprite (options: {
 
   function setLabel (newLabel?: string) {
     currentLabel = newLabel ?? ''
-    const canvas = drawCombinedCanvas(color, currentLabel, '0m')
+    const canvas = drawCombinedCanvas(color, currentLabel, '0m', visualScale)
     const texture = new THREE.CanvasTexture(canvas)
     const mat = sprite.material
     mat.map?.dispose()
@@ -106,7 +127,7 @@ export function createWaypointSprite (options: {
     }
     lastDistanceText = distanceText
 
-    const canvas = drawCombinedCanvas(color, label, distanceText)
+    const canvas = drawCombinedCanvas(color, label, distanceText, visualScale)
     const texture = new THREE.CanvasTexture(canvas)
     const mat = sprite.material
     mat.map?.dispose()
@@ -131,8 +152,8 @@ export function createWaypointSprite (options: {
   ) {
     const vFovRad = cameraFov * Math.PI / 180
     const worldUnitsPerScreenHeightAtDist = Math.tan(vFovRad / 2) * 2 * distance
-    // Use configured target screen size
-    const scale = worldUnitsPerScreenHeightAtDist * (WAYPOINT_CONFIG.TARGET_SCREEN_PX / viewportHeightPx)
+    // Use configured target screen size with visual scale multiplier
+    const scale = worldUnitsPerScreenHeightAtDist * (WAYPOINT_CONFIG.TARGET_SCREEN_PX * visualScale / viewportHeightPx)
     sprite.scale.set(scale, scale, 1)
   }
 
@@ -159,7 +180,7 @@ export function createWaypointSprite (options: {
     ctx.fill()
 
     const texture = new THREE.CanvasTexture(canvas)
-    const material = new THREE.SpriteMaterial({ map: texture, transparent: true, depthTest: false, depthWrite: false })
+    const material = new THREE.SpriteMaterial({ map: texture, transparent: true, depthTest: false, depthWrite: false, opacity })
     arrowSprite = new THREE.Sprite(material)
     arrowSprite.renderOrder = 12
     arrowSprite.visible = false
@@ -278,15 +299,16 @@ export function createWaypointSprite (options: {
     const angle = Math.atan2(ry, rx)
     arrowSprite.material.rotation = angle - Math.PI / 2
 
-    // Constant pixel size for arrow (use fixed placement distance)
+    // Constant pixel size for arrow (use fixed placement distance) with visual scale
     const worldUnitsPerScreenHeightAtDist = Math.tan(vFovRad / 2) * 2 * placeDist
-    const sPx = worldUnitsPerScreenHeightAtDist * (WAYPOINT_CONFIG.ARROW.pixelSize / viewportHeightPx)
+    const sPx = worldUnitsPerScreenHeightAtDist * (WAYPOINT_CONFIG.ARROW.pixelSize * visualScale / viewportHeightPx)
     arrowSprite.scale.set(sPx, sPx, 1)
     return false
   }
 
-  function computeDistance (cameraPosition: THREE.Vector3): number {
-    return cameraPosition.distanceTo(group.position)
+  function computeDistance (_cameraPosition: THREE.Vector3): number {
+    // group.position is in scene space; camera is at scene origin (0,0,0)
+    return group.position.length()
   }
 
   function updateForCamera (
@@ -343,7 +365,7 @@ export function createWaypointSprite (options: {
 }
 
 // Internal helpers
-function drawCombinedCanvas (color: number, id: string, distance: string): OffscreenCanvas {
+function drawCombinedCanvas (color: number, id: string, distance: string, visualScale = 1): OffscreenCanvas {
   const scale = WAYPOINT_CONFIG.CANVAS_SCALE * (globalThis.devicePixelRatio || 1)
   const size = WAYPOINT_CONFIG.CANVAS_SIZE * scale
   const canvas = createCanvas(size, size)
@@ -352,11 +374,11 @@ function drawCombinedCanvas (color: number, id: string, distance: string): Offsc
   // Clear canvas
   ctx.clearRect(0, 0, size, size)
 
-  // Draw dot
+  // Draw dot with visual scale applied
   const centerX = size / 2
   const dotY = Math.round(size * WAYPOINT_CONFIG.LAYOUT.DOT_Y)
-  const radius = Math.round(size * 0.05) // Dot takes up ~12% of canvas height
-  const borderWidth = Math.max(2, Math.round(4 * scale))
+  const radius = Math.round(size * 0.05 * visualScale) // Dot takes up ~5% of canvas height, scaled
+  const borderWidth = Math.max(2, Math.round(4 * scale * visualScale))
 
   // Outer border (black)
   ctx.beginPath()
@@ -374,11 +396,11 @@ function drawCombinedCanvas (color: number, id: string, distance: string): Offsc
   ctx.textAlign = 'center'
   ctx.textBaseline = 'middle'
 
-  // Title
-  const nameFontPx = Math.round(size * 0.08) // ~8% of canvas height
-  const distanceFontPx = Math.round(size * 0.06) // ~6% of canvas height
+  // Title with visual scale applied
+  const nameFontPx = Math.round(size * 0.08 * visualScale) // ~8% of canvas height, scaled
+  const distanceFontPx = Math.round(size * 0.06 * visualScale) // ~6% of canvas height, scaled
   ctx.font = `bold ${nameFontPx}px mojangles`
-  ctx.lineWidth = Math.max(2, Math.round(3 * scale))
+  ctx.lineWidth = Math.max(2, Math.round(3 * scale * visualScale))
   const nameY = Math.round(size * WAYPOINT_CONFIG.LAYOUT.NAME_Y)
 
   ctx.strokeStyle = 'black'
@@ -386,9 +408,9 @@ function drawCombinedCanvas (color: number, id: string, distance: string): Offsc
   ctx.fillStyle = 'white'
   ctx.fillText(id, centerX, nameY)
 
-  // Distance
+  // Distance with visual scale applied
   ctx.font = `bold ${distanceFontPx}px mojangles`
-  ctx.lineWidth = Math.max(2, Math.round(2 * scale))
+  ctx.lineWidth = Math.max(2, Math.round(2 * scale * visualScale))
   const distanceY = Math.round(size * WAYPOINT_CONFIG.LAYOUT.DISTANCE_Y)
 
   ctx.strokeStyle = 'black'
@@ -399,8 +421,8 @@ function drawCombinedCanvas (color: number, id: string, distance: string): Offsc
   return canvas
 }
 
-function createCombinedSprite (color: number, id: string, distance: string, depthTest: boolean): THREE.Sprite {
-  const canvas = drawCombinedCanvas(color, id, distance)
+function createCombinedSprite (color: number, id: string, distance: string, depthTest: boolean, visualScale = 1): THREE.Sprite {
+  const canvas = drawCombinedCanvas(color, id, distance, visualScale)
   const texture = new THREE.CanvasTexture(canvas)
   texture.anisotropy = 1
   texture.magFilter = THREE.LinearFilter

package/src/three/waypoints.ts

@@ -9,6 +9,7 @@ interface Waypoint {
   y: number
   z: number
   minDistance: number
+  maxDistance: number
   color: number
   label?: string
   sprite: WaypointSprite
@@ -18,6 +19,7 @@ interface WaypointOptions {
   color?: number
   label?: string
   minDistance?: number
+  maxDistance?: number
   metadata?: any
 }
 
@@ -40,7 +42,7 @@ export class WaypointsRenderer {
 
   private updateWaypoints() {
     const currentTime = performance.now()
-    const playerPos = this.worldRenderer.cameraObject.position
+    const playerPos = this.worldRenderer.getCameraPosition()
 
     // Performance optimization: throttle updates and check for significant camera movement
     const cameraMovedSignificantly = this.lastCameraPosition.distanceTo(playerPos) > 0.5
@@ -58,13 +60,18 @@ export class WaypointsRenderer {
     for (const waypoint of this.waypoints.values()) {
       const waypointPos = new THREE.Vector3(waypoint.x, waypoint.y, waypoint.z)
       const distance = playerPos.distanceTo(waypointPos)
-      const visible = !waypoint.minDistance || distance >= waypoint.minDistance
+      const visible = (!waypoint.minDistance || distance >= waypoint.minDistance) &&
+        (waypoint.maxDistance === Infinity || distance <= waypoint.maxDistance)
 
       waypoint.sprite.setVisible(visible)
 
       if (visible) {
         // Update position
-        waypoint.sprite.setPosition(waypoint.x, waypoint.y, waypoint.z)
+        waypoint.sprite.setPosition(
+          this.worldRenderer.sceneOrigin.toSceneX(waypoint.x),
+          this.worldRenderer.sceneOrigin.toSceneY(waypoint.y),
+          this.worldRenderer.sceneOrigin.toSceneZ(waypoint.z)
+        )
         // Ensure camera-based update each frame
         waypoint.sprite.updateForCamera(this.worldRenderer.getCameraPosition(), this.worldRenderer.camera, sizeVec.width, sizeVec.height)
       }
@@ -96,6 +103,7 @@ export class WaypointsRenderer {
     const color = options.color ?? 0xFF_00_00
     const { label, metadata } = options
     const minDistance = options.minDistance ?? 0
+    const maxDistance = options.maxDistance ?? Infinity
 
     const sprite = createWaypointSprite({
       position: new THREE.Vector3(x, y, z),
@@ -109,7 +117,7 @@ export class WaypointsRenderer {
     this.waypointScene.add(sprite.group)
 
     this.waypoints.set(id, {
-      id, x: x + 0.5, y: y + 0.5, z: z + 0.5, minDistance,
+      id, x: x + 0.5, y: y + 0.5, z: z + 0.5, minDistance, maxDistance,
       color, label,
       sprite,
     })