@hytopia.com/examples 1.0.45 → 1.0.48

package/entity-controller/MyEntityController.ts

@@ -5,6 +5,8 @@ import {
   CoefficientCombineRule,
   CollisionGroup,
   Entity,
+  EntityEvent,
+  ErrorHandler,
   PlayerEntity,
   BlockType,
 } from 'hytopia';
@@ -12,99 +14,305 @@ import {
 import type {
   PlayerInput,
   PlayerCameraOrientation,
+  Vector3Like,
 } from 'hytopia';
 
 /** Options for creating a MyEntityController instance. @public */
 export interface MyEntityControllerOptions {
-  /** The upward velocity applied to the entity when it jumps. */
-  jumpVelocity?: number;
-
-  /** The normalized horizontal velocity applied to the entity when it runs. */
-  runVelocity?: number;
+  /** Whether to apply directional rotations to the entity while moving, defaults to true. */
+  applyDirectionalMovementRotations?: boolean;
 
-  /** The normalized horizontal velocity applied to the entity when it walks. */
-  walkVelocity?: number;
+  /** Whether to automatically cancel left click input after first processed tick, defaults to true. */
+  autoCancelMouseLeftClick?: boolean;
 
   /** A function allowing custom logic to determine if the entity can jump. */
   canJump?: () => boolean;
 
+  /** A function allowing custom logic to determine if the entity can run. */
+  canRun?: () => boolean;
+
+  /** A function allowing custom logic to determine if the entity can swim. */
+  canSwim?: () => boolean;
+  
   /** A function allowing custom logic to determine if the entity can walk. */
   canWalk?: () => boolean;
 
-  /** A function allowing custom logic to determine if the entity can run. */
-  canRun?: () => boolean;
-}
+  /** Whether to face forward when the entity stops moving. */
+  faceForwardOnStop?: boolean;
+
+  /** Overrides the animation(s) that will play when the entity is idle. */
+  idleLoopedAnimations?: string[];
+
+  /** Overrides the animation(s) that will play when the entity interacts (left click) */
+  interactOneshotAnimations?: string[];
+
+  /** Overrides the animation(s) that will play when the entity is jumping. */
+  jumpOneshotAnimations?: string[];
+
+  /** Overrides the animation(s) that will play when the entity lands with a high velocity. */
+  jumpLandHeavyOneshotAnimations?: string[];
+  
+  /** Overrides the animation(s) that will play when the entity lands after jumping or being airborne. */
+  jumpLandLightOneshotAnimations?: string[];
 
-/**
- * A custom entity controller implementation.
- * 
- * @remarks
- * This class extends {@link BaseEntityController}
- * and implements the default movement logic for a
- * entity. 
- * 
- * @public
- */
-export default class MyEntityController extends BaseEntityController {
   /** The upward velocity applied to the entity when it jumps. */
-  public jumpVelocity: number = 10;
+  jumpVelocity?: number;
 
   /** The normalized horizontal velocity applied to the entity when it runs. */
-  public runVelocity: number = 8;
+  runVelocity?: number;
+
+  /** Overrides the animation(s) that will play when the entity is running. */
+  runLoopedAnimations?: string[];
+
+  /** Whether the entity sticks to platforms, defaults to true. */
+  sticksToPlatforms?: boolean;
+
+  /** The normalized horizontal velocity applied to the entity when it swims fast (equivalent to running). */
+  swimFastVelocity?: number;
+
+  /** The gravity modifier applied to the entity when swimming. */
+  swimGravity?: number;
+
+  /** The maximum downward velocity that the entity can reach when affected by gravity while swimming. */
+  swimMaxGravityVelocity?: number;
+
+  /** The looped animation(s) that will play when the entity is swimming in any direction. */
+  swimLoopedAnimations?: string[];
+
+  /** The looped animation(s) that will play when the entity is not moving while swimming. */
+  swimIdleLoopedAnimations?: string[];
+
+  /** The normalized horizontal velocity applied to the entity when it swims slowly (equivalent to walking). */
+  swimSlowVelocity?: number;
+
+  /** The upward velocity applied to the entity when swimming. */
+  swimUpwardVelocity?: number;
+
+  /** Overrides the animation(s) that will play when the entity is walking. */
+  walkLoopedAnimations?: string[];
 
   /** The normalized horizontal velocity applied to the entity when it walks. */
-  public walkVelocity: number = 4;
+  walkVelocity?: number;
+}
+
+export default class MyEntityController extends BaseEntityController {
+  // These constants are based on a model scale of 1, and will scale relative to the entity.modelScale
+  private static readonly BASE_ENTITY_HEIGHT = 1.5;
+  private static readonly GROUND_SENSOR_HEIGHT_SCALE = 0.125;
+  private static readonly GROUND_SENSOR_RADIUS_SCALE = 0.23;
+  private static readonly JUMP_LAND_HEAVY_VELOCITY_THRESHOLD = -12;
+  private static readonly WALL_COLLIDER_HEIGHT_SCALE = 0.33;
+  private static readonly WALL_COLLIDER_RADIUS_SCALE = 0.40;
+
+  // Movement rotation lookup (static to avoid per-tick allocation)
+  private static readonly MOVEMENT_ROTATIONS: Record<string, number> = {
+    'wa': Math.PI / 4,
+    'wd': -Math.PI / 4,
+    'sa': Math.PI - Math.PI / 4,
+    'sd': Math.PI + Math.PI / 4,
+    's': Math.PI,
+    'asd': Math.PI, // Special case for a+s+d without w
+    'a': Math.PI / 2,
+    'd': -Math.PI / 2,
+  };
+
+  // Physics constants
+  private static readonly EXTERNAL_IMPULSE_DECAY_RATE = 0.253;
+  private static readonly SWIM_UPWARD_COOLDOWN_MS = 600;
+  private static readonly SWIMMING_DRAG_FACTOR = 0.05;
+  private static readonly WATER_ENTRY_SINKING_FACTOR = 0.8;
+  private static readonly WATER_ENTRY_SINKING_MS = 250;
+
+  /** Whether to apply directional rotations to the entity while moving, defaults to true. */
+  public applyDirectionalMovementRotations: boolean = true;
+
+  /** Whether to automatically cancel left click input after first processed tick, defaults to true. */
+  public autoCancelMouseLeftClick: boolean = true;
 
   /**
-   * A function allowing custom logic to determine if the entity can walk.
-   * @param myEntityController - The entity controller instance.
-   * @returns Whether the entity of the entity controller can walk.
+   * A function allowing custom logic to determine if the entity can jump.
+   * @param controller - The default player entity controller instance.
+   * @returns Whether the entity of the entity controller can jump.
    */
-  public canWalk: (myEntityController: MyEntityController) => boolean = () => true;
+  public canJump: (controller: MyEntityController) => boolean = () => true;
 
   /**
    * A function allowing custom logic to determine if the entity can run.
-   * @param myEntityController - The entity controller instance.
+   * @param controller - The default player entity controller instance.
    * @returns Whether the entity of the entity controller can run.
    */
-  public canRun: (myEntityController: MyEntityController) => boolean = () => true;
+  public canRun: (controller: MyEntityController) => boolean = () => true;
 
   /**
-   * A function allowing custom logic to determine if the entity can jump.
-   * @param myEntityController - The entity controller instance.
-   * @returns Whether the entity of the entity controller can jump.
+   * A function allowing custom logic to determine if the entity can swim.
+   * @param controller - The default player entity controller instance.
+   * @returns Whether the entity of the entity controller can swim.
+   */
+  public canSwim: (controller: MyEntityController) => boolean = () => true;
+  
+  /**
+   * A function allowing custom logic to determine if the entity can walk.
+   * @param controller - The default player entity controller instance.
+   * @returns Whether the entity of the entity controller can walk.
    */
-  public canJump: (myEntityController: MyEntityController) => boolean = () => true;
+  public canWalk: (controller: MyEntityController) => boolean = () => true;
+
+  /** Whether to face forward when the entity stops moving. */
+  public faceForwardOnStop: boolean = true;
+
+  /** The looped animation(s) that will play when the entity is idle. */
+  public idleLoopedAnimations: string[] = [ 'idle-upper', 'idle-lower' ];
+
+  /** The oneshot animation(s) that will play when the entity interacts (left click) */
+  public interactOneshotAnimations: string[] = [ 'simple-interact' ];
+
+  /** The oneshot animation(s) that will play when the entity lands with a high velocity. */
+  public jumpLandHeavyOneshotAnimations: string[] = [ 'jump-post-heavy' ];
+
+  /** The oneshot animation(s) that will play when the entity lands after jumping or being airborne. */
+  public jumpLandLightOneshotAnimations: string[] = [ 'jump-post-light' ];
+
+  /** The oneshot animation(s) that will play when the entity is jumping. */
+  public jumpOneshotAnimations: string[] = [ 'jump-loop' ];
+
+  /** The upward velocity applied to the entity when it jumps. */
+  public jumpVelocity: number = 10;
+
+  /** The looped animation(s) that will play when the entity is running. */
+  public runLoopedAnimations: string[] = [ 'run-upper', 'run-lower' ];
+
+  /** The normalized horizontal velocity applied to the entity when it runs. */
+  public runVelocity: number = 8;
+
+  /** Whether the entity sticks to platforms. */
+  public sticksToPlatforms: boolean = true;
+
+  /** The normalized horizontal velocity applied to the entity when it swims fast (equivalent to running). */
+  public swimFastVelocity: number = 5;
+
+  /** The gravity modifier applied to the entity when swimming. */
+  public swimGravity: number = 0;
+
+  /** The looped animation(s) that will play when the entity is not moving while swimming. */
+  public swimIdleLoopedAnimations: string[] = [ 'swim-idle' ];
+
+  /** The looped animation(s) that will play when the entity is swimming in any direction. */
+  public swimLoopedAnimations: string[] = [ 'swim-forward' ];
+
+  /** The maximum downward velocity that the entity can reach when affected by gravity while swimming. */
+  public swimMaxGravityVelocity: number = -1;
+
+  /** The normalized horizontal velocity applied to the entity when it swims slowly (equivalent to walking). */
+  public swimSlowVelocity: number = 3;
+
+  /** The upward velocity applied to the entity when swimming. */
+  public swimUpwardVelocity: number = 2;
+
+  /** The looped animation(s) that will play when the entity is walking. */
+  public walkLoopedAnimations: string[] = [ 'walk-upper', 'walk-lower' ];
+
+  /** The normalized horizontal velocity applied to the entity when it walks. */
+  public walkVelocity: number = 4;
 
   /** @internal */
-  private _stepAudio: Audio | undefined;
+  private readonly _externalVelocity = { x: 0, y: 0, z: 0 };
+
+  /** @internal */
+  private _magnitudeYTracker: number = 0;
 
   /** @internal */
   private _groundContactCount: number = 0;
 
+  /** @internal */
+  private _internalApplyImpulse: (impulse: Vector3Like) => void = () => {};
+
+  /** @internal */
+  private _isActivelyMoving: boolean = false;
+
+  /** @internal */
+  private _isFullySubmerged: boolean = false;
+
+  /** @internal */
+  private _justSubmergedUntil: number = 0;
+
+  /** @internal */
+  private _liquidContactCount: number = 0;
+
   /** @internal */
   private _platform: Entity | undefined;
 
+  /** @internal - Reusable vector for impulse calculation to avoid per-tick allocation */
+  private readonly _reusableImpulse = { x: 0, y: 0, z: 0 };
+
+  /** @internal - Reusable vector for platform velocity fallback to avoid per-tick allocation */
+  private readonly _reusablePlatformVelocity = { x: 0, y: 0, z: 0 };
+
+  /** @internal - Reusable vector for target velocities to avoid per-tick allocation */
+  private readonly _reusableTargetVelocities = { x: 0, y: 0, z: 0 };
+
+  /** @internal - Reusable vector for velocity clamping to avoid per-tick allocation */
+  private readonly _reusableVelocityClamp = { x: 0, y: 0, z: 0 };
+
+  /** @internal */
+  private _stepAudio: Audio | undefined;
+
+  /** @internal */
+  private _swimUpwardCooldownAt: number = 0;
+
   /**
    * @param options - Options for the controller.
    */
   public constructor(options: MyEntityControllerOptions = {}) {
     super();
 
+    // Basic behavior options
+    this.applyDirectionalMovementRotations = options.applyDirectionalMovementRotations ?? this.applyDirectionalMovementRotations;
+    this.autoCancelMouseLeftClick = options.autoCancelMouseLeftClick ?? this.autoCancelMouseLeftClick;
+    this.faceForwardOnStop = options.faceForwardOnStop ?? this.faceForwardOnStop;
+    this.sticksToPlatforms = options.sticksToPlatforms ?? this.sticksToPlatforms;
+
+    // Capability functions
+    this.canJump = options.canJump ?? this.canJump;
+    this.canRun = options.canRun ?? this.canRun;
+    this.canSwim = options.canSwim ?? this.canSwim;
+    this.canWalk = options.canWalk ?? this.canWalk;
+
+    // Movement velocities
     this.jumpVelocity = options.jumpVelocity ?? this.jumpVelocity;
     this.runVelocity = options.runVelocity ?? this.runVelocity;
     this.walkVelocity = options.walkVelocity ?? this.walkVelocity;
-    this.canWalk = options.canWalk ?? this.canWalk;
-    this.canRun = options.canRun ?? this.canRun;
-    this.canJump = options.canJump ?? this.canJump;
+    this.swimFastVelocity = options.swimFastVelocity ?? this.swimFastVelocity;
+    this.swimSlowVelocity = options.swimSlowVelocity ?? this.swimSlowVelocity;
+    this.swimUpwardVelocity = options.swimUpwardVelocity ?? this.swimUpwardVelocity;
+
+    // Swimming physics
+    this.swimGravity = options.swimGravity ?? this.swimGravity;
+    this.swimMaxGravityVelocity = options.swimMaxGravityVelocity ?? this.swimMaxGravityVelocity;
+
+    // Animation overrides
+    this.idleLoopedAnimations = options.idleLoopedAnimations ?? this.idleLoopedAnimations;
+    this.interactOneshotAnimations = options.interactOneshotAnimations ?? this.interactOneshotAnimations;
+    this.jumpOneshotAnimations = options.jumpOneshotAnimations ?? this.jumpOneshotAnimations;
+    this.jumpLandHeavyOneshotAnimations = options.jumpLandHeavyOneshotAnimations ?? this.jumpLandHeavyOneshotAnimations;
+    this.jumpLandLightOneshotAnimations = options.jumpLandLightOneshotAnimations ?? this.jumpLandLightOneshotAnimations;
+    this.runLoopedAnimations = options.runLoopedAnimations ?? this.runLoopedAnimations;
+    this.swimLoopedAnimations = options.swimLoopedAnimations ?? this.swimLoopedAnimations;
+    this.swimIdleLoopedAnimations = options.swimIdleLoopedAnimations ?? this.swimIdleLoopedAnimations;
+    this.walkLoopedAnimations = options.walkLoopedAnimations ?? this.walkLoopedAnimations;
   }
 
+  /** Whether the entity is moving from player inputs. */
+  public get isActivelyMoving(): boolean { return this._isActivelyMoving; }
+
   /** Whether the entity is grounded. */
   public get isGrounded(): boolean { return this._groundContactCount > 0; }
 
   /** Whether the entity is on a platform, a platform is any entity with a kinematic rigid body. */
   public get isOnPlatform(): boolean { return !!this._platform; }
 
+  /** Whether the entity is swimming, this is determined by if the entity is in a liquid block. */
+  public get isSwimming(): boolean { return this._liquidContactCount > 0; }
+
   /** The platform the entity is on, if any. */
   public get platform(): Entity | undefined { return this._platform; }
 
@@ -112,54 +320,111 @@ export default class MyEntityController extends BaseEntityController {
    * Called when the controller is attached to an entity.
    * @param entity - The entity to attach the controller to.
    */
-  public attach(entity: Entity) {
+  public override attach(entity: Entity) {
+    super.attach(entity);
+   
+    // Alter applyImpulse to handle external velocities within internal movement velocity conflicts.
+    this._internalApplyImpulse = entity.applyImpulse.bind(entity);
+    entity.applyImpulse = (impulse: Vector3Like) => {
+      // Convert impulses to velocity (impulse = mass * velocity)
+      const mass = entity.mass || 1;
+      this._externalVelocity.x += impulse.x / mass;
+      this._externalVelocity.y += impulse.y / mass;
+      this._externalVelocity.z += impulse.z / mass;
+    };
+
     this._stepAudio = new Audio({
       uri: 'audio/sfx/step/stone/stone-step-04.mp3',
       loop: true,
       volume: 0.1,
+      referenceDistance: 2,
+      cutoffDistance: 15,
       attachedToEntity: entity,
     });
 
+    entity.setCcdEnabled(true);
     entity.lockAllRotations(); // prevent physics from applying rotation to the entity, we can still explicitly set it.
-  };
+    
+    // Handle swimming when in contact with a liquid block
+    entity.on(EntityEvent.BLOCK_COLLISION, ({ blockType, started }) => {
+      if (!blockType.isLiquid || !this.canSwim(this)) {
+        return;
+      }
+
+      // Slow the linear velocity of the entity when 
+      // first entering the liquid to feel more natural
+      if (this._liquidContactCount <= 0 && started) {
+        const currentLinearVelocity = entity.linearVelocity;
+        entity.setLinearVelocity({
+          x: currentLinearVelocity.x * this.swimGravity,
+          y: currentLinearVelocity.y * this.swimGravity,
+          z: currentLinearVelocity.z * this.swimGravity,
+        });
+      }
+
+      this._liquidContactCount += started ? 1 : -1;
+
+      if (this._liquidContactCount > 0) {
+        entity.setGravityScale(this.swimGravity);
+        entity.stopAllModelLoopedAnimations(this.swimLoopedAnimations);
+        this._swimUpwardCooldownAt = performance.now() + MyEntityController.SWIM_UPWARD_COOLDOWN_MS;
+      } else {
+        entity.setGravityScale(1);
+        entity.stopModelAnimations(this.swimLoopedAnimations);
+      }
+    });
+  }
 
   /**
    * Called when the controlled entity is spawned.
-   * In MyEntityController, this function is used to create
+   * In DefaultPlayerEntityController, this function is used to create
    * the colliders for the entity for wall and ground detection.
    * @param entity - The entity that is spawned.
    */
-  public spawn(entity: Entity) {
+  public spawn(entity: Entity): void {
     if (!entity.isSpawned) {
-      throw new Error('MyEntityController.createColliders(): Entity is not spawned!');
+      return ErrorHandler.error('MyEntityController.spawn(): Entity is not spawned!');
     }
 
     // Ground sensor
     entity.createAndAddChildCollider({
       shape: ColliderShape.CYLINDER,
-      radius: 0.23,
-      halfHeight: 0.125,
+      radius: MyEntityController.GROUND_SENSOR_RADIUS_SCALE * (entity.height / MyEntityController.BASE_ENTITY_HEIGHT),
+      halfHeight: MyEntityController.GROUND_SENSOR_HEIGHT_SCALE * (entity.height / MyEntityController.BASE_ENTITY_HEIGHT),
       collisionGroups: {
         belongsTo: [ CollisionGroup.ENTITY_SENSOR ],
-        collidesWith: [ CollisionGroup.BLOCK, CollisionGroup.ENTITY ],
+        collidesWith: [ CollisionGroup.BLOCK, CollisionGroup.ENTITY, CollisionGroup.ENVIRONMENT_ENTITY ],
       },
       isSensor: true,
-      relativePosition: { x: 0, y: -0.75, z: 0 },
+      relativePosition: { x: 0, y: -entity.height / 2, z: 0 },
       tag: 'groundSensor',
       onCollision: (_other: BlockType | Entity, started: boolean) => {
+        if (!entity.isSpawned) { return; }
+        
         // Ground contact
-        this._groundContactCount += started ? 1 : -1;
+        if (!(_other instanceof BlockType) || !_other.isLiquid) {
+          // Landing detection: check before updating ground count
+          if (started && this._groundContactCount === 0 && entity.linearVelocity.y < -1) {
+            if (entity.linearVelocity.y < MyEntityController.JUMP_LAND_HEAVY_VELOCITY_THRESHOLD) {
+              entity.startModelOneshotAnimations(this.jumpLandHeavyOneshotAnimations);
+            } else {
+              entity.startModelOneshotAnimations(this.jumpLandLightOneshotAnimations);
+            }
+          }
+
+          this._groundContactCount += started ? 1 : -1;
+        }
   
-        if (!this._groundContactCount) {
-          entity.startModelOneshotAnimations([ 'jump_loop' ]);
+        if (!this._groundContactCount && !this.isSwimming) {
+          entity.startModelOneshotAnimations(this.jumpOneshotAnimations);
         } else {
-          entity.stopModelAnimations([ 'jump_loop' ]);
+          entity.stopModelAnimations(this.jumpOneshotAnimations);
         }
 
         // Platform contact
-        if (!(_other instanceof Entity) || !_other.isKinematic) return;
+        if (!(_other instanceof Entity)) return;
         
-        if (started) {
+        if (started && this.sticksToPlatforms) {
           this._platform = _other;
         } else if (_other === this._platform && !started) {
           this._platform = undefined;
@@ -167,25 +432,26 @@ export default class MyEntityController extends BaseEntityController {
       },
     });
 
-
     // Wall collider
     entity.createAndAddChildCollider({
       shape: ColliderShape.CAPSULE,
-      halfHeight: 0.30,
-      radius: 0.37,
+      halfHeight: MyEntityController.WALL_COLLIDER_HEIGHT_SCALE * (entity.height / MyEntityController.BASE_ENTITY_HEIGHT),
+      radius: MyEntityController.WALL_COLLIDER_RADIUS_SCALE * (entity.height / MyEntityController.BASE_ENTITY_HEIGHT),
       collisionGroups: {
         belongsTo: [ CollisionGroup.ENTITY_SENSOR ],
-        collidesWith: [ CollisionGroup.BLOCK ],
+        collidesWith: [ CollisionGroup.BLOCK, CollisionGroup.ENTITY, CollisionGroup.ENVIRONMENT_ENTITY ],
       },
       friction: 0,
       frictionCombineRule: CoefficientCombineRule.Min,
       tag: 'wallCollider',
     });
-  };
+  }
 
   /**
    * Ticks the player movement for the entity controller,
-   * overriding the default implementation.
+   * overriding the default implementation. If the entity to tick
+   * is a child entity, only the event will be emitted but the default
+   * movement logic will not be applied.
    * 
    * @param entity - The entity to tick.
    * @param input - The current input state of the player.
@@ -196,128 +462,209 @@ export default class MyEntityController extends BaseEntityController {
     if (!entity.isSpawned || !entity.world) return;
 
     super.tickWithPlayerInput(entity, input, cameraOrientation, deltaTimeMs);
+    if (entity.parent) return;
 
-    const { w, a, s, d, sp, sh, ml } = input;
+    // Input and state setup
+    const { w, a, s, d, c, sp, sh, ml, jd } = input;
     const { yaw } = cameraOrientation;
     const currentVelocity = entity.linearVelocity;
-    const targetVelocities = { x: 0, y: 0, z: 0 };
-    const isRunning = sh;
-
-    // Temporary, animations
-    if (this.isGrounded && (w || a || s || d)) {
-      if (isRunning) {
-        const runAnimations = [ 'run_upper', 'run_lower' ];
-        entity.stopModelAnimations(Array.from(entity.modelLoopedAnimations).filter(v => !runAnimations.includes(v)));
-        entity.startModelLoopedAnimations(runAnimations);
-        this._stepAudio?.setPlaybackRate(0.81);
-      } else {
-        const walkAnimations = [ 'walk_upper', 'walk_lower' ];
-        entity.stopModelAnimations(Array.from(entity.modelLoopedAnimations).filter(v => !walkAnimations.includes(v)));
-        entity.startModelLoopedAnimations(walkAnimations);
-        this._stepAudio?.setPlaybackRate(0.55);
-      }
 
+    // Reset reusable target velocities
+    this._reusableTargetVelocities.x = 0;
+    this._reusableTargetVelocities.y = 0;
+    this._reusableTargetVelocities.z = 0;
+    
+    const hasJoystickInput = typeof jd === 'number';
+    this._isActivelyMoving = hasJoystickInput || !!(w || a || s || d);
+    const isFastMovement = sh;
+    const hasConflictingInputs = !hasJoystickInput && ((a && d && !w && !s) || (w && s && !a && !d));
+    const canMove = (isFastMovement && this.canRun(this)) || (!isFastMovement && this.canWalk(this));
+
+    // Update swimming state and handle water entry sinking
+    if (this.isSwimming && !this._isFullySubmerged) {
+      this._isFullySubmerged = true;
+      this._justSubmergedUntil = performance.now() + MyEntityController.WATER_ENTRY_SINKING_MS;
+    } else if (!this.isSwimming) {
+      this._isFullySubmerged = false;
+      this._justSubmergedUntil = 0;
+    }
+
+    // Handle movement animations and audio
+    if (this.isGrounded && !this.isSwimming && this._isActivelyMoving && !hasConflictingInputs && canMove) {
+      // Ground movement animations
+      const animations = isFastMovement ? this.runLoopedAnimations : this.walkLoopedAnimations;
+      entity.stopAllModelLoopedAnimations(animations);
+      entity.startModelLoopedAnimations(animations);
+      this._stepAudio?.setPlaybackRate(isFastMovement ? 0.75 : 0.51);
       this._stepAudio?.play(entity.world, !this._stepAudio?.isPlaying);
+    } else if (this._isFullySubmerged && this.canSwim(this)) {
+      this._stepAudio?.pause();
+      if (this._isActivelyMoving) {
+        entity.stopAllModelLoopedAnimations(this.swimLoopedAnimations);
+        entity.startModelLoopedAnimations(this.swimLoopedAnimations);
+      } else {
+        entity.stopAllModelLoopedAnimations(this.swimIdleLoopedAnimations);
+        entity.startModelLoopedAnimations(this.swimIdleLoopedAnimations);
+      }
     } else {
+      // Idle animations
       this._stepAudio?.pause();
-      const idleAnimations = [ 'idle_upper', 'idle_lower' ];
-      entity.stopModelAnimations(Array.from(entity.modelLoopedAnimations).filter(v => !idleAnimations.includes(v)));
-      entity.startModelLoopedAnimations(idleAnimations);
+      entity.stopAllModelLoopedAnimations(this.idleLoopedAnimations);
+      entity.startModelLoopedAnimations(this.idleLoopedAnimations);
     }
 
-    if (ml) {
-      entity.startModelOneshotAnimations([ 'simple_interact' ]);
-
-      // break a block
-      const ray = entity.world.simulation.raycast(
-        entity.position,
-        entity.player.camera.facingDirection,
-        10,
-        { filterExcludeRigidBody: entity.rawRigidBody },
-      );
-
-      if (ray?.hitBlock) {
-        // Remove the block
-        entity.world.chunkLattice.setBlock(ray.hitBlock.globalCoordinate, 0);
+    // Calculate movement rotation for character facing (avoid string concatenation)
+    let movementDiagonalRotation: number | undefined;
+    if (this.applyDirectionalMovementRotations && canMove) {
+      if (hasJoystickInput) {
+        // Joystick: face the exact joystick direction
+        movementDiagonalRotation = jd;
+      } else {
+        // WASD: use discrete directional rotations
+        if (w && a && !d && !s) movementDiagonalRotation = MyEntityController.MOVEMENT_ROTATIONS.wa;
+        else if (w && d && !a && !s) movementDiagonalRotation = MyEntityController.MOVEMENT_ROTATIONS.wd;
+        else if (s && a && !w && !d) movementDiagonalRotation = MyEntityController.MOVEMENT_ROTATIONS.sa;
+        else if (s && d && !w && !a) movementDiagonalRotation = MyEntityController.MOVEMENT_ROTATIONS.sd;
+        else if ((s && !w && !a && !d) || (a && s && d && !w)) movementDiagonalRotation = MyEntityController.MOVEMENT_ROTATIONS.s;
+        else if (a && !w && !s && !d) movementDiagonalRotation = MyEntityController.MOVEMENT_ROTATIONS.a;
+        else if (d && !w && !a && !s) movementDiagonalRotation = MyEntityController.MOVEMENT_ROTATIONS.d;
       }
-
-      input.ml = false;
     }
 
-    // Calculate target horizontal velocities (run/walk)
-    if ((isRunning && this.canRun(this)) || (!isRunning && this.canWalk(this))) {
-      const velocity = isRunning ? this.runVelocity : this.walkVelocity;
+    // Handle interaction input
+    if (ml) {
+      entity.startModelOneshotAnimations(this.interactOneshotAnimations);
+      input.ml = !this.autoCancelMouseLeftClick;
+    }
 
-      if (w) {
-        targetVelocities.x -= velocity * Math.sin(yaw);
-        targetVelocities.z -= velocity * Math.cos(yaw);
-      }
-  
-      if (s) {
-        targetVelocities.x += velocity * Math.sin(yaw);
-        targetVelocities.z += velocity * Math.cos(yaw);
+    // Calculate horizontal movement velocities
+    if (canMove) {
+      const velocity = !this.isSwimming 
+        ? isFastMovement ? this.runVelocity : this.walkVelocity
+        : isFastMovement ? this.swimFastVelocity : this.swimSlowVelocity;
+
+      if (hasJoystickInput) {
+        // Joystick movement: exact direction relative to camera (jd: 0=forward)
+        const movementAngle = yaw + jd;
+        this._reusableTargetVelocities.x = -velocity * Math.sin(movementAngle);
+        this._reusableTargetVelocities.z = -velocity * Math.cos(movementAngle);
+      } else {
+        // WASD movement: discrete directions relative to camera
+        const sinYaw = Math.sin(yaw);
+        const cosYaw = Math.cos(yaw);
+
+        if (w) { this._reusableTargetVelocities.x -= velocity * sinYaw; this._reusableTargetVelocities.z -= velocity * cosYaw; }
+        if (s) { this._reusableTargetVelocities.x += velocity * sinYaw; this._reusableTargetVelocities.z += velocity * cosYaw; }
+        if (a) { this._reusableTargetVelocities.x -= velocity * cosYaw; this._reusableTargetVelocities.z += velocity * sinYaw; }
+        if (d) { this._reusableTargetVelocities.x += velocity * cosYaw; this._reusableTargetVelocities.z -= velocity * sinYaw; }
+
+        // Normalize diagonal movement to prevent speed boost
+        const horizontalSpeed = Math.sqrt(this._reusableTargetVelocities.x * this._reusableTargetVelocities.x + this._reusableTargetVelocities.z * this._reusableTargetVelocities.z);
+        if (horizontalSpeed > velocity) {
+          const factor = velocity / horizontalSpeed;
+          this._reusableTargetVelocities.x *= factor;
+          this._reusableTargetVelocities.z *= factor;
+        }
       }
-      
-      if (a) {
-        targetVelocities.x -= velocity * Math.cos(yaw);
-        targetVelocities.z += velocity * Math.sin(yaw);
+    }
+
+    // Handle swimming physics and vertical movement
+    if (this.isSwimming) {
+      // Clamp swimming velocities (avoid object spread allocation)
+      if (currentVelocity.y < this.swimMaxGravityVelocity) {
+        this._reusableVelocityClamp.x = currentVelocity.x;
+        this._reusableVelocityClamp.y = this.swimMaxGravityVelocity;
+        this._reusableVelocityClamp.z = currentVelocity.z;
+        entity.setLinearVelocity(this._reusableVelocityClamp);
       }
-      
-      if (d) {
-        targetVelocities.x += velocity * Math.cos(yaw);
-        targetVelocities.z -= velocity * Math.sin(yaw);
+      if (currentVelocity.y > this.swimUpwardVelocity * 2) {
+        this._reusableVelocityClamp.x = currentVelocity.x;
+        this._reusableVelocityClamp.y = this.swimUpwardVelocity * 2;
+        this._reusableVelocityClamp.z = currentVelocity.z;
+        entity.setLinearVelocity(this._reusableVelocityClamp);
       }
 
-      // Normalize for diagonals
-      const length = Math.sqrt(targetVelocities.x * targetVelocities.x + targetVelocities.z * targetVelocities.z);
-      if (length > velocity) {
-        const factor = velocity / length;
-        targetVelocities.x *= factor;
-        targetVelocities.z *= factor;
+      // Handle diving and water entry sinking
+      if (c) {
+        this._reusableTargetVelocities.y = -this.swimUpwardVelocity;
+      } else if (performance.now() < this._justSubmergedUntil) {
+        this._reusableTargetVelocities.y = -this.swimUpwardVelocity * MyEntityController.WATER_ENTRY_SINKING_FACTOR;
+      } else if (!sp) {
+        this._reusableTargetVelocities.y = -currentVelocity.y * MyEntityController.SWIMMING_DRAG_FACTOR;
       }
     }
 
-    // Calculate target vertical velocity (jump)
+    // Handle jumping and swimming upward
     if (sp && this.canJump(this)) {
-      if (this.isGrounded && currentVelocity.y > -0.001 && currentVelocity.y <= 3) {
-        targetVelocities.y = this.jumpVelocity;
+      if (this.isGrounded && !this.isSwimming && currentVelocity.y > -0.001 && currentVelocity.y <= 3) {
+        this._reusableTargetVelocities.y = this.jumpVelocity;
+      } else if (this.isSwimming && performance.now() > this._swimUpwardCooldownAt) {
+        this._reusableTargetVelocities.y = this.swimUpwardVelocity;
       }
     }
 
-    // Apply impulse relative to target velocities, taking platform velocity into account
-    const platformVelocity = this._platform ? this._platform.linearVelocity : { x: 0, y: 0, z: 0 };
-    const deltaVelocities = {
-      x: targetVelocities.x - currentVelocity.x + platformVelocity.x,
-      y: targetVelocities.y + platformVelocity.y,
-      z: targetVelocities.z - currentVelocity.z + platformVelocity.z,
-    };
+    // Apply physics impulses (avoid platform velocity object allocation)
+    const platformVelocity = this._platform?.linearVelocity ?? this._reusablePlatformVelocity;
 
-    const hasExternalVelocity = 
-      Math.abs(currentVelocity.x) > this.runVelocity ||
-      Math.abs(currentVelocity.y) > this.jumpVelocity ||
-      Math.abs(currentVelocity.z) > this.runVelocity;
+    if (this._externalVelocity.y !== 0) {
+      this._magnitudeYTracker += this._externalVelocity.y;
+    }
+    
+    // Process external impulses if they exist
+    if (this._externalVelocity.x !== 0 || this._externalVelocity.y !== 0 || this._externalVelocity.z !== 0) {
+      // Only decay horizontal impulses when grounded (physics doesn't decay horizontal velocity in air)
+      if (this.isGrounded) {
+        // Apply decay to external impulses while preserving direction
+        const magnitude = Math.sqrt(
+          this._externalVelocity.x * this._externalVelocity.x + 
+          this._magnitudeYTracker * this._magnitudeYTracker +
+          this._externalVelocity.z * this._externalVelocity.z,
+        );
+        
+        if (magnitude > 0.01) {
+          // Decay the magnitude
+          const newMagnitude = Math.max(0, magnitude - MyEntityController.EXTERNAL_IMPULSE_DECAY_RATE);
+          const scale = newMagnitude / magnitude;
+          
+          // Apply the scale to preserve direction
+          this._externalVelocity.x *= scale;
+          this._magnitudeYTracker *= scale;  // Also scale the Y tracker
+          this._externalVelocity.z *= scale;
+        } else {
+          // Clear very small values
+          this._externalVelocity.x = 0;
+          this._externalVelocity.y = 0;
+          this._magnitudeYTracker = 0;  // Clear the Y tracker
+          this._externalVelocity.z = 0;
+        }
+      }
+    }
 
-    if (!hasExternalVelocity) { // allow external velocities to resolve, otherwise our deltas will cancel them out.
-      if (Object.values(deltaVelocities).some(v => v !== 0)) {
-        const mass = entity.mass;        
+    // Calculate total target velocity (player input + external + platform)
+    const deltaX = this._reusableTargetVelocities.x + this._externalVelocity.x - currentVelocity.x + platformVelocity.x;
+    const deltaY = this._reusableTargetVelocities.y + this._externalVelocity.y + platformVelocity.y;
+    const deltaZ = this._reusableTargetVelocities.z + this._externalVelocity.z - currentVelocity.z + platformVelocity.z;
 
-        entity.applyImpulse({ // multiply by mass for the impulse to result in applying the correct target velocity
-          x: deltaVelocities.x * mass,
-          y: deltaVelocities.y * mass,
-          z: deltaVelocities.z * mass,
-        });
-      }
+    this._externalVelocity.y = 0;
+
+    if (deltaX !== 0 || deltaY !== 0 || deltaZ !== 0) {
+      const mass = entity.mass;
+      this._reusableImpulse.x = deltaX * mass;
+      this._reusableImpulse.y = deltaY * mass;
+      this._reusableImpulse.z = deltaZ * mass;
+      this._internalApplyImpulse(this._reusableImpulse);
     }
 
-    // Apply rotation
-    if (yaw !== undefined) {
-      const halfYaw = yaw / 2;
+    // Apply character rotation
+    if (yaw !== undefined && (this.faceForwardOnStop || this.isActivelyMoving)) {
+      const finalYaw = movementDiagonalRotation !== undefined ? yaw + movementDiagonalRotation : yaw;
+      const halfFinalYaw = finalYaw * 0.5;
       
       entity.setRotation({
         x: 0,
-        y: Math.fround(Math.sin(halfYaw)),
+        y: Math.sin(halfFinalYaw),
         z: 0,
-        w: Math.fround(Math.cos(halfYaw)),
+        w: Math.cos(halfFinalYaw),
       });
     }
   }