emoemu 0.1.0

package/src/input/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Input System
+ *
+ * Handles keyboard and gamepad input for the emulator.
+ */
+
+// Controllers
+export { Controller, Button, DEFAULT_KEY_MAP } from './Controller';
+
+// Input management
+export { InputManager, type InputResult } from './InputManager';
+export {
+  InputMapper,
+  type ButtonChangeCallback,
+  type AnalogChangeCallback,
+  ANALOG_INDEX,
+  ANALOG_AXIS,
+} from './InputMapper';
+
+// Gamepad support
+export {
+  GamepadManager,
+  type GamepadButtonCallback,
+  type GamepadAnalogCallback,
+} from './GamepadManager';
+export {
+  type AnalogState,
+  type GamepadProfile,
+  gamepadProfiles,
+  findProfile,
+  isGamepadDevice,
+} from './gamepadProfiles';
+
+// Utilities
+export { createOppositeDirections } from './inputUtils';
+
+// Re-export constants
+export * from './consts';

package/src/input/inputUtils/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared input utilities for keyboard and gamepad handling.
+ */
+
+/**
+ * Create a Map of opposite D-pad directions for preventing simultaneous
+ * Up+Down or Left+Right presses.
+ *
+ * The returned map accepts any button type T for lookups, returning
+ * the opposite direction if found, or undefined if not a directional button.
+ *
+ * @param Up - The up button value
+ * @param Down - The down button value
+ * @param Left - The left button value
+ * @param Right - The right button value
+ * @returns Map from each direction to its opposite
+ */
+export const createOppositeDirections = <T extends number>(
+  Up: T,
+  Down: T,
+  Left: T,
+  Right: T
+): Map<T, T> => {
+  // Create a Map with explicit type to allow any T as lookup key
+  const map = new Map<T, T>();
+  map.set(Up, Down);
+  map.set(Down, Up);
+  map.set(Left, Right);
+  map.set(Right, Left);
+  return map;
+};

package/src/netplay/FrameBuffer/consts.ts

@@ -0,0 +1,2 @@
+/** Default number of input values per device (joypad + 2 analog) */
+export const INPUTS_PER_DEVICE = 3;

package/src/netplay/FrameBuffer/index.ts

@@ -0,0 +1,364 @@
+/**
+ * Frame Buffer Ring for Netplay Rollback
+ *
+ * Maintains a fixed-size ring buffer of frame states for rollback/replay.
+ * Each frame stores:
+ * - Serialized core state (savestate)
+ * - Local input
+ * - Remote input (per client)
+ * - CRC32 hash for desync detection
+ */
+
+import { DEFAULT_FRAME_BUFFER_SIZE, MAX_INPUT_DEVICES, type FrameState } from '..';
+import { crc32 } from '../crc32';
+
+export * from './consts';
+import { INPUTS_PER_DEVICE } from './consts';
+
+/**
+ * Create a zero-filled number array of the given size.
+ */
+const createZeroArray = (size: number): number[] => {
+  const arr: number[] = [];
+  for (let i = 0; i < size; i++) {
+    arr.push(0);
+  }
+  return arr;
+};
+
+/**
+ * Create an empty frame state for a given frame number.
+ */
+const createEmptyFrame = (frameNumber: number): FrameState => ({
+  frameNumber,
+  serializedState: null,
+  localInput: createZeroArray(MAX_INPUT_DEVICES * INPUTS_PER_DEVICE),
+  remoteInput: new Map(),
+  remoteInputReal: new Map(),
+  crc: null,
+});
+
+/**
+ * FrameBuffer implements a ring buffer for frame history.
+ *
+ * Frame numbers can grow indefinitely, but the buffer only stores
+ * the most recent `capacity` frames. Old frames are overwritten.
+ */
+export class FrameBuffer {
+  private readonly buffer: FrameState[];
+  private readonly _capacity: number;
+
+  /** Earliest frame number still in the buffer */
+  private _oldestFrame: number = 0;
+
+  /** Most recent frame number in the buffer */
+  private _newestFrame: number = -1;
+
+  constructor(capacity: number = DEFAULT_FRAME_BUFFER_SIZE) {
+    this._capacity = capacity;
+    this.buffer = [];
+
+    // Initialize all slots
+    for (let i = 0; i < capacity; i++) {
+      this.buffer.push(createEmptyFrame(i));
+    }
+  }
+
+  /** Buffer capacity (max frames stored) */
+  get capacity(): number {
+    return this._capacity;
+  }
+
+  /** Oldest frame number still available */
+  get oldestFrame(): number {
+    return this._oldestFrame;
+  }
+
+  /** Newest (current) frame number */
+  get newestFrame(): number {
+    return this._newestFrame;
+  }
+
+  /** Number of frames currently stored */
+  get size(): number {
+    if (this._newestFrame < 0) {
+      return 0;
+    }
+    return Math.min(this._newestFrame - this._oldestFrame + 1, this._capacity);
+  }
+
+  /**
+   * Get the buffer index for a frame number.
+   */
+  private indexFor(frameNumber: number): number {
+    // Handle negative frame numbers (shouldn't happen but be safe)
+    const n = frameNumber < 0 ? 0 : frameNumber;
+    return n % this._capacity;
+  }
+
+  /**
+   * Check if a frame number is within the buffer range.
+   */
+  hasFrame(frameNumber: number): boolean {
+    if (this._newestFrame < 0) {
+      return false;
+    }
+    return frameNumber >= this._oldestFrame && frameNumber <= this._newestFrame;
+  }
+
+  /**
+   * Get a frame by number. Returns null if not in buffer.
+   */
+  get(frameNumber: number): FrameState | null {
+    if (!this.hasFrame(frameNumber)) {
+      return null;
+    }
+    return this.buffer[this.indexFor(frameNumber)];
+  }
+
+  /**
+   * Get the current (newest) frame.
+   */
+  getCurrent(): FrameState | null {
+    if (this._newestFrame < 0) {
+      return null;
+    }
+    return this.buffer[this.indexFor(this._newestFrame)];
+  }
+
+  /**
+   * Advance to the next frame, returning the new frame state.
+   * This overwrites the oldest frame if the buffer is full.
+   */
+  advance(): FrameState {
+    this._newestFrame++;
+
+    // Update oldest frame if buffer is full (only when we actually need to overwrite)
+    const currentSize = this._newestFrame - this._oldestFrame + 1;
+    if (currentSize > this._capacity) {
+      this._oldestFrame = this._newestFrame - this._capacity + 1;
+    }
+
+    const index = this.indexFor(this._newestFrame);
+    const frame = this.buffer[index];
+
+    // Reset the frame for reuse
+    frame.frameNumber = this._newestFrame;
+    frame.serializedState = null;
+    frame.localInput.fill(0);
+    frame.remoteInput.clear();
+    frame.remoteInputReal.clear();
+    frame.crc = null;
+
+    return frame;
+  }
+
+  /**
+   * Initialize the buffer at a specific starting frame.
+   * Used when syncing with server.
+   */
+  initializeAt(frameNumber: number): FrameState {
+    this._oldestFrame = frameNumber;
+    this._newestFrame = frameNumber;
+
+    const index = this.indexFor(frameNumber);
+    const frame = this.buffer[index];
+
+    frame.frameNumber = frameNumber;
+    frame.serializedState = null;
+    frame.localInput.fill(0);
+    frame.remoteInput.clear();
+    frame.remoteInputReal.clear();
+    frame.crc = null;
+
+    return frame;
+  }
+
+  /**
+   * Set the serialized state for a frame.
+   */
+  setState(frameNumber: number, state: Buffer): boolean {
+    const frame = this.get(frameNumber);
+    if (!frame) {
+      return false;
+    }
+    frame.serializedState = state;
+    frame.crc = crc32(state);
+    return true;
+  }
+
+  /**
+   * Get the serialized state for a frame.
+   */
+  getState(frameNumber: number): Buffer | null {
+    const frame = this.get(frameNumber);
+    return frame?.serializedState ?? null;
+  }
+
+  /**
+   * Set local input for the current frame.
+   * Input is an array of values: [joypad, analogLeft, analogRight] per device.
+   */
+  setLocalInput(input: number[]): boolean {
+    const frame = this.getCurrent();
+    if (!frame) {
+      return false;
+    }
+    const len = Math.min(input.length, frame.localInput.length);
+    for (let i = 0; i < len; i++) {
+      frame.localInput[i] = input[i];
+    }
+    return true;
+  }
+
+  /**
+   * Set local input for a specific device on the current frame.
+   */
+  setLocalInputForDevice(
+    deviceIndex: number,
+    joypad: number,
+    analogLeft: number = 0,
+    analogRight: number = 0
+  ): boolean {
+    const frame = this.getCurrent();
+    if (!frame || deviceIndex >= MAX_INPUT_DEVICES) {
+      return false;
+    }
+    const base = deviceIndex * INPUTS_PER_DEVICE;
+    frame.localInput[base] = joypad;
+    frame.localInput[base + 1] = analogLeft;
+    frame.localInput[base + 2] = analogRight;
+    return true;
+  }
+
+  /**
+   * Set remote input for a specific client and frame.
+   * Returns true if this was new real input (not just an update).
+   */
+  setRemoteInput(
+    frameNumber: number,
+    clientId: number,
+    input: number[],
+    isReal: boolean = true
+  ): boolean {
+    const frame = this.get(frameNumber);
+    if (!frame) {
+      return false;
+    }
+
+    const wasReal = frame.remoteInputReal.get(clientId) ?? false;
+    frame.remoteInput.set(clientId, [...input]);
+    frame.remoteInputReal.set(clientId, isReal);
+
+    // Return true if this is new real input
+    return isReal && !wasReal;
+  }
+
+  /**
+   * Get remote input for a client at a specific frame.
+   * Returns null if not available.
+   */
+  getRemoteInput(frameNumber: number, clientId: number): number[] | null {
+    const frame = this.get(frameNumber);
+    return frame?.remoteInput.get(clientId) ?? null;
+  }
+
+  /**
+   * Check if remote input for a client at a frame is real (not simulated).
+   */
+  isRemoteInputReal(frameNumber: number, clientId: number): boolean {
+    const frame = this.get(frameNumber);
+    return frame?.remoteInputReal.get(clientId) ?? false;
+  }
+
+  /**
+   * Get the CRC32 for a frame's state.
+   */
+  getCrc(frameNumber: number): number | null {
+    const frame = this.get(frameNumber);
+    return frame?.crc ?? null;
+  }
+
+  /**
+   * Find the earliest frame that has real remote input from all specified clients.
+   * Used to determine the "other" sync point.
+   */
+  findSyncFrame(clientIds: number[]): number | null {
+    if (clientIds.length === 0 || this._newestFrame < 0) {
+      return this._newestFrame >= 0 ? this._newestFrame : null;
+    }
+
+    // Search backwards from newest to find last fully synced frame
+    for (let f = this._newestFrame; f >= this._oldestFrame; f--) {
+      const frame = this.get(f);
+      if (!frame) {
+        continue;
+      }
+
+      let allReal = true;
+      for (const clientId of clientIds) {
+        if (!frame.remoteInputReal.get(clientId)) {
+          allReal = false;
+          break;
+        }
+      }
+
+      if (allReal) {
+        return f;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Find the first frame where we have simulated (not real) input for any client.
+   * This is the "unread" frame - first frame with incomplete data.
+   */
+  findUnreadFrame(clientIds: number[]): number | null {
+    if (clientIds.length === 0 || this._newestFrame < 0) {
+      return null;
+    }
+
+    // Search forward from oldest to find first frame with simulated input
+    for (let f = this._oldestFrame; f <= this._newestFrame; f++) {
+      const frame = this.get(f);
+      if (!frame) {
+        continue;
+      }
+
+      for (const clientId of clientIds) {
+        if (!frame.remoteInputReal.get(clientId)) {
+          return f;
+        }
+      }
+    }
+
+    // All frames have real input
+    return null;
+  }
+
+  /**
+   * Clear all frames and reset the buffer.
+   */
+  clear(): void {
+    this._oldestFrame = 0;
+    this._newestFrame = -1;
+    for (let i = 0; i < this._capacity; i++) {
+      const frame = this.buffer[i];
+      frame.frameNumber = i;
+      frame.serializedState = null;
+      frame.localInput.fill(0);
+      frame.remoteInput.clear();
+      frame.remoteInputReal.clear();
+      frame.crc = null;
+    }
+  }
+}
+
+/**
+ * Create a new frame buffer with the specified capacity.
+ */
+export const createFrameBuffer = (capacity: number = DEFAULT_FRAME_BUFFER_SIZE): FrameBuffer => {
+  return new FrameBuffer(capacity);
+};