《移动游戏产品的架构·客户端与移动运行时》8.1 触控、陀螺仪与传感器抽象

// file: src/input/gesture.ts
// tier: L1
// verify: node --test test/input/gesture.test.ts

export interface TouchPoint { readonly id: number; readonly x: number; readonly y: number; readonly tMs: number; }

export interface GestureConfig {
  readonly tapMaxMs: number; readonly tapSlopPx: number; readonly longPressMs: number;
  readonly swipeMinPx: number; readonly swipeMinVelocityPxPerMs: number; readonly pinchMinScaleDelta: number;
}

export const DEFAULT_GESTURE: GestureConfig = {
  tapMaxMs: 220, tapSlopPx: 12, longPressMs: 500,
  swipeMinPx: 40, swipeMinVelocityPxPerMs: 0.35, pinchMinScaleDelta: 0.08,
};

export type SwipeDirection = "up" | "down" | "left" | "right";
export type LookSource = "gyro" | "drag";

export type Intent =
  | { kind: "tap"; x: number; y: number; tMs: number }
  | { kind: "long-press"; x: number; y: number; tMs: number }
  | { kind: "drag"; id: number; dx: number; dy: number; tMs: number }
  | { kind: "swipe"; direction: SwipeDirection; distancePx: number; velocityPxPerMs: number; tMs: number }
  | { kind: "pinch"; scale: number; centerX: number; centerY: number; tMs: number }
  | { kind: "cancel"; id: number; tMs: number }
  | { kind: "look"; yawDeg: number; pitchDeg: number; source: LookSource; tMs: number };

interface Track {
  startX: number; startY: number; startTMs: number;
  lastX: number; lastY: number; maxDistancePx: number;
  moved: boolean; longPressSent: boolean;
}

export function clamp(value: number, min: number, max: number): number {
  return Math.min(max, Math.max(min, value));
}

/** 触点序列归一化为意图事件；不做命中测试，也不做 7.3 的跨层仲裁。 */
export class GestureRecognizer {
  readonly #config: GestureConfig;
  readonly #tracks = new Map<number, Track>();
  #multiTouched = false;
  #pinchBasePx: number | null = null;
  #lastPinchScale = 1;

  constructor(config: GestureConfig = DEFAULT_GESTURE) {
    this.#config = config;
  }

  down(point: TouchPoint): Intent[] {
    this.#tracks.set(point.id, {
      startX: point.x, startY: point.y, startTMs: point.tMs,
      lastX: point.x, lastY: point.y, maxDistancePx: 0,
      moved: false, longPressSent: false,
    });
    if (this.#tracks.size >= 2) {
      this.#multiTouched = true;
      this.#pinchBasePx = this.#distanceBetweenFirstTwo();
      this.#lastPinchScale = 1;
    }
    return [];
  }

  move(point: TouchPoint): Intent[] {
    const track = this.#tracks.get(point.id);
    if (!track) {
      return [];
    }
    const previousX = track.lastX;
    const previousY = track.lastY;
    track.lastX = point.x;
    track.lastY = point.y;
    track.maxDistancePx = Math.max(track.maxDistancePx,
      Math.hypot(point.x - track.startX, point.y - track.startY));
    if (track.maxDistancePx > this.#config.tapSlopPx) {
      track.moved = true;
    }
    if (this.#tracks.size >= 2) {
      return this.#pinch(point.tMs);
    }
    if (!track.moved) {
      return [];
    }
    return [{ kind: "drag", id: point.id, dx: point.x - previousX, dy: point.y - previousY, tMs: point.tMs }];
  }

  tick(nowMs: number): Intent[] {
    const intents: Intent[] = [];
    for (const track of this.#tracks.values()) {
      if (track.longPressSent || track.moved || this.#tracks.size >= 2) {
        continue;
      }
      if (nowMs - track.startTMs >= this.#config.longPressMs) {
        track.longPressSent = true;
        intents.push({ kind: "long-press", x: track.lastX, y: track.lastY, tMs: nowMs });
      }
    }
    return intents;
  }

  up(point: TouchPoint): Intent[] {
    const track = this.#tracks.get(point.id);
    if (!track) {
      return [];
    }
    this.#tracks.delete(point.id);
    const intents: Intent[] = [];
    const durationMs = point.tMs - track.startTMs;
    const distancePx = Math.hypot(point.x - track.startX, point.y - track.startY);
    if (!this.#multiTouched && !track.moved && durationMs <= this.#config.tapMaxMs) {
      intents.push({ kind: "tap", x: point.x, y: point.y, tMs: point.tMs });
    } else if (!this.#multiTouched && track.moved) {
      const velocity = durationMs > 0 ? distancePx / durationMs : 0;
      if (distancePx >= this.#config.swipeMinPx && velocity >= this.#config.swipeMinVelocityPxPerMs) {
        const dx = point.x - track.startX;
        const dy = point.y - track.startY;
        const direction: SwipeDirection = Math.abs(dx) >= Math.abs(dy)
          ? (dx >= 0 ? "right" : "left")
          : (dy >= 0 ? "down" : "up");
        intents.push({ kind: "swipe", direction, distancePx, velocityPxPerMs: velocity, tMs: point.tMs });
      }
    }
    if (this.#tracks.size < 2) {
      this.#pinchBasePx = null;
      this.#lastPinchScale = 1;
    }
    if (this.#tracks.size === 0) {
      this.#multiTouched = false;
    }
    return intents;
  }

  cancel(id: number, tMs: number): Intent[] {
    const existed = this.#tracks.delete(id);
    if (this.#tracks.size === 0) {
      this.#multiTouched = false;
      this.#pinchBasePx = null;
    }
    return existed ? [{ kind: "cancel", id, tMs }] : [];
  }

  #distanceBetweenFirstTwo(): number | null {
    const [a, b] = [...this.#tracks.values()];
    return a && b ? Math.hypot(b.startX - a.startX, b.startY - a.startY) : null;
  }

  #pinch(tMs: number): Intent[] {
    if (this.#pinchBasePx === null || this.#pinchBasePx <= 0) {
      return [];
    }
    const [a, b] = [...this.#tracks.values()];
    if (!a || !b) {
      return [];
    }
    const scale = Math.hypot(b.lastX - a.lastX, b.lastY - a.lastY) / this.#pinchBasePx;
    if (Math.abs(scale - this.#lastPinchScale) < this.#config.pinchMinScaleDelta) {
      return [];
    }
    this.#lastPinchScale = scale;
    return [{ kind: "pinch", scale, centerX: (a.lastX + b.lastX) / 2, centerY: (a.lastY + b.lastY) / 2, tMs }];
  }
}

export type SensorAvailability = "available" | "missing" | "permission-denied";

export interface MotionSample {
  readonly tMs: number; readonly yawRateDegPerSec: number; readonly pitchRateDegPerSec: number;
}

export interface MotionSource {
  readonly kind: "gyro";
  availability(): SensorAvailability;
}

export interface LookConfig {
  readonly targetHz: number; readonly deadzoneDegPerSec: number; readonly smoothingAlpha: number;
  readonly maxStepDeg: number; readonly maxPitchDeg: number; readonly dragDegPerPx: number;
}

export const DEFAULT_LOOK: LookConfig = {
  targetHz: 30, deadzoneDegPerSec: 0.6, smoothingAlpha: 0.35,
  maxStepDeg: 4, maxPitchDeg: 60, dragDegPerPx: 0.12,
};

export interface LookSample {
  readonly yawDeg: number; readonly pitchDeg: number; readonly source: LookSource; readonly tMs: number;
}

export type Degradation = "none" | "sensor-missing" | "sensor-denied";

/** 陀螺仪降采样、死区、平滑与积分；缺失时改用 applyDrag，意图结构不变。 */
export class LookController {
  readonly #source: MotionSource;
  readonly #config: LookConfig;
  #lastAcceptedMs = Number.NEGATIVE_INFINITY;
  #yawRate = 0;
  #pitchRate = 0;
  #yaw = 0;
  #pitch = 0;

  constructor(source: MotionSource, config: LookConfig = DEFAULT_LOOK) {
    this.#source = source;
    this.#config = config;
  }

  availability(): SensorAvailability {
    return this.#source.availability();
  }

  source(): LookSource {
    return this.availability() === "available" ? "gyro" : "drag";
  }

  degradation(): Degradation {
    const state = this.availability();
    return state === "available" ? "none" : state === "missing" ? "sensor-missing" : "sensor-denied";
  }

  ingest(sample: MotionSample): LookSample | null {
    if (this.source() !== "gyro") {
      return null;
    }
    if (sample.tMs - this.#lastAcceptedMs < 1000 / this.#config.targetHz) {
      return null;
    }
    const dtSec = Number.isFinite(this.#lastAcceptedMs)
      ? Math.min(Math.max(sample.tMs - this.#lastAcceptedMs, 0), 100) / 1000
      : 0;
    this.#lastAcceptedMs = sample.tMs;
    const yawRate = this.#deadzone(sample.yawRateDegPerSec);
    const pitchRate = this.#deadzone(sample.pitchRateDegPerSec);
    const alpha = this.#config.smoothingAlpha;
    this.#yawRate = alpha * yawRate + (1 - alpha) * this.#yawRate;
    this.#pitchRate = alpha * pitchRate + (1 - alpha) * this.#pitchRate;
    this.#yaw += this.#clampStep(this.#yawRate * dtSec);
    this.#pitch = clamp(this.#pitch + this.#clampStep(this.#pitchRate * dtSec),
      -this.#config.maxPitchDeg, this.#config.maxPitchDeg);
    return { yawDeg: this.#yaw, pitchDeg: this.#pitch, source: "gyro", tMs: sample.tMs };
  }

  applyDrag(dxPx: number, dyPx: number, tMs: number): LookSample {
    const max = this.#config.maxStepDeg * 4;
    this.#yaw += clamp(dxPx * this.#config.dragDegPerPx, -max, max);
    this.#pitch = clamp(this.#pitch - clamp(dyPx * this.#config.dragDegPerPx, -max, max),
      -this.#config.maxPitchDeg, this.#config.maxPitchDeg);
    return { yawDeg: this.#yaw, pitchDeg: this.#pitch, source: "drag", tMs };
  }

  #deadzone(rate: number): number {
    return Math.abs(rate) < this.#config.deadzoneDegPerSec ? 0 : rate;
  }

  #clampStep(delta: number): number {
    return clamp(delta, -this.#config.maxStepDeg, this.#config.maxStepDeg);
  }
}

export function lookIntent(sample: LookSample): Intent {
  return { kind: "look", yawDeg: sample.yawDeg, pitchDeg: sample.pitchDeg, source: sample.source, tMs: sample.tMs };
}