@directivegames/genesys.js 3.1.24

package/src/components/movement/CharacterMovementComponent.ts

@@ -0,0 +1,446 @@
+/**
+ * CharacterMovementComponent handles first- or third-person walking controls.
+ *
+ * This class translates directional inputs into velocity changes using a
+ * configurable acceleration model and optional character controller physics. It
+ * supports look rotation with configurable pitch limitations, jumping,
+ * and different movement types that alter how camera inputs are interpreted.
+ * The component manages state needed for smooth acceleration, deceleration,
+ * and in-air movement when physics is active.
+ *
+ * Features:
+ * - Configurable pitch limitations (how far up/down you can look)
+ * - Unlimited yaw rotation (horizontal turning)
+ * - Accumulated rotation tracking to maintain pitch limits across frames
+ * - Support for both first-person and third-person camera modes
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Choose `FirstPerson` or `ThirdPerson` via the `movementType` option.
+ * - Set `minPitchAngle` and `maxPitchAngle` to limit vertical look range.
+ * - Set any pitch limit to `null` to disable that specific limitation.
+ * - Provide a `CharacterControllerOptions` if physics-based collision is
+ *   required.
+ * - Feed input values through `addForwardInput`, `addRightInput`, and look
+ *   methods every frame.
+ */
+import * as THREE from 'three';
+
+import { CHARACTER_HEIGHT, CHARACTER_JUMP_SPEED, CHARACTER_MASS, CHARACTER_MAX_SPEED } from '../../const.js';
+import { PhysicsMotionType } from '../../physics/PhysicsTypes.js';
+import { EngineClass } from '../../systems/ClassRegistry.js';
+import { MathHelpers } from '../../utils/MathHelpers.js';
+import { PrimitiveComponent } from '../PrimitiveComponent.js';
+
+import { BasePawnMovementComponent } from './BasePawnMovementComponent.js';
+
+import type { PawnInput } from './BasePawnMovementComponent.js';
+import type { CharacterControllerOptions } from '../../physics/PhysicsEngine.js';
+import type { SceneComponentOptions } from '../SceneComponent.js';
+
+/**
+ * The type of character movement to use
+ */
+export enum CharacterMovementType {
+  FirstPerson = 'firstPerson',
+  ThirdPerson = 'thirdPerson',
+  Custom = 'custom',
+}
+
+/**
+ * Configuration options for first person movement
+ */
+export interface CharacterMovementOptions extends SceneComponentOptions {
+  /** The type of character movement to use */
+  movementType: CharacterMovementType;
+  /** Movement speed in units per second */
+  maxSpeed: number;
+  /** damp lambda for acceleration */
+  accelerationLambda: number;
+  /** damp lambda for deceleration */
+  decelerationLambda: number;
+  /** Look right/left rotation speed in radians per second */
+  lookRightSpeed: number;
+  /** Look up/down rotation speed in radians per second */
+  lookUpSpeed: number;
+  /** Jump speed in units per second */
+  jumpSpeed: number;
+  /** Maximum number of jumps allowed in mid-air (0 = no mid-air jumps, 1 = double jump, etc.) */
+  maxMidAirJumps: number;
+  /** Acceleration lambda for mid-air movement when using the character controller */
+  midAirAccelerationLambda: number;
+  /** Deceleration lambda for mid-air movement when using the character controller */
+  midAirDecelerationLambda: number;
+  /** Character controller options, set null to disable character controller */
+  characterControllerOptions: CharacterControllerOptions | null;
+  /** Minimum pitch angle in radians (how far down you can look), set null for no limit */
+  minPitchAngle: number | null;
+  /** Maximum pitch angle in radians (how far up you can look), set null for no limit */
+  maxPitchAngle: number | null;
+  /** Whether to disable automatic camera updates */
+  disableCameraUpdate?: boolean;
+}
+
+/**
+ * Component that handles first-person movement for pawns
+ * Processes movement and rotation inputs and applies them to the pawn
+ */
+@EngineClass('CharacterMovementComponent')
+export class CharacterMovementComponent<TOptions extends CharacterMovementOptions = CharacterMovementOptions> extends BasePawnMovementComponent<TOptions> {
+
+  static override get DEFAULT_OPTIONS(): CharacterMovementOptions {
+    return {
+      ...BasePawnMovementComponent.DEFAULT_OPTIONS,
+      movementType: CharacterMovementType.FirstPerson,
+      maxSpeed: CHARACTER_MAX_SPEED,
+      accelerationLambda: 100,
+      decelerationLambda: 10,
+      midAirAccelerationLambda: 5,
+      midAirDecelerationLambda: 0.5,
+      lookRightSpeed: 0.05,
+      lookUpSpeed: 0.05,
+      jumpSpeed: CHARACTER_JUMP_SPEED,
+      maxMidAirJumps: 0,
+      characterControllerOptions: CharacterMovementComponent.DEFAULT_CHARACTER_CONTROLLER_OPTIONS,
+      minPitchAngle: THREE.MathUtils.degToRad(-90),
+      maxPitchAngle: THREE.MathUtils.degToRad(90),
+      disableCameraUpdate: false,
+    };
+  }
+
+  static get DEFAULT_CHARACTER_CONTROLLER_OPTIONS(): CharacterControllerOptions {
+    return {
+      offset: 0.01,
+      simulatedGravityScale: 5,
+      applyImpulsesToDynamicBodies: true,
+      characterMass: CHARACTER_MASS,
+      slideEnabled: true,
+      maxSlopeClimbAngle: Math.PI / 4,
+      minSlopeSlideAngle: Math.PI / 4,
+      snapToGroundDistance: 0.1,
+      autoStepConfig: {
+        maxHeight: CHARACTER_HEIGHT / 4,
+        minWidth: 0,
+        includeDynamicBodies: false,
+      }
+    };
+  }
+
+  protected hasCharacterController: boolean = false;
+  protected lastMotionTypeLogTime: number = 0;
+  protected isGrounded: boolean = false;
+  protected forwardVelocity: number = 0;
+  protected rightVelocity: number = 0;
+  protected verticalVelocity: number = 0;
+  protected jumpFrames: number = 0;
+  protected lastGroundedTime: number = 0;
+  protected coyoteTimeMs: number = 100; // 100ms grace period
+  protected jumpsUsed: number = 0;
+  protected camera: THREE.Camera | null | undefined = undefined;
+  protected teleportPosition: THREE.Vector3 | null = null;
+
+  /**
+     * Creates a new first person movement component
+     * @param options Configuration options for movement behavior
+     */
+  constructor(options: TOptions = CharacterMovementComponent.DEFAULT_OPTIONS as TOptions) {
+    super(options);
+  }
+
+  /**
+     * Called when the component starts playing
+     * Requests pointer lock for first-person camera control
+     */
+  public override beginPlay(): void {
+    super.beginPlay();
+    if (this.options.characterControllerOptions) {
+      this.hasCharacterController = this.getPhysicsEngine()?.createCharacterController(this, this.options.characterControllerOptions) ?? false;
+    }
+  }
+
+  /**
+     * Called when the component stops playing
+     * Exits pointer lock
+     */
+  public override endPlay(): void {
+    super.endPlay();
+    const owner = this.getActor();
+    owner?.getPlayerController()?.getInputManager()?.exitPointerLock();
+    this.getPhysicsEngine()?.removeCharacterController(this);
+  }
+
+  /**
+     * Jumps the pawn
+     */
+  public override jump(strength: number = 1): void {
+    if (this.canJump()) {
+      this.verticalVelocity = this.options.jumpSpeed * strength * this.jumpStrengthModifier;
+      this.jumpFrames = 0;
+
+      // Track mid-air jumps
+      if (!this.isGrounded) {
+        this.jumpsUsed++;
+      }
+    }
+  }
+
+  /**
+   * Checks if the character can jump, can be overridden to allow jumping in mid-air
+   * @returns True if the character can jump, false otherwise
+   */
+  protected canJump(): boolean {
+    // Can always jump when grounded
+    if (this.isGrounded) {
+      return true;
+    }
+
+    // Check if mid-air jumps are available
+    return this.jumpsUsed < this.options.maxMidAirJumps;
+  }
+
+  /**
+   * Sets the world transform of the character
+   * @param transform The transform to set
+   */
+  public override setPawnWorldTransform(transform: { position?: THREE.Vector3, rotation?: THREE.Euler, scale?: THREE.Vector3 }): void {
+    if (this.hasCharacterController) {
+      const owner = this.getActor()!;
+      const rootComponent = owner.rootComponent;
+      if (transform.rotation) {
+        rootComponent.rotation.copy(transform.rotation);
+      }
+      if (transform.scale) {
+        rootComponent.scale.copy(transform.scale);
+      }
+      if (transform.position) {
+        // TEMP hack: teleportation messes with the isGrounded (making it always false) so only use it when the difference is large enough
+        if (transform.position.distanceTo(rootComponent.position) > 0.1) {
+          this.teleportPosition = transform.position.clone();
+        } else {
+          rootComponent.position.copy(transform.position);
+        }
+      }
+
+    } else {
+      super.setPawnWorldTransform(transform);
+    }
+  }
+
+  /**
+     * Called after physics simulation each frame
+     * Processes movement and rotation inputs and applies them to the pawn
+     * @param deltaTime Time in seconds since the last frame
+     */
+  public override tickPostPhysics(deltaTime: number): void {
+    // This MUST be done in tickPostPhysics as in tickPrePhysics the component transform has not been synced to physics yet
+    super.tickPostPhysics(deltaTime);
+
+    const movementType = this.options.movementType;
+
+    const owner = this.getActor()!;
+    const rootComponent = owner.rootComponent;
+    const isMidAir = this.hasCharacterController && !this.isGrounded;
+    const accelerationLambda = isMidAir ? this.options.midAirAccelerationLambda : this.options.accelerationLambda;
+    const decelerationLambda = isMidAir ? this.options.midAirDecelerationLambda : this.options.decelerationLambda;
+    const maxSpeed = this.options.maxSpeed * this.speedModifier;
+
+    this.forwardVelocity = this.updateVelocity({
+      input: this.forwardInput,
+      maxSpeed,
+      currentSpeed: this.forwardVelocity,
+      accelerationLambda,
+      decelerationLambda,
+      deltaTime
+    });
+
+    this.rightVelocity = this.updateVelocity({
+      input: this.rightInput,
+      maxSpeed,
+      currentSpeed: this.rightVelocity,
+      accelerationLambda,
+      decelerationLambda,
+      deltaTime
+    });
+
+    const deltaPosition = new THREE.Vector3(0, 0, 0);
+    deltaPosition.add(owner.forwardDirection().multiplyScalar(this.forwardVelocity * deltaTime));
+    deltaPosition.add(owner.rightDirection().multiplyScalar(this.rightVelocity * deltaTime));
+
+    if (this.hasCharacterController && rootComponent instanceof PrimitiveComponent) {
+      const rootMotionType = rootComponent.getMotionType();
+      if (rootMotionType !== PhysicsMotionType.KinematicVelocityBased) {
+        const owner = this.getActor();
+        if (owner?.getPlayerController()) {
+          // when the pawn is not possessed its collision might be disabled and we don't want to spam the error below in that case
+          const now = Date.now();
+          if (now - this.lastMotionTypeLogTime >= 10000) { // 10 seconds
+            console.error(`${this.getPathName()}: Root component motion type should be "KinematicVelocityBased" when using character controller, current type is "${rootMotionType}"`);
+            this.lastMotionTypeLogTime = now;
+          }
+        }
+      }
+      // perform character controller movement with simulated gravity
+      const physicsEngine = this.getPhysicsEngine()!;
+      const gravityValue = physicsEngine.getOptions()!.gravity.y;
+      this.verticalVelocity += gravityValue * deltaTime * this.options.characterControllerOptions!.simulatedGravityScale;
+      deltaPosition.y += this.verticalVelocity * deltaTime;
+      // the body is moved in computeCharacterMovement so only need to get the position back
+      rootComponent.setPhysicsTransformUpdateFlags({
+        sendPosition: false,
+        sendRotation: false,
+        receivePosition: true,
+        receiveRotation: false,
+      });
+      if (this.teleportPosition) {
+        deltaPosition.copy(this.teleportPosition.clone().sub(rootComponent.position));
+      }
+
+      const { isGrounded } = physicsEngine.computeCharacterMovement(this, rootComponent, deltaPosition.toArray(), !!this.teleportPosition);
+      this.teleportPosition = null;
+
+      this.isGrounded = isGrounded;
+      if (this.isGrounded) {
+        this.lastGroundedTime = performance.now();
+        // Reset jump counter when landing
+        this.jumpsUsed = 0;
+      }
+
+      this.jumpFrames += 1;
+      // clear the vertical velocity when the character is grounded but only when it has jumped for a while
+      // this is a hack around the issue that sometimes the character is pulled immediately back to the ground after jumping because the
+      // isGrounded flag returned from the physics engine is not reliable...
+      if (this.isGrounded && this.jumpFrames >= 10) {
+        this.verticalVelocity = 0;
+      }
+    } else {
+      rootComponent.addWorldPosition(deltaPosition);
+    }
+
+    if (movementType !== CharacterMovementType.Custom) {
+      if (this.lookRightInput.value !== 0) {
+        const rotationAmount = this.calculateRotationAmount(this.lookRightInput, this.options.lookRightSpeed, deltaTime);
+        rootComponent.addWorldRotation(MathHelpers.makeRotation({ yaw: rotationAmount }));
+      }
+
+      if (this.lookUpInput.value !== 0) {
+        if (movementType === CharacterMovementType.FirstPerson) {
+          // implement pitch clamping
+          const currentPitch = new THREE.Euler().setFromQuaternion(rootComponent.quaternion, 'YZX').x;
+          const rotationAmount = this.calculateRotationAmount(this.lookUpInput, this.options.lookUpSpeed, deltaTime);
+          let newPitch = currentPitch + rotationAmount;
+          if (this.options.minPitchAngle !== null) {
+            newPitch = Math.max(newPitch, this.options.minPitchAngle);
+          }
+          if (this.options.maxPitchAngle !== null) {
+            newPitch = Math.min(newPitch, this.options.maxPitchAngle);
+          }
+          rootComponent.addLocalRotation(MathHelpers.makeRotation({ pitch: newPitch - currentPitch }));
+        }
+      }
+    }
+    this.updateCamera(deltaTime);
+  }
+
+  protected updateCamera(deltaTime: number): void {
+    if (this.options.disableCameraUpdate) {
+      return;
+    }
+
+    const rootComponent = this.getActor()!.rootComponent;
+    if (this.camera === undefined) {
+      this.camera = rootComponent.getComponent(THREE.Camera);
+    }
+    if (!this.camera) {
+      return;
+    }
+    if (this.options.movementType === CharacterMovementType.ThirdPerson) {
+      if (!this.camera.useAbsoluteRotation) {
+        const pitchDelta = this.calculateRotationAmount(this.lookUpInput, this.options.lookUpSpeed, deltaTime);
+        const newPitch = THREE.MathUtils.clamp(this.camera.rotation.x + pitchDelta, -Math.PI / 2, Math.PI / 2);
+        this.camera.rotation.x = newPitch;
+      }
+
+      if (!this.camera.useAbsolutePosition) {
+        const matrix = new THREE.Matrix4().makeRotationFromEuler(this.camera.rotation);
+        const cameraDistance = this.camera.position.length();
+        const newCameraPosition = new THREE.Vector3(0, 0, 1).applyMatrix4(matrix).multiplyScalar(cameraDistance);
+        this.camera.position.copy(newCameraPosition);
+      }
+    }
+  }
+
+  /**
+   * Get the grounded state of the character
+   * @returns The grounded state of the character
+   */
+  public getGrounded(): boolean {
+    return this.isGrounded || (performance.now() - this.lastGroundedTime < this.coyoteTimeMs);
+  }
+
+  /**
+   * Get the velocities of the character
+   * @returns The velocities of the character
+   */
+  public getVelocities(): { forward: number, right: number, vertical: number } {
+    return {
+      forward: this.forwardVelocity,
+      right: this.rightVelocity,
+      vertical: this.verticalVelocity,
+    };
+  }
+
+  /**
+   * Get the movement inputs for the character
+   * @returns The movement inputs for the character
+   */
+  public getMovementInputs(): { forward: number, right: number } {
+    return {
+      forward: this.forwardInput.value,
+      right: this.rightInput.value,
+    };
+  }
+
+  /**
+   * Get the jump state of the character
+   * @returns The jump state including jumps used and jumps remaining
+   */
+  public getJumpState(): { jumpsUsed: number, jumpsRemaining: number, canJump: boolean } {
+    return {
+      jumpsUsed: this.jumpsUsed,
+      jumpsRemaining: this.options.maxMidAirJumps - this.jumpsUsed,
+      canJump: this.canJump(),
+    };
+  }
+
+  //====================================================================================================
+
+  protected updateVelocity(param: { input: PawnInput, maxSpeed: number, currentSpeed: number, accelerationLambda: number, decelerationLambda: number, deltaTime: number }): number {
+    if (param.input.value !== 0) {
+      const target = THREE.MathUtils.clamp(param.input.value * param.maxSpeed, -param.maxSpeed, param.maxSpeed);
+      return THREE.MathUtils.damp(param.currentSpeed, target, param.accelerationLambda, param.deltaTime);
+    }
+    else {
+      return THREE.MathUtils.damp(param.currentSpeed, 0, param.decelerationLambda, param.deltaTime);
+    }
+  }
+
+  /**
+   * Calculates rotation amount based on input type and parameters
+   */
+  protected calculateRotationAmount(input: PawnInput, speed: number, deltaTime: number): number {
+    if (input.isAbsolute) {
+      // For absolute input (like accumulated mouse movement), apply directly
+      return input.value * speed;
+    } else {
+      // For speed-based input (like gamepad analog), apply with delta time
+      return input.value * speed * deltaTime;
+    }
+  }
+
+  //====================================================================================================
+  // Editor Functions
+  //====================================================================================================
+
+  public override getEditorClassIcon(): string | null {
+    return 'Icon_Character';
+  }
+}

package/src/components/movement/DirectionalCharacterMovementComponent.ts

@@ -0,0 +1,79 @@
+/**
+ * DirectionalCharacterMovementComponent provides constrained movement along a
+ * single axis for 2D-style gameplay.
+ *
+ * Built on CharacterMovementComponent, it restricts movement to either
+ * forward/backward or left/right direction while disabling look rotation. This
+ * is ideal for side-scrollers, platformers, or games where character movement
+ * should be constrained to specific axes. The component optionally supports
+ * auto-movement for characters that move continuously without input.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Use for 2D-style games, side-scrollers, or platformers.
+ * - Choose `ForwardBackward` or `LeftRight` via the `direction` option.
+ * - Enable `autoMove` for NPCs that should move continuously.
+ * - Look rotation is automatically disabled for focused gameplay.
+ */
+import { EngineClass } from '../../systems/ClassRegistry.js';
+
+import { CharacterMovementComponent, CharacterMovementType } from './CharacterMovementComponent.js';
+
+import type { CharacterMovementOptions } from './CharacterMovementComponent.js';
+
+export enum CharacterMovementDirection {
+  ForwardBackward = 'forwardBackward',
+  LeftRight = 'leftRight',
+}
+
+export interface DirectionalCharacterMovementOptions extends Omit<CharacterMovementOptions, 'movementType' | 'lookRightSpeed' | 'lookUpSpeed'> {
+  // movementType, lookRightSpeed, and lookUpSpeed are fixed and not user-configurable
+  direction: CharacterMovementDirection;
+  autoMove: boolean;
+}
+
+type CompleteOptions = DirectionalCharacterMovementOptions & CharacterMovementOptions;
+
+@EngineClass('DirectionalCharacterMovementComponent')
+// eslint-disable-next-line custom/constructor-type-consistency
+export class DirectionalCharacterMovementComponent extends CharacterMovementComponent<CompleteOptions> {
+  static override get DEFAULT_OPTIONS(): CompleteOptions {
+    return {
+      ...CharacterMovementComponent.DEFAULT_OPTIONS,
+      direction: CharacterMovementDirection.LeftRight,
+      autoMove: false,
+      midAirAccelerationLambda: 0,
+      midAirDecelerationLambda: 0,
+      // These are fixed and not user-configurable
+      movementType: CharacterMovementType.Custom,
+      lookRightSpeed: 0,
+      lookUpSpeed: 0,
+    };
+  }
+
+  constructor(options: DirectionalCharacterMovementOptions = DirectionalCharacterMovementComponent.DEFAULT_OPTIONS) {
+    super({
+      ...options,
+      // Force these values regardless of user input
+      movementType: CharacterMovementType.Custom,
+      lookRightSpeed: 0,
+      lookUpSpeed: 0,
+    });
+  }
+
+  public override tickPostPhysics(deltaTime: number): void {
+    if (this.options.direction === CharacterMovementDirection.ForwardBackward) {
+      // move forward and backward
+      this.addRightInput(0);
+      if (this.options.autoMove) {
+        this.addForwardInput(1);
+      }
+    } else {
+      // move left and right
+      this.addForwardInput(0);
+      if (this.options.autoMove) {
+        this.addRightInput(1);
+      }
+    }
+    super.tickPostPhysics(deltaTime);
+  }
+}