@directivegames/genesys.js 3.1.24

package/src/components/movement/NpcMovementComponent.ts

@@ -0,0 +1,930 @@
+/**
+ * NpcMovementComponent drives AI-controlled characters along paths or toward
+ * targets.
+ *
+ * Built on CharacterMovementComponent, it augments the basic movement model
+ * with path following, actor following, and integration with the navigation
+ * server. Options expose distances for stopping or maintaining a follow
+ * offset, plus parameters for path refresh cadence. The component stores the
+ * computed path internally and moves the actor each tick, rotating it to face
+ * waypoints or the target actor.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Use when an NPC needs simple autonomous locomotion.
+ * - Call `followPath` or `followActor` to start movement.
+ * - Tweak speeds and refresh rates based on gameplay needs.
+ */
+import * as THREE from 'three';
+
+import { EngineClass } from '../../systems/ClassRegistry.js';
+
+import { CharacterMovementComponent, CharacterMovementType } from './CharacterMovementComponent.js';
+
+import type { CharacterMovementOptions } from './CharacterMovementComponent.js';
+import type { Actor } from '../../actors/Actor.js';
+import type { INavigationServer } from '../../navigation/NavigationServer.js';
+import type { CharacterControllerOptions } from '../../physics/PhysicsEngine.js';
+import type { EditorClassMeta } from '../../utils/EditorClassMeta.js';
+import type { SceneGraphDebugNode } from '../../utils/SceneGraphUtils.js';
+
+export interface NpcMovementOptions extends CharacterMovementOptions {
+  pathFollowingAccuracy: number;
+  actorFollowingDistance: number;
+  stopDistance: number;
+  movementSpeed?: number;
+  turnSpeed?: number;
+
+  // Whether to use the navigation server to calculate paths
+  useNavigationServer?: boolean;
+
+  // Debug visualization options
+  debugVisualization?: {
+    enabled: boolean;
+    pathColor?: number;
+    targetColor?: number;
+    lineWidth?: number;
+    showWaypoints?: boolean;
+    waypointSize?: number;
+  };
+}
+
+/**
+ * Component that handles NPC movement for pawns
+ * Provides functionality for following paths and other actors
+ * Uses CharacterMovementComponent for actual movement simulation
+ */
+@EngineClass('NpcMovementComponent')
+export class NpcMovementComponent extends CharacterMovementComponent {
+
+  static override get DEFAULT_OPTIONS(): NpcMovementOptions {
+    return {
+      ...CharacterMovementComponent.DEFAULT_OPTIONS,
+      movementType: CharacterMovementType.ThirdPerson,
+      maxSpeed: 20,
+      midAirAccelerationLambda: 100,
+      midAirDecelerationLambda: 10,
+      lookRightSpeed: 0.05,
+      lookUpSpeed: 0, // NPCs don't look up/down
+      jumpSpeed: 0, // NPCs don't jump
+      pathFollowingAccuracy: 3.0,
+      actorFollowingDistance: 4.0,
+      stopDistance: 1.0,
+      movementSpeed: 20,
+      turnSpeed: 10,
+      useNavigationServer: true,
+      debugVisualization: {
+        enabled: false,
+        pathColor: 0x00ff00,
+        targetColor: 0xff0000,
+        lineWidth: 10,
+        showWaypoints: true,
+        waypointSize: 0.7
+      }
+    };
+  };
+
+  static override readonly EDITOR_CLASS_META: EditorClassMeta = {
+    ...CharacterMovementComponent.EDITOR_CLASS_META,
+    movementType: { select: [CharacterMovementType.FirstPerson, CharacterMovementType.ThirdPerson] }
+  } as const;
+
+  private targetPosition: THREE.Vector3 | null = null;
+  private pathPoints: THREE.Vector3[] = [];
+  private currentPathIndex: number = 0;
+  private actorToFollow: Actor | null = null;
+  private isLoopedPath: boolean = false;
+  private continueFollowingAfterReached: boolean = true;
+
+  // Private stopDistance that can be overridden by actions
+  private currentStopDistance: number;
+
+  // Look-at functionality
+  private lookAtTarget: THREE.Vector3 | null = null;
+  private lookAtThreshold: number = Math.PI / 16; // ~11.25 degrees
+  private isLookingAtTarget: boolean = false;
+
+  // Debug visualization
+  private debugGroup: THREE.Group | null = null;
+  private pathLine: THREE.Line | null = null;
+  private waypointSpheres: THREE.Mesh[] = [];
+  private targetSphere: THREE.Mesh | null = null;
+
+  private navigationServer: INavigationServer | null = null;
+
+  constructor(private npcOptions: NpcMovementOptions = NpcMovementComponent.DEFAULT_OPTIONS) {
+    super({
+      ...npcOptions,
+      maxSpeed: npcOptions.movementSpeed ?? NpcMovementComponent.DEFAULT_OPTIONS.maxSpeed,
+      lookRightSpeed: npcOptions.turnSpeed ?? NpcMovementComponent.DEFAULT_OPTIONS.lookRightSpeed,
+    });
+
+    // Initialize currentStopDistance from options
+    this.currentStopDistance = npcOptions.stopDistance;
+  }
+
+  /**
+   * Sets a path for the NPC to follow
+   * @param points Array of points defining the path
+   * @param looped Whether the path should loop back to start when finished
+   */
+  public setPath(points: THREE.Vector3[], looped: boolean = false): void {
+    // Filter out any points that are too close to the NPC's current position
+    // This prevents the immediate removal of the first point in handlePathPointTransition
+    const owner = this.getActor();
+    if (owner && points.length > 0) {
+      const currentPosition = this.getCurrentPosition(owner);
+      const filteredPoints = points.filter(point => {
+        const distance = currentPosition.distanceTo(point);
+        return distance >= this.npcOptions.pathFollowingAccuracy;
+      });
+
+      this.pathPoints = filteredPoints;
+    } else {
+      this.pathPoints = points;
+    }
+
+    this.currentPathIndex = 0;
+    // Don't automatically clear actorToFollow - let the caller manage it
+    this.isLoopedPath = looped;
+    this.updateTargetPosition();
+  }
+
+  /**
+   * Sets the actor to follow without clearing the current path
+   * @param actor The actor to follow
+   * @param continueAfterReached Whether to continue following after reaching the target
+   */
+  public setFollowedActor(actor: Actor | null, continueAfterReached: boolean = true): void {
+    this.actorToFollow = actor;
+    this.continueFollowingAfterReached = continueAfterReached;
+  }
+
+  /**
+   * Sets an actor for the NPC to follow
+   * @param actor The actor to follow
+   * @param continueAfterReached Whether to continue following after reaching the target
+   */
+  public followActor(actor: Actor | null, continueAfterReached: boolean = true): void {
+    this.actorToFollow = actor;
+    this.pathPoints = [];
+    this.currentPathIndex = 0;
+    this.targetPosition = null;
+    this.continueFollowingAfterReached = continueAfterReached;
+  }
+
+  /**
+   * Sets a target position for the NPC to move to, automatically calculating the path
+   * @param targetPosition The world position to move to
+   * @param stopDistance Optional stop distance override
+   */
+  public setTargetPosition(targetPosition: THREE.Vector3, stopDistance?: number): void {
+    // Clear any actor following
+    this.actorToFollow = null;
+
+    // Set stop distance if provided
+    if (stopDistance !== undefined) {
+      this.currentStopDistance = stopDistance;
+    }
+
+    // Calculate path to target
+    this.calculateAndSetPathToPosition(targetPosition);
+  }
+
+  /**
+   * Sets a target actor for the NPC to follow, automatically handling path calculation
+   * @param actor The actor to follow
+   * @param followDistance The distance to maintain from the target
+   * @param continueAfterReached Whether to continue following after reaching the target
+   */
+  public setTargetActor(actor: Actor | null, followDistance?: number, continueAfterReached: boolean = true): void {
+    this.actorToFollow = actor;
+    this.continueFollowingAfterReached = continueAfterReached;
+
+    // Set follow distance if provided
+    if (followDistance !== undefined) {
+      this.npcOptions.actorFollowingDistance = followDistance;
+    }
+
+    // Clear any existing path - actor following will be handled in tick
+    this.pathPoints = [];
+    this.currentPathIndex = 0;
+    this.targetPosition = null;
+  }
+
+  /**
+   * Sets the stop distance for this NPC
+   * @param distance The distance at which the NPC should stop when approaching targets
+   */
+  public setStopDistance(distance: number): void {
+    this.currentStopDistance = distance;
+  }
+
+  /**
+   * Gets the current stop distance
+   */
+  public getStopDistance(): number {
+    return this.currentStopDistance;
+  }
+
+  /**
+   * Stops all movement inputs without clearing the path
+   */
+  public stopMovement(): void {
+    this.addForwardInput(0);
+    this.addLookRightInput(0);
+  }
+
+  /**
+   * Stops the NPC movement and clears the path
+   */
+  public stop(): void {
+    this.targetPosition = null;
+    this.pathPoints = [];
+    this.currentPathIndex = 0;
+    this.actorToFollow = null;
+    this.addForwardInput(0);
+    this.addRightInput(0);
+    this.addLookRightInput(0);
+  }
+
+  private updateTargetPosition(): void {
+    if (this.pathPoints.length > 0) {
+      if (this.currentPathIndex >= this.pathPoints.length) {
+        if (this.isLoopedPath) {
+          this.currentPathIndex = 0;
+        } else {
+          this.targetPosition = null;
+          return;
+        }
+      }
+      this.targetPosition = this.pathPoints[this.currentPathIndex];
+    } else {
+      this.targetPosition = null;
+    }
+  }
+
+  public override beginPlay(): void {
+    super.beginPlay();
+
+    // Initialize debug visualization if enabled
+    if (this.npcOptions.debugVisualization?.enabled) {
+      this.initializeDebugVisualization();
+    }
+
+    // Get reference to navigation server
+    this.navigationServer = this.getWorld()?.getNavigationServer() ?? null;
+  }
+
+  public override endPlay(): void {
+    super.endPlay();
+
+    // Clean up debug visualization
+    this.cleanupDebugVisualization();
+  }
+
+  public override tickPrePhysics(deltaTime: number): void {
+    // Get current position and update actor following if needed
+    const owner = this.getActor()!;
+    const currentPosition = this.getCurrentPosition(owner);
+
+    // Update target position if following an actor
+    this.updateActorFollowingTarget(currentPosition);
+
+    // Handle movement based on navigation type
+    if (this.canUseNavigationServer()) {
+      this.handleNavigationServerMovement(owner, currentPosition);
+    } else {
+      this.handleStandardMovement(owner, currentPosition);
+    }
+
+    // Handle look-at targets even when not moving
+    if (this.lookAtTarget && this.isLookingAtTarget && !this.targetPosition) {
+      this.handleLookAtTarget(owner);
+    }
+
+    // Update debug visualization
+    if (this.npcOptions.debugVisualization?.enabled) {
+      this.updateDebugVisualization();
+    }
+
+    // Let CharacterMovementComponent handle the actual movement
+    super.tickPrePhysics(deltaTime);
+  }
+
+  /**
+   * Gets the current world position of the NPC
+   */
+  private getCurrentPosition(owner: Actor): THREE.Vector3 {
+    const currentPosition = new THREE.Vector3();
+    owner.rootComponent.getWorldPosition(currentPosition);
+    return currentPosition;
+  }
+
+  /**
+   * Updates the target position when following an actor
+   */
+  private updateActorFollowingTarget(currentPosition: THREE.Vector3): void {
+    if (!this.actorToFollow) return;
+
+    const actorPosition = new THREE.Vector3();
+    this.actorToFollow.rootComponent.getWorldPosition(actorPosition);
+    const distanceToActor = currentPosition.distanceTo(actorPosition);
+
+    if (distanceToActor > this.npcOptions.actorFollowingDistance) {
+      // Check if we need to recalculate the path to the actor
+      if (this.shouldRecalculatePathToActor(actorPosition)) {
+        this.calculateAndSetPathToPosition(actorPosition);
+      }
+    } else {
+      this.targetPosition = null;
+      if (!this.continueFollowingAfterReached) {
+        this.actorToFollow = null;
+      }
+    }
+  }
+
+  /**
+   * Handles movement when using the navigation server for pathfinding
+   */
+  private handleNavigationServerMovement(owner: Actor, currentPosition: THREE.Vector3): void {
+    if (!this.targetPosition) {
+      this.stopMovement();
+      return;
+    }
+
+    // Get the first path point if we have a path
+    const nextPoint = this.pathPoints.length > 0 ? this.pathPoints[0] : this.targetPosition;
+
+    // Calculate direction and distance to the next point
+    let toPoint = nextPoint.clone().sub(currentPosition);
+    toPoint.y = 0; // Flatten to XZ plane
+    const distanceToPoint = toPoint.length();
+
+    // Handle path point transitions
+    this.handlePathPointTransition(distanceToPoint);
+
+    // Check if targetPosition was cleared by handlePathPointTransition (single-point path completed)
+    if (!this.targetPosition) {
+      this.stopMovement();
+      return;
+    }
+
+    // Handle destination arrival
+    if (this.hasReachedDestination(distanceToPoint)) {
+      return;
+    }
+
+    if (distanceToPoint > this.npcOptions.pathFollowingAccuracy) {
+      // Move toward the point
+      this.moveTowardPoint(owner, toPoint, distanceToPoint);
+    } else {
+      // We're close enough to the waypoint - stop both movement and rotation
+      this.stopMovement();
+    }
+  }
+
+  /**
+   * Handles standard movement without using the navigation server
+   */
+  private handleStandardMovement(owner: Actor, currentPosition: THREE.Vector3): void {
+    if (!this.targetPosition) {
+      this.stopMovement();
+      return;
+    }
+
+    let toTarget = this.targetPosition.clone().sub(currentPosition);
+    toTarget.y = 0;
+    const distanceToTarget = toTarget.length();
+
+    // Check if we need to move to next path point
+    if (this.pathPoints.length > 0 && distanceToTarget < this.npcOptions.pathFollowingAccuracy) {
+      this.currentPathIndex++;
+      this.updateTargetPosition();
+
+      if (!this.targetPosition) {
+        this.stop();
+        return;
+      }
+    }
+
+    // Move toward the target
+    this.moveTowardPoint(owner, toTarget, distanceToTarget);
+  }
+
+  /**
+   * Handles checking if we should move to the next path point
+   */
+  private handlePathPointTransition(distanceToPoint: number): void {
+    // If we're close enough to the current point
+    if (distanceToPoint < this.npcOptions.pathFollowingAccuracy) {
+      if (this.pathPoints.length > 1) {
+        // Remove the first point and target the next one
+        this.pathPoints.shift();
+      } else if (this.pathPoints.length === 1) {
+        // For single-point paths, remove the point so the NPC knows it's done
+        this.pathPoints.shift();
+        this.targetPosition = null;
+      }
+    }
+  }
+
+  /**
+   * Checks if the NPC has reached its final destination
+   */
+  private hasReachedDestination(distanceToPoint: number): boolean {
+    if (distanceToPoint < this.currentStopDistance && this.pathPoints.length <= 1) {
+      if (!this.actorToFollow) {
+        this.stop();
+        return true;
+      } else {
+        this.stopMovement();
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Moves the NPC toward a specific point
+   */
+  private moveTowardPoint(owner: Actor, toPoint: THREE.Vector3, distance: number): void {
+    // Check if we have a look-at target that takes priority
+    if (this.lookAtTarget && this.isLookingAtTarget) {
+      this.handleLookAtTarget(owner);
+    } else {
+      // Normal movement rotation logic
+      // Normalize the direction vector
+      const toPointFlat = toPoint.clone().normalize();
+
+      // Get current forward direction
+      const currentForward = owner.forwardDirection();
+      currentForward.y = 0;
+      currentForward.normalize();
+
+      // Calculate the rotation angle
+      const yawDiff = this.calculateYawDifference(currentForward, toPointFlat);
+
+      // Apply rotation input - negative because we want to turn toward the target
+      this.addLookRightInput(-yawDiff);
+    }
+
+    // Apply movement input based on the required turn angle (only if not prioritizing look-at)
+    if (!this.isLookingAtTarget) {
+      const toPointFlat = toPoint.clone().normalize();
+      const currentForward = owner.forwardDirection();
+      currentForward.y = 0;
+      currentForward.normalize();
+      const yawDiff = this.calculateYawDifference(currentForward, toPointFlat);
+      this.applyMovementInput(yawDiff, distance);
+    } else {
+      // When looking at target, stop movement
+      this.addForwardInput(0);
+    }
+  }
+
+  /**
+   * Handles look-at target rotation
+   */
+  private handleLookAtTarget(owner: Actor): void {
+    if (!this.lookAtTarget) return;
+
+    const ownerPosition = new THREE.Vector3();
+    owner.rootComponent.getWorldPosition(ownerPosition);
+
+    // Calculate direction to look-at target
+    const direction = this.lookAtTarget.clone().sub(ownerPosition);
+    direction.y = 0; // Flatten to XZ plane
+
+    if (direction.length() < 0.001) {
+      return; // Too close to determine direction
+    }
+
+    direction.normalize();
+
+    // Get current forward direction
+    const currentForward = owner.forwardDirection();
+    currentForward.y = 0;
+    currentForward.normalize();
+
+    // Calculate the rotation angle using the same logic as movement
+    const yawDiff = this.calculateYawDifference(currentForward, direction);
+
+    // Apply rotation input - negative because we want to turn toward the target
+    this.addLookRightInput(-yawDiff);
+  }
+
+  /**
+   * Calculates the yaw difference between current direction and target direction
+   */
+  private calculateYawDifference(currentDirection: THREE.Vector3, targetDirection: THREE.Vector3): number {
+    // Calculate rotation using dot product and cross product
+    const dot = currentDirection.dot(targetDirection);
+    const cross = currentDirection.cross(targetDirection).y;
+
+    // Calculate the smallest angle between current direction and target
+    let yawDiff = Math.atan2(cross, dot);
+
+    // Clamp the rotation input
+    return THREE.MathUtils.clamp(yawDiff, -1, 1);
+  }
+
+  /**
+   * Applies appropriate movement input based on turn angle and distance
+   */
+  private applyMovementInput(yawDiff: number, distance: number): void {
+    // Add movement input if we're roughly facing the right direction
+    if (Math.abs(yawDiff) < Math.PI / 4) {
+      if (this.canUseNavigationServer()) {
+        // Use speed proportional to distance for navigation server
+        const speedFactor = Math.max(0.3, Math.min(1.0, distance / (this.npcOptions.pathFollowingAccuracy * 2)));
+        this.addForwardInput(speedFactor);
+      } else {
+        // Use full speed for standard movement
+        this.addForwardInput(1.0);
+      }
+    } else {
+      // Slow down when turning sharply (only for navigation server)
+      this.addForwardInput(this.canUseNavigationServer() ? 0.1 : 0);
+    }
+  }
+
+  /**
+   * Checks if the navigation server is available and ready
+   */
+  public canUseNavigationServer(): boolean {
+    // Must want to use navigation
+    if (!this.npcOptions.useNavigationServer) {
+      return false;
+    }
+
+    // Must have a navigation server instance
+    if (!this.navigationServer) {
+      // Try to get it again in case it was created after beginPlay
+      this.navigationServer = this.getWorld()?.getNavigationServer() ?? null;
+      if (!this.navigationServer) {
+        return false;
+      }
+    }
+
+    // Navigation server must be ready (have a navigation mesh)
+    return this.navigationServer.isReady();
+  }
+
+  /**
+   * Gets the current target position (if any)
+   */
+  public getCurrentTarget(): THREE.Vector3 | null {
+    return this.targetPosition ? this.targetPosition.clone() : null;
+  }
+
+  /**
+   * Gets the current path points
+   */
+  public getCurrentPath(): THREE.Vector3[] {
+    const result = this.pathPoints.slice(); // Return a copy
+    return result;
+  }
+
+  /**
+   * Gets the current path index
+   */
+  public getCurrentPathIndex(): number {
+    return this.currentPathIndex;
+  }
+
+  /**
+   * Gets the total number of path points
+   */
+  public getPathLength(): number {
+    return this.pathPoints.length;
+  }
+
+  /**
+   * Gets the actor being followed (if any)
+   */
+  public getFollowedActor(): Actor | null {
+    return this.actorToFollow;
+  }
+
+  /**
+   * Checks if the NPC has reached its current target position
+   */
+  public hasReachedCurrentTarget(): boolean {
+    const currentPosition = this.getCurrentPosition(this.getActor()!);
+    if (!this.targetPosition) {
+      return true;
+    }
+    let toTarget = this.targetPosition.clone().sub(currentPosition);
+    toTarget.y = 0; // Flatten to XZ plane
+    const distanceToTarget = toTarget.length();
+    return distanceToTarget <= this.currentStopDistance;
+  }
+
+  /**
+   * Sets a target position for the NPC to look at
+   * @param targetPosition The world position to look at
+   * @param threshold Optional angle threshold in radians (defaults to ~11.25 degrees)
+   */
+  public setLookAtTarget(targetPosition: THREE.Vector3, threshold?: number): void {
+    this.lookAtTarget = targetPosition.clone();
+    if (threshold !== undefined) {
+      this.lookAtThreshold = threshold;
+    }
+    this.isLookingAtTarget = true;
+  }
+
+  /**
+   * Clears the current look-at target
+   */
+  public clearLookAtTarget(): void {
+    this.lookAtTarget = null;
+    this.isLookingAtTarget = false;
+    this.addLookRightInput(0); // Stop any rotation input
+  }
+
+  /**
+   * Checks if the NPC is currently looking at the target (within threshold)
+   */
+  public isLookingAtTargetComplete(): boolean {
+    if (!this.lookAtTarget || !this.isLookingAtTarget) {
+      return true; // No target means "complete"
+    }
+
+    const owner = this.getActor()!;
+    const ownerPosition = new THREE.Vector3();
+    owner.rootComponent.getWorldPosition(ownerPosition);
+
+    // Calculate direction to target
+    const direction = this.lookAtTarget.clone().sub(ownerPosition);
+    direction.y = 0; // Flatten to XZ plane
+
+    if (direction.length() < 0.001) {
+      return true; // Too close to determine direction
+    }
+
+    direction.normalize();
+
+    // Get current forward direction
+    const currentForward = owner.forwardDirection();
+    currentForward.y = 0;
+    currentForward.normalize();
+
+    // Calculate angle difference
+    const dot = currentForward.dot(direction);
+    const cross = currentForward.cross(direction).y;
+    const yawDiff = Math.atan2(cross, dot);
+
+    return Math.abs(yawDiff) <= this.lookAtThreshold;
+  }
+
+  public override generateDebugNode(): SceneGraphDebugNode | null {
+    return {
+      title: this.name,
+      data: this.npcOptions
+    };
+  }
+
+  /**
+   * Determines if we need to recalculate the path when following an actor
+   */
+  private shouldRecalculatePathToActor(actorPosition: THREE.Vector3): boolean {
+    // Always recalculate if we have no path
+    if (this.pathPoints.length === 0) {
+      return true;
+    }
+
+    // Check if we've reached the end of our current path
+    if (this.hasReachedCurrentTarget() && this.currentPathIndex >= this.pathPoints.length - 1) {
+      return true;
+    }
+
+    // Check if the actor has moved significantly from the last path endpoint
+    if (this.pathPoints.length > 0) {
+      const lastPathPoint = this.pathPoints[this.pathPoints.length - 1];
+      const distanceFromPathEnd = lastPathPoint.distanceTo(actorPosition);
+
+      // Recalculate if actor moved more than 3 units from where we were heading
+      if (distanceFromPathEnd > 3.0) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Calculates and sets path to a target position using navigation server
+   */
+  private calculateAndSetPathToPosition(targetPosition: THREE.Vector3): void {
+    const owner = this.getActor();
+    if (!owner) {
+      console.warn('NpcMovementComponent: No owner actor found');
+      return;
+    }
+
+    // Get current position
+    const ownerPosition = new THREE.Vector3();
+    owner.rootComponent.getWorldPosition(ownerPosition);
+
+
+    if (!this.navigationServer) {
+      console.warn('NpcMovementComponent: No navigation server available, using direct path');
+      this.setPath([targetPosition], false);
+      return;
+    }
+
+    if (this.canUseNavigationServer()) {
+      // Use navigation server - find closest point on navmesh if target is not on it
+      let pathTarget = targetPosition.clone();
+      const wasTargetOnNavmesh = this.navigationServer.isPointOnNavigationMesh(targetPosition);
+      if (!wasTargetOnNavmesh) {
+        pathTarget = this.navigationServer.getClosestPointOnNavigationMesh(targetPosition);
+      }
+
+      // Calculate path using navigation server
+      const pathPoints = this.navigationServer.calculatePath(ownerPosition, pathTarget);
+      this.setPath(pathPoints, false);
+    } else {
+      // Direct movement without navigation
+      this.setPath([targetPosition], false);
+    }
+  }
+
+  /**
+   * Initializes debug visualization objects
+   */
+  private initializeDebugVisualization(): void {
+    if (!this.npcOptions.debugVisualization?.enabled) return;
+
+    const world = this.getWorld();
+    if (!world) return;
+
+    // Create debug group
+    this.debugGroup = new THREE.Group();
+    this.debugGroup.name = `NPC_Debug_${this.getActor()?.uuid ?? 'unknown'}`;
+    world.scene.add(this.debugGroup);
+
+    // Create path line
+    const pathGeometry = new THREE.BufferGeometry();
+    const pathMaterial = new THREE.LineBasicMaterial({
+      color: this.npcOptions.debugVisualization.pathColor ?? 0x00ff00,
+      linewidth: this.npcOptions.debugVisualization.lineWidth ?? 2
+    });
+    this.pathLine = new THREE.Line(pathGeometry, pathMaterial);
+    this.pathLine.name = 'NPC_Path_Line';
+    this.debugGroup.add(this.pathLine);
+
+    // Create target sphere
+    if (this.npcOptions.debugVisualization.showWaypoints) {
+      const targetGeometry = new THREE.SphereGeometry(
+        this.npcOptions.debugVisualization.waypointSize ?? 0.5,
+        8, 6
+      );
+      const targetMaterial = new THREE.MeshBasicMaterial({
+        color: this.npcOptions.debugVisualization.targetColor ?? 0xff0000,
+        transparent: true,
+        opacity: 0.8
+      });
+      this.targetSphere = new THREE.Mesh(targetGeometry, targetMaterial);
+      this.targetSphere.name = 'NPC_Target_Sphere';
+      this.debugGroup.add(this.targetSphere);
+    }
+
+    // Disable raycasting for all debug objects
+    this.debugGroup.traverse((child) => {
+      child.raycast = () => { };
+    });
+  }
+
+  /**
+   * Cleans up debug visualization objects
+   */
+  private cleanupDebugVisualization(): void {
+    if (this.debugGroup) {
+      this.debugGroup.removeFromParent();
+      this.debugGroup = null;
+    }
+    this.pathLine = null;
+    this.waypointSpheres.forEach(sphere => sphere.geometry.dispose());
+    this.waypointSpheres = [];
+    if (this.targetSphere) {
+      this.targetSphere.geometry.dispose();
+      this.targetSphere = null;
+    }
+  }
+
+  /**
+   * Updates debug visualization based on current path and target
+   */
+  private updateDebugVisualization(): void {
+    if (!this.npcOptions.debugVisualization?.enabled || !this.debugGroup) return;
+
+    const owner = this.getActor();
+    if (!owner) return;
+
+    // Update path line
+    if (this.pathLine && this.pathPoints.length > 0) {
+      const points: THREE.Vector3[] = [];
+
+      // Add current position as start point
+      const currentPos = new THREE.Vector3();
+      owner.rootComponent.getWorldPosition(currentPos);
+      points.push(currentPos);
+
+      // Add all path points
+      points.push(...this.pathPoints);
+
+      // Dispose old geometry and create new one to avoid buffer size issues
+      this.pathLine.geometry.dispose();
+      this.pathLine.geometry = new THREE.BufferGeometry().setFromPoints(points);
+      this.pathLine.visible = true;
+    } else if (this.pathLine) {
+      this.pathLine.visible = false;
+    }
+
+    // Update target sphere
+    if (this.targetSphere && this.targetPosition) {
+      this.targetSphere.position.copy(this.targetPosition);
+      this.targetSphere.visible = true;
+    } else if (this.targetSphere) {
+      this.targetSphere.visible = false;
+    }
+
+    // Update waypoint spheres
+    this.updateWaypointSpheres();
+  }
+
+  /**
+   * Updates waypoint spheres for path visualization
+   */
+  private updateWaypointSpheres(): void {
+    if (!this.npcOptions.debugVisualization?.enabled ||
+      !this.npcOptions.debugVisualization.showWaypoints ||
+      !this.debugGroup) return;
+
+    // Remove existing waypoint spheres
+    this.waypointSpheres.forEach(sphere => {
+      this.debugGroup!.remove(sphere);
+      sphere.geometry.dispose();
+    });
+    this.waypointSpheres = [];
+
+    // Create new waypoint spheres
+    this.pathPoints.forEach((point, index) => {
+      const geometry = new THREE.SphereGeometry(
+        (this.npcOptions.debugVisualization!.waypointSize ?? 0.5) * 0.7,
+        6, 4
+      );
+      const material = new THREE.MeshBasicMaterial({
+        color: 0x00ffff,
+        transparent: true,
+        opacity: 0.6
+      });
+      const sphere = new THREE.Mesh(geometry, material);
+      sphere.position.copy(point);
+      sphere.name = `NPC_Waypoint_${index}`;
+      sphere.raycast = () => { }; // Disable raycasting
+
+      this.debugGroup!.add(sphere);
+      this.waypointSpheres.push(sphere);
+    });
+  }
+
+  /**
+   * Gets the current debug visualization enabled state
+   */
+  public isDebugVisualizationEnabled(): boolean {
+    return this.npcOptions.debugVisualization?.enabled ?? false;
+  }
+
+  /**
+   * Enables or disables debug visualization
+   */
+  public setDebugVisualizationEnabled(enabled: boolean): void {
+    this.npcOptions.debugVisualization ??= {
+      enabled: false,
+      pathColor: 0x00ff00,
+      targetColor: 0xff0000,
+      lineWidth: 2,
+      showWaypoints: true,
+      waypointSize: 0.5
+    };
+
+    this.npcOptions.debugVisualization.enabled = enabled;
+
+    if (enabled && !this.debugGroup) {
+      this.initializeDebugVisualization();
+    } else if (!enabled && this.debugGroup) {
+      this.cleanupDebugVisualization();
+    }
+  }
+
+  //====================================================================================================
+  // Editor Functions
+  //====================================================================================================
+
+  public override getEditorClassIcon(): string | null {
+    return 'Icon_NPC';
+  }
+
+}