@quybt93/pcgf 0.0.1

package/plugins/phaser-casual-game-factory/templates/loading-view/loading-view-model.ts

@@ -0,0 +1,203 @@
+import { BehaviorSubject, Observable, Subscription, timer } from 'rxjs';
+import type { LoadingViewModelConfig, LoadingViewState, LoadingViewTask } from './types';
+import {
+  calculateDisplayedProgress,
+  calculateWeightedProgress,
+  clampLoadingProgress,
+} from './progress';
+
+const now = (): number => globalThis.performance?.now() ?? Date.now();
+
+/** Progress never reads as complete while any registered task is still running. */
+const INCOMPLETE_PROGRESS_CAP = 0.99;
+
+/**
+ * Phaser-independent loading state (MVVM ViewModel).
+ *
+ * Contract:
+ * - Every async step registers as a weighted task and reports real progress.
+ * - Tasks may start with `opening`; work that changes visible scenes waits for open
+ *   (`afterOpen` or `waitForOpen()`).
+ * - Task window = open + showing (showing ≥ minimumVisibleMs). Close is View-only.
+ * - actualProgress stays ≤ 0.99 until all tasks settle, then 1.
+ * - View is optional and only mirrors `state$`.
+ */
+export class LoadingViewModel {
+  readonly openDurationMs: number;
+  readonly closeDurationMs: number;
+  readonly minimumVisibleMs: number;
+
+  private readonly stateSubject: BehaviorSubject<LoadingViewState>;
+  private readonly tasks: LoadingViewTask[];
+  private readonly taskProgress = new Map<string, number>();
+  private ticker?: Subscription;
+  private startedAt = 0;
+  private closingStartedAt?: number;
+  private openReleased = false;
+  private allTasksFinished = false;
+  private taskError?: unknown;
+  private runPromise?: Promise<void>;
+  private resolveRun?: () => void;
+  private rejectRun?: (error: unknown) => void;
+  private resolveOpen!: () => void;
+  private readonly openReady: Promise<void>;
+
+  readonly state$: Observable<LoadingViewState>;
+
+  constructor(config: LoadingViewModelConfig, tasks: LoadingViewTask | LoadingViewTask[]) {
+    this.openDurationMs = Math.max(0, config.openDurationMs ?? 0);
+    this.closeDurationMs = Math.max(0, config.closeDurationMs ?? 0);
+    this.minimumVisibleMs = Math.max(0, config.minimumVisibleMs ?? 0);
+    this.tasks = (Array.isArray(tasks) ? tasks : [tasks]).map((task, index) => ({
+      ...task,
+      id: task.id || `task-${index}`,
+      weight: Math.max(0, task.weight ?? 1),
+    }));
+    this.tasks.forEach((task) => this.taskProgress.set(task.id, 0));
+    this.openReady = new Promise<void>((resolve) => {
+      this.resolveOpen = resolve;
+    });
+
+    this.stateSubject = new BehaviorSubject<LoadingViewState>({
+      phase: 'idle',
+      description: config.description,
+      actualProgress: 0,
+      displayedProgress: 0,
+    });
+    this.state$ = this.stateSubject.asObservable();
+  }
+
+  get snapshot(): LoadingViewState {
+    return this.stateSubject.value;
+  }
+
+  /** Resolves when opening has finished (same gate as `afterOpen` tasks). */
+  waitForOpen(): Promise<void> {
+    return this.openReady;
+  }
+
+  start(): Promise<void> {
+    if (this.runPromise) return this.runPromise;
+
+    this.runPromise = new Promise<void>((resolve, reject) => {
+      this.resolveRun = resolve;
+      this.rejectRun = reject;
+    });
+    this.startedAt = now();
+    this.emit({ phase: 'opening' });
+    this.ticker = timer(0, 16).subscribe(() => this.tick(now()));
+    void this.runTasks();
+    return this.runPromise;
+  }
+
+  dispose(): void {
+    this.ticker?.unsubscribe();
+    this.ticker = undefined;
+    this.releaseOpen();
+    this.stateSubject.complete();
+  }
+
+  private releaseOpen(): void {
+    if (this.openReleased) return;
+    this.openReleased = true;
+    this.resolveOpen();
+  }
+
+  private async runTasks(): Promise<void> {
+    if (this.tasks.length === 0) {
+      this.allTasksFinished = true;
+      this.emitProgress();
+      return;
+    }
+
+    const contextBase = {
+      waitForOpen: () => this.openReady,
+    };
+
+    try {
+      const results = await Promise.allSettled(
+        this.tasks.map(async (task) => {
+          if (task.afterOpen) await this.openReady;
+          await task.run({
+            ...contextBase,
+            reportProgress: (progress) => {
+              this.taskProgress.set(task.id, clampLoadingProgress(progress));
+              this.emitProgress();
+            },
+          });
+          this.taskProgress.set(task.id, 1);
+          this.emitProgress();
+        }),
+      );
+      const failed = results.find((result): result is PromiseRejectedResult => result.status === 'rejected');
+      if (failed) this.taskError = failed.reason;
+    } finally {
+      // Never reveal a partially settled task set, including error paths.
+      this.tasks.forEach((task) => this.taskProgress.set(task.id, 1));
+      this.allTasksFinished = true;
+      this.emitProgress();
+    }
+  }
+
+  private tick(currentTime: number): void {
+    const openingElapsed = currentTime - this.startedAt;
+    if (openingElapsed < this.openDurationMs) return;
+
+    this.releaseOpen();
+
+    if (this.closingStartedAt == null) {
+      const visibleElapsed = Math.max(0, openingElapsed - this.openDurationMs);
+      const actualProgress = this.calculateActualProgress();
+      const displayedProgress = calculateDisplayedProgress(
+        actualProgress,
+        visibleElapsed,
+        this.minimumVisibleMs,
+      );
+
+      // An instant zero-minimum load skips text/slider and goes straight to close.
+      if (this.allTasksFinished && this.minimumVisibleMs === 0 && actualProgress >= 1) {
+        this.closingStartedAt = currentTime;
+        this.emit({ phase: 'closing', actualProgress: 1, displayedProgress: 1, error: this.taskError });
+        return;
+      }
+
+      this.emit({ phase: 'showing', actualProgress, displayedProgress, error: this.taskError });
+      if (this.allTasksFinished && displayedProgress >= 1) {
+        this.closingStartedAt = currentTime;
+        this.emit({ phase: 'closing', actualProgress: 1, displayedProgress: 1, error: this.taskError });
+      }
+      return;
+    }
+
+    if (currentTime - this.closingStartedAt >= this.closeDurationMs) this.complete();
+  }
+
+  private calculateActualProgress(): number {
+    const weighted = calculateWeightedProgress(
+      this.tasks.map((task) => ({
+        progress: this.taskProgress.get(task.id) ?? 0,
+        weight: task.weight,
+      })),
+      this.allTasksFinished,
+    );
+    if (this.allTasksFinished) return 1;
+    return Math.min(weighted, INCOMPLETE_PROGRESS_CAP);
+  }
+
+  private emitProgress(): void {
+    const state = this.snapshot;
+    this.emit({ actualProgress: this.calculateActualProgress(), error: this.taskError ?? state.error });
+  }
+
+  private emit(patch: Partial<LoadingViewState>): void {
+    this.stateSubject.next({ ...this.snapshot, ...patch });
+  }
+
+  private complete(): void {
+    this.ticker?.unsubscribe();
+    this.ticker = undefined;
+    this.emit({ phase: 'complete', actualProgress: 1, displayedProgress: 1, error: this.taskError });
+    if (this.taskError != null) this.rejectRun?.(this.taskError);
+    else this.resolveRun?.();
+  }
+}

package/plugins/phaser-casual-game-factory/templates/loading-view/presets.ts

@@ -0,0 +1,26 @@
+import type { LoadingViewModelConfig } from './types';
+
+/** Safe defaults; generated games should tune them from the requested UX. */
+export const LOADING_TIMING_PRESETS = {
+  /** First boot → Home. Default close style `iris` (~700ms). Use 650 when `slide-up`. */
+  bootToHome: {
+    openDurationMs: 0,
+    minimumVisibleMs: 2000,
+    closeDurationMs: 700,
+  },
+  menuToGame: {
+    openDurationMs: 0,
+    minimumVisibleMs: 1000,
+    closeDurationMs: 1000,
+  },
+  gameToMenu: {
+    openDurationMs: 0,
+    minimumVisibleMs: 1000,
+    closeDurationMs: 1000,
+  },
+  nextLevel: {
+    openDurationMs: 1000,
+    minimumVisibleMs: 1000,
+    closeDurationMs: 1000,
+  },
+} as const satisfies Record<string, LoadingViewModelConfig>;

package/plugins/phaser-casual-game-factory/templates/loading-view/progress.ts

@@ -0,0 +1,30 @@
+export type WeightedLoadingProgress = {
+  progress: number;
+  weight?: number;
+};
+
+export const clampLoadingProgress = (value: number): number =>
+  Math.max(0, Math.min(1, Number.isFinite(value) ? value : 0));
+
+export function calculateDisplayedProgress(
+  actualProgress: number,
+  visibleElapsedMs: number,
+  minimumVisibleMs: number,
+): number {
+  const timeProgress =
+    minimumVisibleMs <= 0 ? 1 : clampLoadingProgress(Math.max(0, visibleElapsedMs) / minimumVisibleMs);
+  return Math.min(clampLoadingProgress(actualProgress), timeProgress);
+}
+
+export function calculateWeightedProgress(entries: WeightedLoadingProgress[], allFinished = false): number {
+  if (entries.length === 0) return 1;
+  const totalWeight = entries.reduce((total, entry) => total + Math.max(0, entry.weight ?? 1), 0);
+  if (totalWeight <= 0) return allFinished ? 1 : 0;
+  return clampLoadingProgress(
+    entries.reduce(
+      (total, entry) =>
+        total + clampLoadingProgress(entry.progress) * Math.max(0, entry.weight ?? 1),
+      0,
+    ) / totalWeight,
+  );
+}

package/plugins/phaser-casual-game-factory/templates/loading-view/types.ts

@@ -0,0 +1,49 @@
+export type LoadingPhase = 'idle' | 'opening' | 'showing' | 'closing' | 'complete';
+
+/** Timing and state belong to the ViewModel. No texture, mask or layout fields. */
+export type LoadingViewModelConfig = {
+  description?: string;
+  /** Cover/open tween length. Visual scene work must wait for this. */
+  openDurationMs?: number;
+  /** Reveal/close tween only — no async work. */
+  closeDurationMs?: number;
+  /** Minimum `showing` duration after open. */
+  minimumVisibleMs?: number;
+};
+
+export type LoadingViewTaskContext = {
+  /** Reports this task's real progress in the [0..1] range. */
+  reportProgress: (progress: number) => void;
+  /**
+   * Resolves when `openDurationMs` has elapsed (phase leaves `opening`).
+   * Use before any work that changes what the player can still see under the View.
+   */
+  waitForOpen: () => Promise<void>;
+};
+
+/**
+ * One ViewModel aggregates every async step of a user-visible load
+ * (cleanup scene, load scene, config, user data, mandatory assets, …).
+ */
+export type LoadingViewTask = {
+  id: string;
+  weight?: number;
+  /**
+   * When true, ViewModel delays `run` until open finishes.
+   * Required for cleanup / start / layout swaps that would flash under an opening View.
+   */
+  afterOpen?: boolean;
+  run: (context: LoadingViewTaskContext) => Promise<void> | void;
+};
+
+export type LoadingViewState = {
+  phase: LoadingPhase;
+  description?: string;
+  /**
+   * Weighted real progress. Capped at 0.99 until every task settles; then 1.
+   */
+  actualProgress: number;
+  /** min(actualProgress, elapsedVisible / minimumVisibleMs). */
+  displayedProgress: number;
+  error?: unknown;
+};

package/plugins/phaser-casual-game-factory/templates/motion/index.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './phaser-ui-motion';

package/plugins/phaser-casual-game-factory/templates/motion/phaser-ui-motion.ts

@@ -0,0 +1,363 @@
+import * as Phaser from 'phaser';
+import type { ButtonMotionOptions, SliderMotionOptions } from './types';
+
+type ScaleTarget = Phaser.GameObjects.GameObject & { setScale(x: number, y?: number): unknown; scaleX: number; scaleY: number };
+
+type FillBackground = Phaser.GameObjects.Shape & {
+  fillColor: number;
+  fillAlpha: number;
+  setFillStyle(color: number, alpha?: number): unknown;
+};
+
+const SLIDER_DRAG_PX = 6;
+
+/**
+ * Attaches safe pointer animation. The accepted check deliberately uses the
+ * original unscaled hit size (not the pressed/shrunk visual), so a press cannot
+ * lose its click. Prefer this over ad-hoc hover tweens.
+ *
+ * When the visible chrome is `Graphics`, pass the hit rect as `background`
+ * (hover tint stays invisible) and set `scaleTarget` to the button `Container`.
+ *
+ * Press UX (Settings close / Home buttons): keep press scale while dragging
+ * outside; clear only on pointer release. Scene `POINTER_UP` is required because
+ * `pointerupoutside` on a hit child inside a scaled Container is unreliable.
+ */
+export function bindButtonMotion(
+  scene: Phaser.Scene,
+  hitArea: Phaser.GameObjects.Rectangle,
+  background: FillBackground,
+  options: ButtonMotionOptions = {},
+): { setEnabled(enabled: boolean): void; destroy(): void } {
+  const scaleTarget = (options.scaleTarget ?? hitArea) as ScaleTarget;
+  const disabledColor = options.disabledColor ?? 0x858585;
+  const normalColor = background.fillColor;
+  const backgroundAlpha = background.fillAlpha ?? 1;
+  const hoverColor = options.hoverColor ?? 0xffffff;
+  const hoverScale = options.hoverScale ?? 1.08;
+  const pressScale = options.pressScale ?? 0.9;
+  let enabled = true;
+  /** Active pointer id while a press started on this hit; null when idle. */
+  let activePointerId: number | null = null;
+  let capturedPointerId: number | null = null;
+
+  const kill = () => scene.tweens.killTweensOf(scaleTarget);
+  const scaleTo = (scale: number, ease: string) => {
+    kill();
+    scene.tweens.add({ targets: scaleTarget, scaleX: scale, scaleY: scale, duration: 150, ease });
+  };
+  const paintBg = (color: number) => background.setFillStyle(color, backgroundAlpha);
+  const resetVisual = () => {
+    paintBg(normalColor);
+    scaleTo(1, 'Back.out');
+  };
+
+  const canvas = () => scene.game.canvas as HTMLCanvasElement | undefined;
+
+  const releaseCapture = () => {
+    if (capturedPointerId == null) return;
+    try {
+      canvas()?.releasePointerCapture?.(capturedPointerId);
+    } catch {
+      /* ignore — capture may already be cleared */
+    }
+    capturedPointerId = null;
+  };
+
+  /** Unscaled hit test in world space (ignores press/hover scale on `scaleTarget`). */
+  const containsUnscaled = (pointer: Phaser.Input.Pointer): boolean => {
+    const bounds = hitArea.getBounds();
+    const sx = Math.max(0.001, Math.abs(scaleTarget.scaleX));
+    const sy = Math.max(0.001, Math.abs(scaleTarget.scaleY));
+    const hw = bounds.width / sx / 2;
+    const hh = bounds.height / sy / 2;
+    return Math.abs(pointer.worldX - bounds.centerX) <= hw && Math.abs(pointer.worldY - bounds.centerY) <= hh;
+  };
+
+  const finish = (pointer: Phaser.Input.Pointer, acceptedOverride?: boolean) => {
+    if (activePointerId == null || pointer.id !== activePointerId) return;
+    const accepted =
+      typeof acceptedOverride === 'boolean'
+        ? acceptedOverride
+        : enabled && containsUnscaled(pointer);
+    activePointerId = null;
+    releaseCapture();
+    resetVisual();
+    if (accepted) {
+      options.onClickSound?.();
+      options.onAccepted?.();
+    }
+  };
+
+  /** Release outside the game canvas never reaches scene POINTER_UP — finish here. */
+  const finishFromWindow = (event: PointerEvent) => {
+    if (activePointerId == null) return;
+    if (capturedPointerId != null && event.pointerId !== capturedPointerId) return;
+
+    const el = canvas();
+    let accepted = false;
+    if (el) {
+      const rect = el.getBoundingClientRect();
+      const insideCanvas =
+        event.clientX >= rect.left &&
+        event.clientX <= rect.right &&
+        event.clientY >= rect.top &&
+        event.clientY <= rect.bottom;
+      if (insideCanvas) {
+        const pointer =
+          scene.input.manager.pointers.find((p) => p.id === activePointerId) ??
+          scene.input.activePointer;
+        accepted = enabled && containsUnscaled(pointer);
+        finish(pointer, accepted);
+        return;
+      }
+    }
+
+    // Outside canvas: clear press tween, never accept click.
+    activePointerId = null;
+    releaseCapture();
+    resetVisual();
+  };
+
+  hitArea.setInteractive({ useHandCursor: true });
+
+  hitArea.on('pointerover', () => {
+    if (!enabled || activePointerId != null) return;
+    paintBg(hoverColor);
+    scaleTo(hoverScale, 'Expo.out');
+  });
+
+  hitArea.on('pointerout', () => {
+    // While pressed: keep press scale until release (Settings close / Home buttons).
+    if (!enabled || activePointerId != null) return;
+    resetVisual();
+  });
+
+  hitArea.on('pointerdown', (pointer: Phaser.Input.Pointer) => {
+    if (!enabled) return;
+    activePointerId = pointer.id;
+    scaleTo(pressScale, 'Expo.out');
+    // DOM Settings close keeps :active for the whole gesture via browser capture.
+    // Mirror that so Canvas still receives the matching pointerup after drag-off.
+    const domPointerId = pointer.event?.pointerId;
+    if (typeof domPointerId === 'number') {
+      try {
+        canvas()?.setPointerCapture?.(domPointerId);
+        capturedPointerId = domPointerId;
+      } catch {
+        capturedPointerId = null;
+      }
+    }
+  });
+
+  hitArea.on('pointerup', (pointer: Phaser.Input.Pointer) => finish(pointer));
+  hitArea.on('pointerupoutside', (pointer: Phaser.Input.Pointer) => finish(pointer));
+
+  /**
+   * Safety net: child hit inside a scaled Container often skips `pointerupoutside`.
+   * Always finish on any scene pointer up so press scale never sticks.
+   */
+  const onScenePointerUp = (pointer: Phaser.Input.Pointer) => finish(pointer);
+  scene.input.on(Phaser.Input.Events.POINTER_UP, onScenePointerUp);
+
+  // Release far outside the canvas (letterbox / off-game) skips Phaser input.
+  window.addEventListener('pointerup', finishFromWindow, true);
+  window.addEventListener('pointercancel', finishFromWindow, true);
+
+  return {
+    setEnabled(next) {
+      enabled = next;
+      activePointerId = null;
+      releaseCapture();
+      hitArea.disableInteractive();
+      if (next) {
+        paintBg(normalColor);
+        hitArea.setInteractive({ useHandCursor: true });
+      } else {
+        paintBg(disabledColor);
+        kill();
+        scaleTarget.setScale(1);
+      }
+    },
+    destroy() {
+      scene.input.off(Phaser.Input.Events.POINTER_UP, onScenePointerUp);
+      window.removeEventListener('pointerup', finishFromWindow, true);
+      window.removeEventListener('pointercancel', finishFromWindow, true);
+      releaseCapture();
+      kill();
+      hitArea.removeAllListeners();
+    },
+  };
+}
+
+export function tweenPopup(scene: Phaser.Scene, popup: Phaser.GameObjects.Container, open: boolean, done?: () => void): void {
+  scene.tweens.killTweensOf(popup);
+  if (open) {
+    popup.setVisible(true).setScale(0);
+    scene.tweens.add({ targets: popup, scale: 1, duration: 250, ease: 'Back.out', onComplete: done });
+  } else {
+    scene.tweens.add({
+      targets: popup,
+      scale: 0,
+      duration: 180,
+      ease: 'Expo.out',
+      onComplete: () => {
+        popup.setVisible(false);
+        done?.();
+      },
+    });
+  }
+}
+
+/**
+ * Visual slider. Drag = instant fill; click/tap seek = tween
+ * (`Back.out` up, `Expo.out` down). Programmatic `setProgress` follows the same rule.
+ */
+export function createSlider(scene: Phaser.Scene, x: number, y: number, width: number, options: SliderMotionOptions = {}) {
+  const track = scene.add.rectangle(x, y, width, 14, 0x353951).setOrigin(0, 0.5);
+  const fill = scene.add.rectangle(x, y, 0, 14, 0x8f82ff).setOrigin(0, 0.5);
+  let progress = Phaser.Math.Clamp(options.initialProgress ?? 0, 0, 1);
+  fill.width = width * progress;
+
+  const setProgress = (next: number, animate = true) => {
+    next = Phaser.Math.Clamp(next, 0, 1);
+    scene.tweens.killTweensOf(fill);
+    if (!animate) {
+      fill.width = width * next;
+      progress = next;
+      options.onChanged?.(next);
+      return;
+    }
+    const ease = next >= progress ? 'Back.out' : 'Expo.out';
+    scene.tweens.add({
+      targets: fill,
+      width: width * next,
+      duration: 260,
+      ease,
+      onUpdate: () => {
+        progress = width > 0 ? fill.width / width : next;
+        options.onChanged?.(progress);
+      },
+      onComplete: () => {
+        progress = next;
+        fill.width = width * next;
+        options.onChanged?.(next);
+      },
+    });
+  };
+
+  if (options.interactive) {
+    track.setInteractive({ useHandCursor: true });
+    let dragging = false;
+    let downX = 0;
+    /** Active pointer id while gesture started on this track; null when idle. */
+    let activePointerId: number | null = null;
+    let capturedPointerId: number | null = null;
+
+    const canvas = () => scene.game.canvas as HTMLCanvasElement | undefined;
+
+    const releaseCapture = () => {
+      if (capturedPointerId == null) return;
+      try {
+        canvas()?.releasePointerCapture?.(capturedPointerId);
+      } catch {
+        /* ignore */
+      }
+      capturedPointerId = null;
+    };
+
+    const progressFromPointer = (pointer: Phaser.Input.Pointer): number => {
+      const bounds = track.getBounds();
+      if (bounds.width <= 0) return progress;
+      return Phaser.Math.Clamp((pointer.worldX - bounds.x) / bounds.width, 0, 1);
+    };
+
+    const applyDrag = (pointer: Phaser.Input.Pointer): void => {
+      if (activePointerId == null || pointer.id !== activePointerId) return;
+      if (!pointer.isDown) return;
+      if (!dragging && Math.abs(pointer.worldX - downX) >= SLIDER_DRAG_PX) {
+        dragging = true;
+      }
+      if (dragging) setProgress(progressFromPointer(pointer), false);
+    };
+
+    const endPointer = (pointer: Phaser.Input.Pointer): void => {
+      if (activePointerId == null || pointer.id !== activePointerId) return;
+      const next = progressFromPointer(pointer);
+      if (dragging) setProgress(next, false);
+      else setProgress(next, true);
+      dragging = false;
+      activePointerId = null;
+      releaseCapture();
+    };
+
+    const endFromWindow = (event: PointerEvent): void => {
+      if (activePointerId == null) return;
+      if (capturedPointerId != null && event.pointerId !== capturedPointerId) return;
+      // Outside canvas: stop drag; keep last fill (no seek tween).
+      dragging = false;
+      activePointerId = null;
+      releaseCapture();
+    };
+
+    track.on('pointerdown', (pointer: Phaser.Input.Pointer) => {
+      activePointerId = pointer.id;
+      dragging = false;
+      downX = pointer.worldX;
+      options.onClickSound?.();
+      // Keep receiving move/up after drag leaves the thin track (same as buttons).
+      const domPointerId = pointer.event?.pointerId;
+      if (typeof domPointerId === 'number') {
+        try {
+          canvas()?.setPointerCapture?.(domPointerId);
+          capturedPointerId = domPointerId;
+        } catch {
+          capturedPointerId = null;
+        }
+      }
+    });
+
+    // Scene-level move/up: track `pointermove` dies outside the hit; panel sinks steal it.
+    const onSceneMove = (pointer: Phaser.Input.Pointer) => applyDrag(pointer);
+    const onSceneUp = (pointer: Phaser.Input.Pointer) => endPointer(pointer);
+    scene.input.on(Phaser.Input.Events.POINTER_MOVE, onSceneMove);
+    scene.input.on(Phaser.Input.Events.POINTER_UP, onSceneUp);
+
+    track.on('pointerup', endPointer);
+    track.on('pointerupoutside', endPointer);
+
+    window.addEventListener('pointerup', endFromWindow, true);
+    window.addEventListener('pointercancel', endFromWindow, true);
+
+    return {
+      track,
+      fill,
+      get progress() {
+        return progress;
+      },
+      setProgress,
+      destroy() {
+        scene.input.off(Phaser.Input.Events.POINTER_MOVE, onSceneMove);
+        scene.input.off(Phaser.Input.Events.POINTER_UP, onSceneUp);
+        window.removeEventListener('pointerup', endFromWindow, true);
+        window.removeEventListener('pointercancel', endFromWindow, true);
+        releaseCapture();
+        scene.tweens.killTweensOf(fill);
+        track.removeAllListeners();
+      },
+    };
+  }
+
+  return {
+    track,
+    fill,
+    get progress() {
+      return progress;
+    },
+    setProgress,
+    destroy() {
+      scene.tweens.killTweensOf(fill);
+      track.removeAllListeners();
+    },
+  };
+}

package/plugins/phaser-casual-game-factory/templates/motion/types.ts

@@ -0,0 +1,21 @@
+import type * as Phaser from 'phaser';
+
+/** Reusable interaction defaults for Phaser casual-game UI. */
+export type ButtonMotionOptions = {
+  disabledColor?: number;
+  hoverColor?: number;
+  hoverScale?: number;
+  pressScale?: number;
+  /** With an icon, only the icon scales by default. Without one, the whole button scales. */
+  scaleTarget?: Phaser.GameObjects.GameObject & { setScale(x: number, y?: number): unknown; scaleX: number; scaleY: number };
+  onAccepted?: () => void;
+  onClickSound?: () => void;
+};
+
+export type SliderMotionOptions = {
+  interactive?: boolean;
+  initialProgress?: number;
+  onChanged?: (progress: number) => void;
+  /** Shared UI click — once per pointer-down on an interactive slider. */
+  onClickSound?: () => void;
+};