@directivegames/genesys.js 3.1.24

package/src/actors/PlayerController.ts

@@ -0,0 +1,646 @@
+/**
+ * PlayerController - actor that translates user input into pawn movement.
+ *
+ * Detailed explanation:
+ * - Reads keyboard, mouse, and gamepad events, applying sensitivity and pointer lock options.
+ * - Forwards movement axes and button presses to the currently possessed `Pawn` instance.
+ * - Exposes delegate hooks so games can intercept raw input or extend processing logic.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Spawn one per player and call `possess` with a pawn instance to begin controlling it.
+ * - Bind to delegates like `onKeyDown` when you need custom handling beyond the default movement.
+ * - Disable pointer lock with the `noPointerLock` option for menu-driven or top-down games.
+ */
+import * as THREE from 'three';
+
+import { EngineClass } from '../systems/ClassRegistry.js';
+import { ConsoleCommand } from '../systems/ConsoleManager.js';
+import { GamepadAxis, GamepadButton } from '../systems/InputManager.js';
+import { MouseButton } from '../systems/InputManager.js';
+import { VirtualJoystickIndex } from '../systems/InputManager.js';
+import { Delegate } from '../utils/Delegate.js';
+import { ensure } from '../utils/Utils.js';
+
+import { Actor } from './Actor.js';
+
+import type { ActorOptions } from './Actor.js';
+import type { Pawn } from './Pawn.js';
+import type {
+  GamepadAxisEventDelegate,
+  GamepadButtonEventDelegate,
+  IInputHandler,
+  InputManager,
+  KeyboardEventDelegate,
+  MouseEventDelegate,
+  VirtualJoystickData,
+} from '../systems/InputManager.js';
+
+
+/**
+ * Options for the PlayerController actor
+ */
+export interface PlayerControllerOptions extends ActorOptions {
+  /**
+   * If true, the player controller will not request pointer lock
+   */
+  noPointerLock?: boolean;
+}
+
+type InputDevices = 'mouse' | 'gamepad' | 'keyboard' | 'joystick';
+@EngineClass('PlayerController')
+export class PlayerController extends Actor<PlayerControllerOptions> implements IInputHandler {
+  private pawn: Pawn | null = null;
+  private forward: number = 0;
+  private backward: number = 0;
+  private left: number = 0;
+  private right: number = 0;
+  private zoom: number = 0;
+
+  private forwardKeys: string[] = ['w', 'ArrowUp'].map(key => key.toLowerCase());
+  private backwardKeys: string[] = ['s', 'ArrowDown'].map(key => key.toLowerCase());
+  private leftKeys: string[] = ['a', 'ArrowLeft'].map(key => key.toLowerCase());
+  private rightKeys: string[] = ['d', 'ArrowRight'].map(key => key.toLowerCase());
+  private zoomInKeys: string[] = ['q'].map(key => key.toLowerCase());
+  private zoomOutKeys: string[] = ['e'].map(key => key.toLowerCase());
+  private jumpKeys: string[] = [' '].map(key => key.toLowerCase());
+  private reloadKeys: string[] = ['r'].map(key => key.toLowerCase());
+
+  private inputManager: InputManager | null = null;
+
+  // Movement settings
+  public static inputSettings = {
+    lookSensitivity: 0.02,
+    gamepadLookSensitivity: 80.0,
+    joystickLookSensitivity: 0.6,
+    joystickMovementSensitivity: 0.03,
+  };
+
+  // Add properties to track different input sources
+  private mouseLookUp: number = 0;
+  private mouseLookRight: number = 0;
+  private gamepadLookUp: number = 0;
+  private gamepadLookRight: number = 0;
+  private joystickLookUp: number = 0;
+  private joystickLookRight: number = 0;
+  private lastInputDevice: InputDevices = 'keyboard';
+
+  private joystickStartData: Map<VirtualJoystickIndex, VirtualJoystickData> = new Map();
+
+  public readonly onKeyDown: KeyboardEventDelegate = new Delegate<[KeyboardEvent], boolean>();
+  public readonly onKeyUp: KeyboardEventDelegate = new Delegate<[KeyboardEvent], boolean>();
+  public readonly onMouseDown: MouseEventDelegate = new Delegate<[MouseButton, MouseEvent], boolean>();
+  public readonly onMouseUp: MouseEventDelegate = new Delegate<[MouseButton, MouseEvent], boolean>();
+
+  // Add gamepad delegate events
+  public readonly onGamepadButtonDown: GamepadButtonEventDelegate = new Delegate<[number, GamepadButton, number], boolean>();
+  public readonly onGamepadButtonUp: GamepadButtonEventDelegate = new Delegate<[number, GamepadButton, number], boolean>();
+  public readonly onGamepadAxisChange: GamepadAxisEventDelegate = new Delegate<[number, GamepadAxis, number], boolean>();
+
+
+  /**
+     * Sets the input manager for this controller
+     * @param manager The input manager to use, or null to remove
+     */
+  public setInputManager(manager: InputManager | null): void {
+    this.inputManager = manager;
+  }
+
+  /**
+     * Gets the current input manager
+     * @returns The current input manager or null if none is set
+     */
+  public getInputManager(): InputManager | null {
+    return this.inputManager;
+  }
+
+  /**
+     * Gets the currently possessed pawn
+     * @returns The possessed pawn or null if no pawn is possessed
+     */
+  public getPawn(): Pawn | null {
+    return this.pawn;
+  }
+
+  /**
+     * Handles key down events from the input system
+     * @param e The keyboard event
+     * @returns True if the event was handled, false otherwise
+     */
+  public handleKeyDown(e: KeyboardEvent): boolean {
+    // Track the active input device
+    this.setActiveInputDevice('keyboard');
+
+    if (this.pawn?.handleKeyDown(e)) {
+      return true;
+    }
+
+    if (this.onKeyDown.invokeWithPredicate(result => result, e).at(-1) ?? false) {
+      return true;
+    }
+
+    const key = e.key.toLocaleLowerCase();
+
+    if (this.forwardKeys.includes(key)) {
+      this.forward = 1;
+      return true;
+    } else if (this.backwardKeys.includes(key)) {
+      this.backward = 1;
+      return true;
+    } else if (this.leftKeys.includes(key)) {
+      this.left = 1;
+      return true;
+    } else if (this.rightKeys.includes(key)) {
+      this.right = 1;
+      return true;
+    } else if (this.zoomInKeys.includes(key)) {
+      this.zoom = 1;
+      return true;
+    } else if (this.zoomOutKeys.includes(key)) {
+      this.zoom = -1;
+      return true;
+    } else if (this.jumpKeys.includes(key)) {
+      if (this.pawn) {
+        this.pawn.jump();
+        return true;
+      }
+    } else if (this.reloadKeys.includes(key)) {
+      if (this.pawn) {
+        this.pawn.reload();
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+     * Handles key up events from the input system
+     * @param e The keyboard event
+     * @returns True if the event was handled, false otherwise
+     */
+  public handleKeyUp(e: KeyboardEvent): boolean {
+    if (this.pawn?.handleKeyUp(e)) {
+      return true;
+    }
+
+    if (this.onKeyUp.invokeWithPredicate(result => result, e).at(-1) ?? false) {
+      return true;
+    }
+
+    const key = e.key.toLocaleLowerCase();
+
+    if (this.forwardKeys.includes(key)) {
+      this.forward = 0;
+      return true;
+    } else if (this.backwardKeys.includes(key)) {
+      this.backward = 0;
+      return true;
+    } else if (this.leftKeys.includes(key)) {
+      this.left = 0;
+      return true;
+    } else if (this.rightKeys.includes(key)) {
+      this.right = 0;
+      return true;
+    } else if (this.zoomInKeys.includes(key)) {
+      this.zoom = 0;
+      return true;
+    } else if (this.zoomOutKeys.includes(key)) {
+      this.zoom = 0;
+      return true;
+    } else if (this.jumpKeys.includes(key)) {
+      if (this.pawn) {
+        this.pawn.stopJump();
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+     * Handles mouse down events from the input system
+     * @param button The mouse event
+     * @returns True if the event was handled, false otherwise
+     */
+  public handleMouseDown(button: MouseButton, e: MouseEvent): boolean {
+    if (this.pawn?.handleMouseDown(button, e)) {
+      return true;
+    }
+
+    if (this.onMouseDown.invokeWithPredicate(result => result, button, e).at(-1) ?? false) {
+      return true;
+    }
+
+    if (button === MouseButton.Left) {
+      if (this.pawn?.beginFire() ?? false) {
+        return true;
+      }
+    } else if (button === MouseButton.Right) {
+      if (this.pawn?.beginAltFire() ?? false) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+     * Handles mouse up events from the input system
+     * @param button The mouse event
+     * @returns True if the event was handled, false otherwise
+     */
+  public handleMouseUp(button: MouseButton, e: MouseEvent): boolean {
+    if (this.pawn?.handleMouseUp(button, e)) {
+      return true;
+    }
+
+    if (this.onMouseUp.invokeWithPredicate(result => result, button, e).at(-1) ?? false) {
+      return true;
+    }
+
+    if (button === MouseButton.Left) {
+      if (this.pawn?.endFire() ?? false) {
+        return true;
+      }
+    } else if (button === MouseButton.Right) {
+      if (this.pawn?.endAltFire() ?? false) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+     * Handles mouse movement events from the input system
+     * @param e The mouse event
+     * @returns True if the event was handled, false otherwise
+     */
+  public handleMouseMove(e: MouseEvent): boolean {
+    if (!this.inputManager?.isPointerLocked()) {
+      return false;
+    }
+
+    // Track the active input device
+    this.setActiveInputDevice('mouse');
+
+    this.mouseLookUp += -e.movementY * PlayerController.inputSettings.lookSensitivity;
+    this.mouseLookRight += e.movementX * PlayerController.inputSettings.lookSensitivity;
+    return true;
+  }
+
+  /**
+     * Handles mouse click events from the input system
+     * @param button The mouse button that was clicked
+     * @param e The mouse event
+     * @returns True if the event was handled, false otherwise
+     */
+  public handleMouseClick(button: MouseButton, e: MouseEvent): boolean {
+    return false;
+  }
+
+  /**
+   * Handles virtual joystick events from the input system
+   * @param index The index of the virtual joystick
+   * @param joystickData The data from the virtual joystick
+   * @returns True if the event was handled, false otherwise
+   */
+  public handleVirtualJoystick(index: VirtualJoystickIndex, joystickData: VirtualJoystickData): boolean {
+    const inputSettings = PlayerController.inputSettings;
+    this.setActiveInputDevice('joystick');
+    if (joystickData.type === 'start') {
+      this.joystickStartData.set(index, joystickData);
+    } else if (joystickData.type === 'end') {
+      this.joystickStartData.delete(index);
+      if (index === VirtualJoystickIndex.Left) {
+        this.forward = 0;
+        this.backward = 0;
+        this.left = 0;
+        this.right = 0;
+      } else if (index === VirtualJoystickIndex.Right) {
+        this.joystickLookRight = 0;
+        this.joystickLookUp = 0;
+      }
+    } else if (joystickData.type === 'move') {
+      const startData = this.joystickStartData.get(index);
+      if (startData) {
+        const deltaX = joystickData.position.x - startData.position.x;
+        const deltaY = joystickData.position.y - startData.position.y;
+        if (index === VirtualJoystickIndex.Left) {
+          this.forward = THREE.MathUtils.clamp(-deltaY * inputSettings.joystickMovementSensitivity, 0, 1);
+          this.backward = THREE.MathUtils.clamp(deltaY * inputSettings.joystickMovementSensitivity, 0, 1);
+          this.left = THREE.MathUtils.clamp(-deltaX * inputSettings.joystickMovementSensitivity, 0, 1);
+          this.right = THREE.MathUtils.clamp(deltaX * inputSettings.joystickMovementSensitivity, 0, 1);
+        } else if (index === VirtualJoystickIndex.Right) {
+          this.joystickLookRight = deltaX * inputSettings.joystickLookSensitivity;
+          this.joystickLookUp = -deltaY * inputSettings.joystickLookSensitivity;
+        }
+      } else {
+        this.joystickStartData.set(index, joystickData);
+      }
+    }
+    return true;
+  }
+
+  /**
+     * Track the active input device with a timestamp
+     * @param device The input device that was just used
+     */
+  private setActiveInputDevice(device: InputDevices): void {
+    this.lastInputDevice = device;
+  }
+
+  /**
+     * Handles gamepad button down events from the gamepad system
+     * @param gamepadIndex The index of the gamepad
+     * @param buttonIndex The index of the button
+     * @param value The value of the button press (0.0 to 1.0)
+     * @returns True if the event was handled, false otherwise
+     */
+  public handleGamepadButtonDown(gamepadIndex: number, buttonIndex: number, value: number): boolean {
+    // Only handle gamepad 0 by default (first connected gamepad)
+    if (gamepadIndex !== 0) return false;
+
+    // Track the active input device
+    this.setActiveInputDevice('gamepad');
+
+    if (this.pawn?.handleGamepadButtonDown(gamepadIndex, buttonIndex as GamepadButton, value)) {
+      return true;
+    }
+
+    if (this.onGamepadButtonDown.invokeWithPredicate(result => result, gamepadIndex, buttonIndex as GamepadButton, value).at(-1) ?? false) {
+      return true;
+    }
+
+    if (buttonIndex === GamepadButton.FaceBottom) {
+      // Jump with bottom face button (A on Xbox, X on PlayStation)
+      if (this.pawn) {
+        this.pawn.jump();
+        return true;
+      }
+    } else if (buttonIndex === GamepadButton.FaceLeft) {
+      // Reload with left face button (X on Xbox, Square on PlayStation)
+      if (this.pawn) {
+        this.pawn.reload();
+        return true;
+      }
+    } else if (buttonIndex === GamepadButton.LeftTrigger) {
+      // Begin zoom in
+      this.zoom = value;
+      return true;
+    } else if (buttonIndex === GamepadButton.RightTrigger) {
+      // Begin fire
+      if (this.pawn?.beginFire() ?? false) {
+        return true;
+      }
+    } else if (buttonIndex === GamepadButton.LeftBumper) {
+      // Begin zoom out
+      this.zoom = -value;
+      return true;
+    } else if (buttonIndex === GamepadButton.RightBumper) {
+      // Begin alt fire
+      if (this.pawn?.beginAltFire() ?? false) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+     * Handles gamepad button up events from the gamepad system
+     * @param gamepadIndex The index of the gamepad
+     * @param buttonIndex The index of the button
+     * @returns True if the event was handled, false otherwise
+     */
+  public handleGamepadButtonUp(gamepadIndex: number, buttonIndex: number): boolean {
+    // Only handle gamepad 0 by default (first connected gamepad)
+    if (gamepadIndex !== 0) return false;
+
+    // Track the active input device
+    this.setActiveInputDevice('gamepad');
+
+    if (this.pawn?.handleGamepadButtonUp(gamepadIndex, buttonIndex as GamepadButton)) {
+      return true;
+    }
+
+    if (this.onGamepadButtonUp.invokeWithPredicate(result => result, gamepadIndex, buttonIndex as GamepadButton, 0).at(-1) ?? false) {
+      return true;
+    }
+
+    if (buttonIndex === GamepadButton.LeftTrigger || buttonIndex === GamepadButton.LeftBumper) {
+      // End zoom
+      this.zoom = 0;
+      return true;
+    } else if (buttonIndex === GamepadButton.RightTrigger) {
+      // End fire
+      if (this.pawn?.endFire() ?? false) {
+        return true;
+      }
+    } else if (buttonIndex === GamepadButton.RightBumper) {
+      // End alt fire
+      if (this.pawn?.endAltFire() ?? false) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+     * Handles gamepad axis change events from the gamepad system
+     * @param gamepadIndex The index of the gamepad
+     * @param axisIndex The index of the axis
+     * @param value The value of the axis (-1.0 to 1.0)
+     * @returns True if the event was handled, false otherwise
+     */
+  public handleGamepadAxisChange(gamepadIndex: number, axisIndex: number, value: number): boolean {
+    // Only handle standard gamepad 0
+    if (gamepadIndex !== 0) return false;
+
+    // Only track active input device if there's significant input
+    // This prevents small axis noise from switching input device
+    if (Math.abs(value) > 0.25) {
+      this.setActiveInputDevice('gamepad');
+    }
+
+    if (this.pawn?.handleGamepadAxisChange(gamepadIndex, axisIndex as GamepadAxis, value)) {
+      return true;
+    }
+
+    if (this.onGamepadAxisChange.invokeWithPredicate(result => result, gamepadIndex, axisIndex as GamepadAxis, value).at(-1) ?? false) {
+      return true;
+    }
+
+    if (axisIndex === GamepadAxis.LeftStickX) {
+      // Left/Right movement
+      if (value > 0) {
+        this.right = value;
+        this.left = 0;
+      } else {
+        this.right = 0;
+        this.left = -value;
+      }
+      return true;
+    } else if (axisIndex === GamepadAxis.LeftStickY) {
+      // Forward/Backward movement
+      if (value > 0) {
+        this.backward = value;
+        this.forward = 0;
+      } else {
+        this.backward = 0;
+        this.forward = -value;
+      }
+      return true;
+    } else if (axisIndex === GamepadAxis.RightStickX) {
+      // Look right/left - store in separate gamepad variable
+      this.gamepadLookRight = value * PlayerController.inputSettings.gamepadLookSensitivity;
+      return true;
+    } else if (axisIndex === GamepadAxis.RightStickY) {
+      // Look up/down - store in separate gamepad variable
+      this.gamepadLookUp = -value * PlayerController.inputSettings.gamepadLookSensitivity;
+      return true;
+    }
+
+    return false;
+  }
+
+
+  /**
+     * Called before physics simulation to process input and update the controlled pawn
+     * @param deltaTime Time elapsed since the last frame in seconds
+     */
+  public override tickPrePhysics(deltaTime: number): void {
+    super.tickPrePhysics(deltaTime);
+    if (this.pawn) {
+      const forwardValue = this.forward - this.backward;
+      const rightValue = this.right - this.left;
+
+      // Use look values from the active input device
+      let lookUpValue = 0;
+      let lookRightValue = 0;
+
+      if (this.lastInputDevice === 'mouse') {
+        lookUpValue = this.mouseLookUp;
+        lookRightValue = this.mouseLookRight;
+      } else if (this.lastInputDevice === 'gamepad') {
+        lookUpValue = this.gamepadLookUp;
+        lookRightValue = this.gamepadLookRight;
+      } else if (this.lastInputDevice === 'joystick') {
+        lookUpValue = this.joystickLookUp;
+        lookRightValue = this.joystickLookRight;
+      }
+
+      // Movement inputs are typically speed-based (normalized range [-1, 1])
+      this.pawn.addForwardInput(forwardValue, false);
+      this.pawn.addRightInput(rightValue, false);
+
+      // Look inputs: mouse is absolute (accumulated pixels), gamepad/joystick are speed-based
+      this.pawn.addLookUpInput(lookUpValue, this.lastInputDevice === 'mouse');
+      this.pawn.addLookRightInput(lookRightValue, this.lastInputDevice === 'mouse');
+
+      // Zoom input is typically speed-based
+      this.pawn.addZoomInput(this.zoom, false);
+    }
+
+    // Always reset mouse look values each frame
+    this.mouseLookUp = 0;
+    this.mouseLookRight = 0;
+
+    // For gamepad, apply continuous input or decay
+    if (this.lastInputDevice === 'gamepad') {
+      // Stick is already at zero or at a maintained value from handleGamepadAxisChange
+      // No need for additional decay logic here
+    } else {
+      // If gamepad is not active, decay its values to avoid lingering input
+      const GAMEPAD_DECAY = 0.2;
+      if (Math.abs(this.gamepadLookUp) < GAMEPAD_DECAY) {
+        this.gamepadLookUp = 0;
+      } else if (this.gamepadLookUp > 0) {
+        this.gamepadLookUp -= GAMEPAD_DECAY;
+      } else {
+        this.gamepadLookUp += GAMEPAD_DECAY;
+      }
+
+      if (Math.abs(this.gamepadLookRight) < GAMEPAD_DECAY) {
+        this.gamepadLookRight = 0;
+      } else if (this.gamepadLookRight > 0) {
+        this.gamepadLookRight -= GAMEPAD_DECAY;
+      } else {
+        this.gamepadLookRight += GAMEPAD_DECAY;
+      }
+    }
+  }
+
+  /**
+     * Releases control of the currently possessed pawn
+     */
+  public unpossess(): void {
+    if (this.pawn) {
+      this.pawn.setPlayerController(null);
+    }
+    this.pawn = null;
+  }
+
+  /**
+     * Takes control of the specified pawn
+     * @param pawn The pawn to possess (control)
+     */
+  public possess(pawn: Pawn): void {
+    this.pawn = pawn;
+    this.pawn.setPlayerController(this);
+  }
+
+  /**
+     * Restarts the player at the player start or a specified location
+     */
+  public restartPlayer(): void {
+    const playerStart = this.getWorld()?.gameMode.findPlayerStart(this);
+    if (playerStart) {
+      ensure(this.pawn);
+      const playerStartTransform = playerStart.getWorldTransform();
+      this.pawn?.setWorldTransform({
+        position: playerStartTransform.position,
+        rotation: playerStartTransform.rotation,
+      });
+    }
+  }
+
+  public override getCamera(): THREE.Camera | null {
+    return this.pawn?.getCamera() ?? super.getCamera();
+  }
+
+  //====================================================================================================
+
+  protected override doBeginPlay(): void {
+    super.doBeginPlay();
+    const world = this.getWorld()!;
+    world.consoleManager.addCommandHandler(this);
+    if (!this.options.noPointerLock) {
+      world.inputManager.requestPointerLock({});
+    }
+    world.inputManager.addInputHandler(this);
+
+    this.restartPlayer();
+  }
+
+  protected override doEndPlay(): void {
+    super.doEndPlay();
+    this.getWorld()?.consoleManager.removeCommandHandler(this);
+    this.inputManager?.removeInputHandler(this);
+  }
+
+  @ConsoleCommand('restartplayer', 'Restart the current player')
+  private restartPlayerCommand(): string {
+    this.restartPlayer();
+    return 'Restarted player';
+  }
+
+  //====================================================================================================
+  // Editor Functions
+  //====================================================================================================
+
+  public override getEditorClassIcon(): string | null {
+    return 'Icon_Character';
+  }
+}

package/src/actors/PlayerStart.ts

@@ -0,0 +1,47 @@
+/**
+ * PlayerStart - simple actor marking where players should spawn.
+ *
+ * Detailed explanation:
+ * - Provides only a transform and no runtime behavior.
+ * - Queried by `GameMode` implementations to determine initial pawn placement.
+ * - Multiple instances allow the game to choose among several potential spawn points.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Place in levels wherever new players or respawns should occur.
+ * - Access via `world.getActors(PlayerStart)` to collect all available starts.
+ * - Extend this class if additional logic such as team-based filtering is required.
+ */
+import * as THREE from 'three';
+
+import { EngineClass } from '../systems/ClassRegistry.js';
+
+import { Actor } from './Actor.js';
+
+
+/**
+ * Represents the starting transform for a player controlled pawn.
+ */
+@EngineClass('PlayerStart')
+export class PlayerStart extends Actor {
+
+  //====================================================================================================
+  // Editor Functions
+  //====================================================================================================
+
+  public override onEditorAddToWorld(): void {
+    super.onEditorAddToWorld();
+    // Create arrow helper pointing forward
+    const arrowHelper = new THREE.ArrowHelper(
+      new THREE.Vector3(0, 0, -1), // direction
+      new THREE.Vector3(0, 0.02, 0), // position slightly above ground
+      2, // length
+      0x00ffff, // color
+    );
+    arrowHelper.setTransient(true);
+    this.rootComponent?.add(arrowHelper);
+  }
+
+  public override getEditorClassIcon(): string | null {
+    return 'Icon_PlayerStart';
+  }
+}