@directivegames/genesys.js 3.1.24

package/src/components/gameplay/DoorComponent.ts

@@ -0,0 +1,930 @@
+/**
+ * DoorComponent manages door state and animation logic.
+ *
+ * Detailed explanation:
+ * - Handles door state transitions (Closed, Opening, Open, Closing, Locked)
+ * - Implements transform-based animation for different door types using Tween.js
+ * - Provides proximity detection and interaction handling
+ * - Uses delegates for event notifications
+ * - Calculates appropriate pivot points from door geometry
+ * - Supports automatic proximity-based opening and manual key-based interaction
+ *
+ * Interaction Modes:
+ * - Proximity: Automatically opens when player enters range, closes when they exit
+ * - KeyPress: Requires player to be in proximity and press the interaction key
+ * - Remote: Reserved for future remote control implementation
+ *
+ * Proximity Detection:
+ * - Collision-based: Uses existing CollisionShapeComponent if found (more efficient)
+ * - Distance-based: Creates proximity trigger for distance calculation (fallback)
+ * - Automatically selects best method during initialization
+ *
+ * Animation System:
+ * - Transform-based animation independent of model pivot points
+ * - Smooth easing with configurable duration using Tween.js
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Attach to any actor that should behave like a door
+ * - Configure door type and animation parameters via options
+ * - Listen to door events using delegates (onDoorOpened, onDoorClosed, etc.)
+ * - Use open(), close(), toggle() methods for direct control
+ */
+
+import * as TWEEN from '@tweenjs/tween.js';
+import * as THREE from 'three';
+
+import { Actor } from '../../actors/Actor.js';
+import { CollisionMeshType, PhysicsMotionType } from '../../physics/PhysicsTypes.js';
+import { EngineClass } from '../../systems/ClassRegistry.js';
+import { DefaultCollisionProfile } from '../../systems/collision/CollisionTypes.js';
+import { Delegate } from '../../utils/Delegate.js';
+import { AsyncTaskWorker, IAsyncLoadableTag } from '../../utils/IAsyncLoadable.js';
+import { CollisionShapeComponent, CollisionShapeType } from '../CollisionShapeComponent.js';
+import { SceneComponent } from '../SceneComponent.js';
+import { GLTFMeshComponent } from '../visual/GLTFMeshComponent.js';
+
+import type { IInputHandler, InputManager } from '../../systems/InputManager.js';
+import type { EditorClassMeta } from '../../utils/EditorClassMeta.js';
+import type { IAsyncLoadable } from '../../utils/IAsyncLoadable.js';
+import type { SceneComponentOptions } from '../SceneComponent.js';
+
+export enum DoorState {
+  Closed = 'closed',
+  Opening = 'opening',
+  Open = 'open',
+  Closing = 'closing',
+  Locked = 'locked'
+}
+
+/**
+ * Door animation types
+ */
+export enum DoorType {
+  /** Rotates around Y-axis (fully implemented) */
+  Hinged = 'hinged',
+  /** Slides along X-axis (fully implemented) */
+  Sliding = 'sliding',
+  /** Rotates and lifts upward (basic implementation) */
+  Garage = 'garage',
+  /** Multiple coordinated door panels (placeholder - uses hinged animation) */
+  Double = 'double',
+  /** Custom animation handled by external code via delegates */
+  Custom = 'custom'
+}
+
+/**
+ * Door interaction methods
+ */
+export enum DoorInteractionType {
+  /** Automatically opens when player approaches, closes when they leave */
+  Proximity = 'proximity',
+  /** Requires player to be in proximity and press interaction key */
+  KeyPress = 'keypress',
+  /** Reserved for future remote control implementation */
+  Remote = 'remote'
+}
+
+export interface DoorComponentOptions extends SceneComponentOptions {
+  doorType: DoorType;
+  interactionType: DoorInteractionType;
+  animationDuration: number;
+  maxOpenAngle: number;
+  slideDistance: number;
+  /** Direction vector for sliding doors in local space (default: right direction) */
+  slideDirection?: THREE.Vector3;
+  startLocked: boolean;
+  proximityRange: number;
+  interactionKey: string;
+}
+
+export type DoorEventDelegate = Delegate<[DoorComponent], void>;
+
+@EngineClass('DoorComponent')
+export class DoorComponent extends SceneComponent<DoorComponentOptions> implements IInputHandler, IAsyncLoadable {
+  static override readonly EDITOR_CLASS_META: EditorClassMeta = {
+    doorType: { select: Object.values(DoorType) },
+    interactionType: { select: Object.values(DoorInteractionType) }
+  } as const;
+
+  readonly [IAsyncLoadableTag] = true;
+
+  private inputManager: InputManager | null = null;
+  // State management
+  private currentState: DoorState = DoorState.Closed;
+  private animationProgress: number = 0;
+
+  // Tween.js animation
+  private tweenGroup: TWEEN.Group = new TWEEN.Group();
+  private currentTween: TWEEN.Tween<{ progress: number }> | null = null;
+
+  // Transform tracking
+  private initialTransform: { position: THREE.Vector3; rotation: THREE.Euler; scale: THREE.Vector3 } | null = null;
+  private doorPivotPoint: THREE.Vector3 | null = null;
+  private doorMesh: THREE.Mesh | null = null;
+  private gltfMeshComponent: GLTFMeshComponent | null = null;
+
+  // Interaction components
+  private proximityTrigger: CollisionShapeComponent | null = null;
+  private existingCollisionShape: CollisionShapeComponent | null = null;
+  private playersInRange: Set<Actor> = new Set();
+  private isRegisteredForInput: boolean = false;
+  private useCollisionBasedProximity: boolean = false;
+
+  // Proximity check optimization
+  private proximityCheckTimer: number = 0;
+  private readonly proximityCheckInterval: number = 0.25; // 4 times per second
+
+  // Event delegates
+  public readonly onDoorStartOpening: DoorEventDelegate = new Delegate<[DoorComponent], void>();
+  public readonly onDoorStartClosing: DoorEventDelegate = new Delegate<[DoorComponent], void>();
+  public readonly onDoorOpened: DoorEventDelegate = new Delegate<[DoorComponent], void>();
+  public readonly onDoorClosed: DoorEventDelegate = new Delegate<[DoorComponent], void>();
+  public readonly onDoorLocked: DoorEventDelegate = new Delegate<[DoorComponent], void>();
+  public readonly onDoorUnlocked: DoorEventDelegate = new Delegate<[DoorComponent], void>();
+  public readonly onInteractionAttempt: DoorEventDelegate = new Delegate<[DoorComponent], void>();
+
+
+  private _asyncTaskWorker = new AsyncTaskWorker();
+
+  static override get DEFAULT_OPTIONS(): DoorComponentOptions {
+    return {
+      ...SceneComponent.DEFAULT_OPTIONS,
+      doorType: DoorType.Hinged,
+      interactionType: DoorInteractionType.Proximity,
+      animationDuration: 1.0,
+      maxOpenAngle: 90,
+      slideDistance: 2.0,
+      slideDirection: new THREE.Vector3(1, 0, 0), // Default: slide to the right in local space
+      startLocked: false,
+      proximityRange: 2.0,
+      interactionKey: 'e',
+    };
+  }
+
+  constructor(options: DoorComponentOptions) {
+    super(options);
+
+    if (this.options.startLocked) {
+      this.currentState = DoorState.Locked;
+    }
+  }
+
+  public override beginPlay(): void {
+    super.beginPlay();
+
+    this._asyncTaskWorker.runTask(async () => {
+      // Initialize door geometry and pivot point
+      await this.initializeDoorGeometry();
+
+      // Set up proximity detection if needed
+      if (this.options.interactionType === DoorInteractionType.Proximity ||
+        this.options.interactionType === DoorInteractionType.KeyPress) {
+        this.setupProximityDetection();
+      }
+    });
+  }
+
+  public override endPlay(): void {
+    super.endPlay();
+
+    // Clean up input registration
+    if (this.isRegisteredForInput) {
+      const world = this.getActor()?.getWorld();
+      if (world) {
+        world.inputManager.removeInputHandler(this);
+        this.isRegisteredForInput = false;
+      }
+    }
+  }
+
+  // IAsyncLoadable implementation
+  public async waitForLoad(): Promise<void> {
+    await this._asyncTaskWorker.waitUntilComplete();
+  }
+
+  public isLoading(): boolean {
+    return this._asyncTaskWorker.isRunning();
+  }
+  // end IAsyncLoadable implementation
+
+  public override tickPrePhysics(deltaTime: number): void {
+    super.tickPrePhysics(deltaTime);
+
+    // Update tween animations
+    const gameTime = this.getWorld()?.getGameTime() ?? 0;
+    this.tweenGroup.update(gameTime * 1000); // Convert to milliseconds
+
+    // Proximity check optimization - only check 4 times per second
+    this.proximityCheckTimer += deltaTime;
+    if (this.proximityCheckTimer >= this.proximityCheckInterval) {
+      this.proximityCheckTimer = 0;
+      this.updateProximityCheck();
+    }
+
+    // Handle input registration for proximity-based interaction
+    this.updateInputRegistration();
+  }
+
+  /**
+   * Opens the door if it's not locked
+   */
+  public open(): void {
+    if (this.currentState === DoorState.Locked) {
+      this.onDoorLocked.invoke(this);
+      return;
+    }
+
+    if (this.currentState === DoorState.Closed) {
+      this.startOpening();
+    }
+  }
+
+  /**
+   * Closes the door
+   */
+  public close(): void {
+    if (this.currentState === DoorState.Open) {
+      this.startClosing();
+    }
+  }
+
+  /**
+   * Starts opening animation, can interrupt closing animation smoothly
+   */
+  private startOpening(): void {
+    if (this.currentState === DoorState.Locked) {
+      this.onDoorLocked.invoke(this);
+      return;
+    }
+
+    this.currentState = DoorState.Opening;
+
+    // Fire the start opening event
+    this.onDoorStartOpening.invoke(this);
+
+    // Stop any existing tween
+    if (this.currentTween) {
+      this.currentTween.stop();
+      this.currentTween = null;
+    }
+
+    // Create tween from current progress to fully open (1.0)
+    const startProgress = this.animationProgress;
+    const targetProgress = 1.0;
+    const progressDelta = targetProgress - startProgress;
+    const duration = this.options.animationDuration * progressDelta * 1000; // Convert to milliseconds
+
+    const tweenData = { progress: startProgress };
+
+    this.currentTween = new TWEEN.Tween(tweenData, this.tweenGroup)
+      .to({ progress: targetProgress }, duration)
+      .easing(TWEEN.Easing.Cubic.InOut)
+      .onUpdate(() => {
+        this.animationProgress = tweenData.progress;
+        this.applyDoorTransform(this.animationProgress);
+      })
+      .onComplete(() => {
+        this.currentState = DoorState.Open;
+        this.currentTween = null;
+        this.onDoorOpened.invoke(this);
+      })
+      .start();
+  }
+
+  /**
+   * Starts closing animation, can interrupt opening animation smoothly
+   */
+  private startClosing(): void {
+    this.currentState = DoorState.Closing;
+
+    // Fire the start closing event
+    this.onDoorStartClosing.invoke(this);
+
+    // Stop any existing tween
+    if (this.currentTween) {
+      this.currentTween.stop();
+      this.currentTween = null;
+    }
+
+    // Create tween from current progress to fully closed (0.0)
+    const startProgress = this.animationProgress;
+    const targetProgress = 0.0;
+    const progressDelta = Math.abs(targetProgress - startProgress);
+    const duration = this.options.animationDuration * progressDelta * 1000; // Convert to milliseconds
+
+    const tweenData = { progress: startProgress };
+
+    this.currentTween = new TWEEN.Tween(tweenData, this.tweenGroup)
+      .to({ progress: targetProgress }, duration)
+      .easing(TWEEN.Easing.Cubic.InOut)
+      .onUpdate(() => {
+        this.animationProgress = tweenData.progress;
+        this.applyDoorTransform(this.animationProgress);
+      })
+      .onComplete(() => {
+        this.currentState = DoorState.Closed;
+        this.currentTween = null;
+        this.onDoorClosed.invoke(this);
+      })
+      .start();
+  }
+
+  /**
+   * Toggles the door state
+   */
+  public toggle(): void {
+    if (this.isOpen()) {
+      this.close();
+    } else {
+      this.open();
+    }
+  }
+
+  /**
+   * Locks the door
+   */
+  public lock(): void {
+    this.currentState = DoorState.Locked;
+    this.onDoorLocked.invoke(this);
+  }
+
+  /**
+   * Unlocks the door
+   */
+  public unlock(): void {
+    if (this.currentState === DoorState.Locked) {
+      this.currentState = DoorState.Closed;
+      this.onDoorUnlocked.invoke(this);
+    }
+  }
+
+  /**
+   * Checks if the door is currently open
+   */
+  public isOpen(): boolean {
+    return this.currentState === DoorState.Open;
+  }
+
+  /**
+   * Checks if the door is currently locked
+   */
+  public isLocked(): boolean {
+    return this.currentState === DoorState.Locked;
+  }
+
+  /**
+   * Checks if the door is currently animating
+   */
+  public isAnimating(): boolean {
+    return this.currentState === DoorState.Opening || this.currentState === DoorState.Closing;
+  }
+
+  /**
+   * Gets the current door state
+   */
+  public getState(): DoorState {
+    return this.currentState;
+  }
+
+  // IInputHandler implementation
+  public handleKeyDown(e: KeyboardEvent): boolean {
+    if (e.key.toLowerCase() === this.options.interactionKey.toLowerCase()) {
+      if (this.playersInRange.size > 0) {
+        this.onInteractionAttempt.invoke(this);
+        this.toggle();
+        return true;
+      }
+    }
+    return false;
+  }
+
+  public handleKeyUp(e: KeyboardEvent): boolean { return false; }
+  public handleMouseDown(button: any, e: MouseEvent): boolean { return false; }
+  public handleMouseUp(button: any, e: MouseEvent): boolean { return false; }
+  public handleMouseMove(e: MouseEvent): boolean { return false; }
+  public handleMouseClick(button: any, e: MouseEvent): boolean { return false; }
+
+  public setInputManager(manager: InputManager | null): void {
+    this.inputManager = manager;
+  }
+
+  /**
+   * Initializes door geometry and calculates pivot point
+   */
+  private async initializeDoorGeometry(): Promise<void> {
+    const actor = this.getActor();
+    if (!actor) {
+      return;
+    }
+
+    // Get the GLTF mesh component from the root scene component hierarchy
+    const gltfComponent = actor.rootComponent.getComponent(GLTFMeshComponent);
+    if (!gltfComponent) {
+      console.warn('[DoorComponent] No GLTF mesh component found');
+      return;
+    }
+
+    // Store reference to the GLTF mesh component for animation
+    this.gltfMeshComponent = gltfComponent;
+
+    // Also search for existing CollisionShapeComponent for proximity detection
+    const existingCollisionShape = actor.rootComponent.getComponent(CollisionShapeComponent);
+    if (existingCollisionShape) {
+      this.existingCollisionShape = existingCollisionShape;
+      this.useCollisionBasedProximity = true;
+    } else {
+      this.useCollisionBasedProximity = false;
+    }
+
+    // Wait for model to load
+    await gltfComponent.waitForLoad();
+
+    const model = gltfComponent.getModel();
+    if (!model) {
+      console.log('[DoorComponent] Model failed to load');
+      return;
+    }
+
+    // Store initial transform of the GLTF mesh component (what we'll be animating)
+    this.initialTransform = {
+      position: gltfComponent.position.clone(),
+      rotation: gltfComponent.rotation.clone(),
+      scale: gltfComponent.scale.clone()
+    };
+
+    // Find the door mesh and calculate pivot point
+    this.findDoorMesh(model);
+    this.calculatePivotPoint();
+
+    // Fix physics options - doors should be kinematic (can be moved by code but not physics)
+    gltfComponent.replacePhysicsOptions({
+      enabled: true,
+      motionType: PhysicsMotionType.KinematicPositionBased,
+      generateCollisionEvents: false, // We don't need collision events from the door itself
+      collisionMeshType: CollisionMeshType.ConvexHull,
+      density: 1.0
+    });
+
+  }
+
+  /**
+   * Finds the main door mesh in the model
+   */
+  private findDoorMesh(model: THREE.Object3D): void {
+    let bestCandidate: THREE.Mesh | null = null;
+    let bestScore = 0;
+
+    model.traverse((object) => {
+      if (object instanceof THREE.Mesh) {
+        // Score potential door meshes based on name and dimensions
+        let score = 0;
+
+        const name = object.name.toLowerCase();
+        if (name.includes('door')) score += 10;
+        if (name.includes('panel')) score += 5;
+        if (name.includes('leaf')) score += 5;
+
+        // Check dimensions (doors are typically tall and rectangular)
+        const bbox = new THREE.Box3().setFromObject(object);
+        const size = bbox.getSize(new THREE.Vector3());
+
+        if (size.y > 1.5 && size.y > size.x && size.y > size.z) {
+          score += 5; // Tall object
+        }
+
+        if (score > bestScore) {
+          bestScore = score;
+          bestCandidate = object;
+        }
+      }
+    });
+
+    this.doorMesh = bestCandidate;
+  }
+
+  /**
+   * Calculates the appropriate pivot point for door animation
+   */
+  private calculatePivotPoint(): void {
+    if (!this.doorMesh) return;
+
+    const bbox = new THREE.Box3().setFromObject(this.doorMesh);
+
+    switch (this.options.doorType) {
+      case DoorType.Hinged:
+        // Pivot at the edge of the door (typically left side)
+        const center1 = new THREE.Vector3();
+        bbox.getCenter(center1);
+        this.doorPivotPoint = new THREE.Vector3(bbox.min.x, bbox.min.y, center1.z);
+        break;
+
+      case DoorType.Sliding:
+        // No pivot needed for sliding doors
+        this.doorPivotPoint = null;
+        break;
+
+      case DoorType.Garage:
+        // Pivot at the bottom edge
+        const center2 = new THREE.Vector3();
+        bbox.getCenter(center2);
+        this.doorPivotPoint = new THREE.Vector3(center2.x, bbox.min.y, bbox.min.z);
+        break;
+
+      case DoorType.Double:
+        // For double doors, use center as pivot (each door swings outward)
+        const center3 = new THREE.Vector3();
+        bbox.getCenter(center3);
+        this.doorPivotPoint = new THREE.Vector3(center3.x, bbox.min.y, center3.z);
+        break;
+    }
+  }
+
+  /**
+   * Sets up proximity detection for door interaction
+   */
+  private setupProximityDetection(): void {
+    const actor = this.getActor();
+    if (!actor) return;
+
+    if (this.useCollisionBasedProximity && this.existingCollisionShape) {
+      this.setupCollisionBasedProximity();
+    } else {
+      this.setupDistanceBasedProximity();
+    }
+  }
+
+  /**
+   * Sets up collision-based proximity detection using existing CollisionShapeComponent
+   */
+  private setupCollisionBasedProximity(): void {
+    if (!this.existingCollisionShape) return;
+
+    // Bind to overlap events for proximity detection (using sensor/trigger volumes)
+    this.existingCollisionShape.onOverlapWith.add((thisComponent, otherComponent, collisionEvent) => {
+      const otherActor = otherComponent.getActor();
+      if (otherActor && this.isPlayerPawn(otherActor)) {
+        this.playersInRange.add(otherActor);
+        this.handleProximityChange();
+      }
+    });
+
+    // Bind to overlap end events for proximity exit detection
+    this.existingCollisionShape.onStopOverlappingWith.add((thisComponent, otherComponent, collisionEvent) => {
+      const otherActor = otherComponent.getActor();
+      if (otherActor && this.isPlayerPawn(otherActor)) {
+        this.playersInRange.delete(otherActor);
+        this.handleProximityChange();
+      }
+    });
+  }
+
+  /**
+   * Sets up collision-based proximity detection with a new proximity trigger that only detects player pawns
+   */
+  private async setupDistanceBasedProximity(): Promise<void> {
+    const actor = this.getActor();
+    if (!actor) return;
+
+    // Calculate trigger position based on door geometry
+    const doorPosition = actor.rootComponent.position.clone();
+
+    // Wait for door geometry to be initialized so we can use the door bounds
+    let triggerPosition = doorPosition.clone();
+
+    if (this.doorMesh) {
+      // If we have door mesh info, position the trigger at the center of the door panel
+      this.doorMesh.geometry.computeBoundingBox();
+      const boundingBox = this.doorMesh.geometry.boundingBox;
+      if (boundingBox) {
+        // Get the center of the door panel in local space
+        const doorCenter = new THREE.Vector3();
+        boundingBox.getCenter(doorCenter);
+
+        // Transform to world space
+        const worldCenter = doorCenter.clone();
+        this.doorMesh.localToWorld(worldCenter);
+
+        // Use the door center as the trigger position
+        triggerPosition.copy(worldCenter);
+        triggerPosition.y = doorPosition.y + 1.25; // Keep the vertical center
+
+      }
+    } else {
+      // Fallback: offset the trigger towards the door panel (assuming standard door orientation)
+      // For a hinged door, offset forward by about half a door width (typical door is ~0.8m wide)
+      const doorForward = new THREE.Vector3(0, 0, 1); // Towards the door panel
+      const offsetDistance = 0.4; // Half a typical door width
+
+      triggerPosition.add(doorForward.multiplyScalar(offsetDistance));
+      triggerPosition.y += 1.25; // Center vertically
+
+    }
+
+
+
+    // Create a simple actor to hold the trigger component
+    const world = actor.getWorld();
+    if (world) {
+      // Create the trigger component that only overlaps with Pawn channel (player pawns)
+      this.proximityTrigger = new CollisionShapeComponent({
+        shapeType: CollisionShapeType.Cube,
+        scale: new THREE.Vector3(
+          this.options.proximityRange * 2,
+          2.5,
+          this.options.proximityRange * 2
+        ),
+        physicsOptions: {
+          enabled: true,
+          motionType: PhysicsMotionType.Static,
+          generateCollisionEvents: true,
+          // Use Trigger profile which only generates overlap events, no blocking
+          collisionProfile: DefaultCollisionProfile.Trigger
+        }
+      });
+
+      // Bind to overlap events for proximity detection - this will only trigger for Pawn channel objects
+      this.proximityTrigger.onOverlapWith.add((thisComponent, otherComponent, collisionEvent) => {
+        const otherActor = otherComponent.getActor();
+        if (otherActor && this.isPlayerPawn(otherActor)) {
+          this.playersInRange.add(otherActor);
+          this.handleProximityChange();
+        }
+      });
+
+      // Bind to overlap end events for proximity exit detection
+      this.proximityTrigger.onStopOverlappingWith.add((thisComponent, otherComponent, collisionEvent) => {
+        const otherActor = otherComponent.getActor();
+        if (otherActor && this.isPlayerPawn(otherActor)) {
+          this.playersInRange.delete(otherActor);
+          this.handleProximityChange();
+        }
+      });
+
+      // Create an actor with a simple root component
+      const triggerActor = new Actor({
+        position: triggerPosition,
+        rootComponent: new SceneComponent({})
+      });
+
+      // Add the trigger as a child component
+      triggerActor.rootComponent.add(this.proximityTrigger);
+
+      // Add to world
+      world.addActors(triggerActor);
+
+      // Switch to collision-based proximity since we're now using collision events
+      this.useCollisionBasedProximity = true;
+    } else {
+      console.log('[DoorComponent] Could not get world to add trigger');
+    }
+  }
+
+  /**
+   * Checks if an actor is a player pawn (controlled by a PlayerController)
+   */
+  private isPlayerPawn(actor: Actor): boolean {
+    return actor.getPlayerController() !== null;
+  }
+
+  /**
+   * Handles proximity change events for automatic doors
+   */
+  private handleProximityChange(): void {
+    if (this.options.interactionType !== DoorInteractionType.Proximity) return;
+
+    const hasPlayersInRange = this.playersInRange.size > 0;
+
+    // Player entered range - open door (can interrupt closing animation)
+    if (hasPlayersInRange && (this.currentState === DoorState.Closed || this.currentState === DoorState.Closing)) {
+      this.startOpening();
+    }
+    // Player left range - close door (can interrupt opening animation)
+    else if (!hasPlayersInRange && (this.currentState === DoorState.Open || this.currentState === DoorState.Opening)) {
+      this.startClosing();
+    }
+  }
+
+  /**
+   * Proximity check - handles both collision-based and distance-based detection
+   */
+  private updateProximityCheck(): void {
+    const world = this.getActor()?.getWorld();
+    if (!world) return;
+
+    const previousCount = this.playersInRange.size;
+
+    if (this.useCollisionBasedProximity) {
+      // For collision-based proximity, detection is handled entirely by collision events
+      // No additional processing needed here
+    } else {
+      // For distance-based proximity, do full distance calculation
+      this.updateDistanceBasedProximity();
+    }
+
+    // Handle automatic proximity-based interaction
+    this.handleProximityChange();
+  }
+
+  /**
+   * Updates distance-based proximity detection
+   */
+  private updateDistanceBasedProximity(): void {
+    if (!this.proximityTrigger) return;
+
+    const world = this.getActor()?.getWorld();
+    if (!world) return;
+
+    const triggerPosition = this.proximityTrigger.getWorldPosition(new THREE.Vector3());
+    const range = this.options.proximityRange;
+    const previousCount = this.playersInRange.size;
+
+    // Clear current players in range
+    this.playersInRange.clear();
+
+    // Check all actors in the world that are player pawns
+    const playerActors = world.getActorsByPredicate(actor => this.isPlayerPawn(actor));
+
+    for (const actor of playerActors) {
+      const actorPosition = actor.rootComponent.getWorldPosition(new THREE.Vector3());
+      const distance = triggerPosition.distanceTo(actorPosition);
+
+      if (distance <= range) {
+        this.playersInRange.add(actor);
+
+        // Log when player enters range for the first time
+        if (previousCount === 0) {
+        }
+      }
+    }
+  }
+
+  /**
+   * Updates input registration based on proximity
+   */
+  private updateInputRegistration(): void {
+    const shouldBeRegistered = this.playersInRange.size > 0 &&
+      this.options.interactionType === DoorInteractionType.KeyPress;
+
+    if (shouldBeRegistered && !this.isRegisteredForInput) {
+      const world = this.getActor()?.getWorld();
+      if (world) {
+        // Register with high priority by adding to the beginning of the handler list
+        // This ensures the door component gets the input before other handlers
+        world.inputManager.addInputHandler(this);
+
+        const inputManager = world.inputManager as any;
+        const handlers = inputManager.inputHandlers as IInputHandler[];
+        const index = handlers.indexOf(this);
+        if (index > 0) {
+          handlers.splice(index, 1); // Remove from current position
+          handlers.unshift(this);    // Add to beginning
+        }
+
+        this.isRegisteredForInput = true;
+      }
+    } else if (!shouldBeRegistered && this.isRegisteredForInput) {
+      const world = this.getActor()?.getWorld();
+      if (world) {
+        // Unregister from input handling
+        world.inputManager.removeInputHandler(this);
+        this.isRegisteredForInput = false;
+      }
+    }
+  }
+
+
+  /**
+   * Applies transform to door based on animation progress
+   */
+  private applyDoorTransform(progress: number): void {
+    if (!this.initialTransform || !this.gltfMeshComponent) return;
+
+    const actor = this.getActor();
+    if (!actor) return;
+
+    switch (this.options.doorType) {
+      case DoorType.Hinged:
+        this.applyHingedTransform(this.gltfMeshComponent, progress);
+        break;
+
+      case DoorType.Sliding:
+        this.applySlidingTransform(this.gltfMeshComponent, actor, progress);
+        break;
+
+      case DoorType.Garage:
+        this.applyGarageTransform(this.gltfMeshComponent, progress);
+        break;
+
+      case DoorType.Double:
+        this.applyDoubleTransform(this.gltfMeshComponent, progress);
+        break;
+
+      case DoorType.Custom:
+        // Custom doors handle their own animation via delegates
+        // No built-in transform is applied
+        break;
+    }
+  }
+
+  /**
+   * Applies hinged door animation
+   */
+  private applyHingedTransform(gltfComponent: GLTFMeshComponent, progress: number): void {
+    if (!this.initialTransform) return;
+
+    const openAngle = THREE.MathUtils.degToRad(this.options.maxOpenAngle) * progress;
+
+    // Reset to initial position and rotation
+    gltfComponent.position.copy(this.initialTransform.position);
+    gltfComponent.rotation.copy(this.initialTransform.rotation);
+
+    // For hinged doors, we rotate around Y-axis in local space
+    // Transform this axis by the Actor's world rotation to make it work with any door orientation
+    const actor = this.getActor();
+    if (actor) {
+      const actorWorldRotation = actor.getWorldRotation();
+
+      // The hinge axis in local space (Y-axis)
+      const localHingeAxis = new THREE.Vector3(0, 1, 0);
+
+      // Transform the hinge axis by the Actor's world rotation
+      const worldHingeAxis = localHingeAxis.clone();
+      worldHingeAxis.applyEuler(actorWorldRotation);
+
+      // Create a quaternion representing rotation around the transformed hinge axis
+      const hingeQuaternion = new THREE.Quaternion();
+      hingeQuaternion.setFromAxisAngle(worldHingeAxis, openAngle);
+
+      // Apply this rotation to the mesh's current rotation
+      const currentQuaternion = new THREE.Quaternion().setFromEuler(gltfComponent.rotation);
+      currentQuaternion.multiply(hingeQuaternion);
+
+      gltfComponent.rotation.setFromQuaternion(currentQuaternion);
+    } else {
+      // Fallback: just apply Y rotation (original behavior)
+      gltfComponent.rotation.y += openAngle;
+    }
+  }
+
+  /**
+   * Applies sliding door animation
+   */
+  private applySlidingTransform(gltfComponent: GLTFMeshComponent, actor: Actor, progress: number): void {
+    if (!this.initialTransform) return;
+
+    const slideOffset = this.options.slideDistance * progress;
+
+    // Reset to initial position
+    gltfComponent.position.copy(this.initialTransform.position);
+    gltfComponent.rotation.copy(this.initialTransform.rotation);
+
+    // Use the configurable slide direction in the door's local coordinate system
+    // Transform it by the Actor's world rotation to make it work with any door orientation
+    const slideDirection = this.options.slideDirection ?? new THREE.Vector3(1, 0, 0);
+    const worldSlideVector = slideDirection.clone().normalize();
+
+    // Apply the Actor's world rotation to transform the slide direction from local to world space
+    // This makes the sliding direction relative to the door's actual orientation in the world
+    const actorWorldRotation = actor.getWorldRotation();
+    worldSlideVector.applyEuler(actorWorldRotation);
+
+    // Apply sliding offset in the calculated world direction
+    const slideVector = worldSlideVector.multiplyScalar(slideOffset);
+    gltfComponent.position.add(slideVector);
+  }
+
+  /**
+   * Applies garage door animation (combination of rotation and translation)
+   */
+  private applyGarageTransform(gltfComponent: GLTFMeshComponent, progress: number): void {
+    if (!this.initialTransform) return;
+
+    const maxAngle = THREE.MathUtils.degToRad(90) * progress;
+    const liftHeight = 2.0 * progress;
+
+    // Reset to initial position
+    gltfComponent.position.copy(this.initialTransform.position);
+    gltfComponent.rotation.copy(this.initialTransform.rotation);
+
+    // Rotate and lift
+    gltfComponent.rotation.x -= maxAngle;
+    gltfComponent.position.y += liftHeight;
+  }
+
+  /**
+   * Applies double door animation
+   */
+  private applyDoubleTransform(gltfComponent: GLTFMeshComponent, progress: number): void {
+    // For now, treat as single hinged door
+    // In Phase 3, this will coordinate multiple door panels
+    this.applyHingedTransform(gltfComponent, progress);
+  }
+
+  //====================================================================================================
+  // Editor Functions
+  //====================================================================================================
+
+  public override getEditorClassIcon(): string | null {
+    return 'Icon_Door';
+  }
+}