@quybt93/pcgf 0.0.1

package/plugins/phaser-casual-game-factory/templates/phaser/scene-registration.ts

@@ -0,0 +1,28 @@
+import Phaser from 'phaser';
+import { SceneKeys } from './scene-keys';
+
+export interface CasualSceneConstructors {
+  boot: typeof Phaser.Scene;
+  home: typeof Phaser.Scene;
+  game: typeof Phaser.Scene;
+  /** Technical Loading View — register last so transitions can bringToTop. */
+  loadingOverlay?: typeof Phaser.Scene;
+}
+
+/**
+ * Register Boot, Home, Game (+ optional FactoryLoadingOverlay).
+ * Only Boot should auto-start; Home/Game start via LoadingView tasks.
+ */
+export function createCasualSceneList(
+  scenes: CasualSceneConstructors,
+): Phaser.Types.Scenes.SceneType[] {
+  const sceneList: Phaser.Types.Scenes.SceneType[] = [
+    { key: SceneKeys.Boot, scene: scenes.boot },
+    { key: SceneKeys.Home, scene: scenes.home },
+    { key: SceneKeys.Game, scene: scenes.game },
+  ];
+  if (scenes.loadingOverlay) {
+    sceneList.push({ key: SceneKeys.LoadingOverlay, scene: scenes.loadingOverlay });
+  }
+  return sceneList;
+}

package/plugins/phaser-casual-game-factory/templates/phaser/system-time-adapter.ts

@@ -0,0 +1,33 @@
+import type { Clock, TimeService } from '../core/time';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export class SystemClock implements Clock {
+  now(): number {
+    return Date.now();
+  }
+}
+
+export class LocalTimeAdapter implements TimeService {
+  constructor(private readonly clock: Clock = new SystemClock()) {}
+
+  now(): number {
+    return this.clock.now();
+  }
+
+  todayKey(): string {
+    const date = new Date(this.now());
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+  }
+
+  diffMs(from: number, to: number): number {
+    return to - from;
+  }
+
+  diffDays(from: number, to: number): number {
+    return Math.floor(this.diffMs(from, to) / DAY_MS);
+  }
+}

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

@@ -0,0 +1,2 @@
+export * from '../core/time';
+export * from './time-service';

package/plugins/phaser-casual-game-factory/templates/time/time-service.ts

@@ -0,0 +1,184 @@
+import type { EventBus, GameEventMap } from '../core/events';
+import type {
+  CalendarSnapshot,
+  ServerTimeFetcher,
+  TimeBoundaryPayload,
+  TimeIntervalPayload,
+  ManagedTimeService,
+  TimeServiceConfig,
+  TimeSource,
+} from '../core/time';
+import type { Unsubscribe } from '../core/types';
+
+type TimeEventMap = {
+  'new-minute': TimeBoundaryPayload;
+  'new-hour': TimeBoundaryPayload;
+  'new-day': TimeBoundaryPayload;
+  'new-week': TimeBoundaryPayload;
+  'new-month': TimeBoundaryPayload;
+  interval: TimeIntervalPayload;
+};
+
+type TimeEventName = keyof TimeEventMap;
+
+export class LocalTimeSource implements TimeSource {
+  readonly kind = 'local' as const;
+
+  now(): number {
+    return Date.now();
+  }
+}
+
+/**
+ * Keeps a locally advancing clock corrected by the latest server response.
+ * Call sync() at app boot/resume, then pass this source to DefaultTimeService.
+ */
+export class ServerTimeSource implements TimeSource {
+  readonly kind = 'server' as const;
+  private offsetMs = 0;
+
+  constructor(
+    private readonly fetchServerTime: ServerTimeFetcher,
+    private readonly localSource: TimeSource = new LocalTimeSource(),
+  ) {}
+
+  now(): number {
+    return this.localSource.now() + this.offsetMs;
+  }
+
+  async sync(): Promise<number> {
+    const response = await this.fetchServerTime();
+    if (!Number.isFinite(response.unixMs)) {
+      throw new Error('Server time response must contain a finite unixMs value.');
+    }
+    this.offsetMs = response.unixMs - this.localSource.now();
+    return this.now();
+  }
+}
+
+export class DefaultTimeService implements ManagedTimeService {
+  private readonly timeZone: string;
+  private readonly weekStartsOn: number;
+  private readonly defaultPollIntervalMs: number;
+  private readonly listeners = new Map<TimeEventName, Set<(payload: never) => void>>();
+  private readonly intervalListeners = new Map<number, Set<(payload: TimeIntervalPayload) => void>>();
+  private lastSnapshot?: CalendarSnapshot;
+  private pollTimer?: ReturnType<typeof setInterval>;
+
+  constructor(
+    private readonly source: TimeSource = new LocalTimeSource(),
+    config: TimeServiceConfig = {},
+    private readonly events?: EventBus<GameEventMap>,
+  ) {
+    this.timeZone = config.timeZone ?? 'UTC';
+    this.weekStartsOn = config.weekStartsOn ?? 1;
+    this.defaultPollIntervalMs = config.pollIntervalMs ?? 30_000;
+    if (!Number.isInteger(this.weekStartsOn) || this.weekStartsOn < 0 || this.weekStartsOn > 6) {
+      throw new Error('weekStartsOn must be an integer from 0 (Sunday) to 6 (Saturday).');
+    }
+    if (!Number.isFinite(this.defaultPollIntervalMs) || this.defaultPollIntervalMs < 1_000) {
+      throw new Error('pollIntervalMs must be at least 1000ms.');
+    }
+  }
+
+  now(): number { return this.source.now(); }
+
+  todayKey(): string { return this.snapshot().dayKey; }
+
+  diffMs(from: number, to: number): number { return to - from; }
+
+  diffDays(from: number, to: number): number {
+    return Math.floor(this.diffMs(from, to) / (24 * 60 * 60 * 1000));
+  }
+
+  snapshot(timestamp = this.now()): CalendarSnapshot {
+    const parts = new Intl.DateTimeFormat('en-CA', {
+      timeZone: this.timeZone,
+      year: 'numeric', month: '2-digit', day: '2-digit',
+      hour: '2-digit', minute: '2-digit', hourCycle: 'h23',
+    }).formatToParts(new Date(timestamp));
+    const read = (name: string) => parts.find((part) => part.type === name)?.value ?? '';
+    const year = read('year');
+    const month = read('month');
+    const day = read('day');
+    const hour = read('hour');
+    const minute = read('minute');
+    const dayKey = `${year}-${month}-${day}`;
+    const dayUtc = new Date(Date.UTC(Number(year), Number(month) - 1, Number(day)));
+    const shift = (dayUtc.getUTCDay() - this.weekStartsOn + 7) % 7;
+    dayUtc.setUTCDate(dayUtc.getUTCDate() - shift);
+    const weekKey = dayUtc.toISOString().slice(0, 10);
+    return {
+      timestamp,
+      minuteKey: `${dayKey}T${hour}:${minute}`,
+      hourKey: `${dayKey}T${hour}`,
+      dayKey,
+      weekKey,
+      monthKey: `${year}-${month}`,
+    };
+  }
+
+  on<Event extends TimeEventName>(event: Event, listener: (payload: TimeEventMap[Event]) => void): Unsubscribe {
+    const entries = this.listeners.get(event) ?? new Set<(payload: never) => void>();
+    entries.add(listener as (payload: never) => void);
+    this.listeners.set(event, entries);
+    return () => entries.delete(listener as (payload: never) => void);
+  }
+
+  onEveryMinutes(intervalMinutes: number, listener: (payload: TimeIntervalPayload) => void): Unsubscribe {
+    if (!Number.isInteger(intervalMinutes) || intervalMinutes <= 0) {
+      throw new Error('intervalMinutes must be a positive integer.');
+    }
+    const entries = this.intervalListeners.get(intervalMinutes) ?? new Set<(payload: TimeIntervalPayload) => void>();
+    entries.add(listener);
+    this.intervalListeners.set(intervalMinutes, entries);
+    return () => entries.delete(listener);
+  }
+
+  /** Establishes the first checkpoint, or emits every boundary crossed since the prior tick. */
+  tick(): CalendarSnapshot {
+    const current = this.snapshot();
+    const previous = this.lastSnapshot;
+    this.lastSnapshot = current;
+    if (!previous) return current;
+    const payload = { previous, current };
+    if (previous.minuteKey !== current.minuteKey) this.emit('new-minute', payload, 'time:new-minute');
+    if (previous.hourKey !== current.hourKey) this.emit('new-hour', payload, 'time:new-hour');
+    if (previous.dayKey !== current.dayKey) this.emit('new-day', payload, 'time:new-day');
+    if (previous.weekKey !== current.weekKey) this.emit('new-week', payload, 'time:new-week');
+    if (previous.monthKey !== current.monthKey) this.emit('new-month', payload, 'time:new-month');
+    for (const [intervalMinutes, listeners] of this.intervalListeners) {
+      const previousBucket = Math.floor(previous.timestamp / (intervalMinutes * 60_000));
+      const currentBucket = Math.floor(current.timestamp / (intervalMinutes * 60_000));
+      if (previousBucket !== currentBucket) {
+        const intervalPayload = { intervalMinutes, previousBucket, currentBucket, timestamp: current.timestamp };
+        for (const listener of listeners) listener(intervalPayload);
+        this.events?.emit('time:interval', intervalPayload);
+      }
+    }
+    return current;
+  }
+
+  startPolling(intervalMs = this.defaultPollIntervalMs): void {
+    if (!Number.isFinite(intervalMs) || intervalMs < 1_000) throw new Error('Polling interval must be at least 1000ms.');
+    this.stopPolling();
+    this.tick();
+    this.pollTimer = setInterval(() => this.tick(), intervalMs);
+  }
+
+  stopPolling(): void {
+    if (this.pollTimer) clearInterval(this.pollTimer);
+    this.pollTimer = undefined;
+  }
+
+  dispose(): void {
+    this.stopPolling();
+    this.listeners.clear();
+    this.intervalListeners.clear();
+  }
+
+  private emit<Event extends TimeEventName>(event: Event, payload: TimeEventMap[Event], globalEvent: keyof GameEventMap): void {
+    for (const listener of this.listeners.get(event) ?? []) (listener as (value: TimeEventMap[Event]) => void)(payload);
+    this.events?.emit(globalEvent, payload as never);
+  }
+}

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

@@ -0,0 +1,148 @@
+/**
+ * Shared SFX / Music volume (0–1), persisted in localStorage.
+ * SFX scales UI click/close. Music drives a soft demo pad (no BGM asset required).
+ */
+
+const STORAGE_KEY = 'pcgf.audio-settings.v1';
+
+export type AudioSettingsState = {
+  sfx: number;
+  music: number;
+};
+
+const DEFAULTS: AudioSettingsState = { sfx: 0.8, music: 0.5 };
+
+let state: AudioSettingsState = load();
+let musicPad: DemoMusicPad | undefined;
+const listeners = new Set<(next: AudioSettingsState) => void>();
+
+function clamp01(value: number): number {
+  return Math.max(0, Math.min(1, value));
+}
+
+function load(): AudioSettingsState {
+  try {
+    const raw = globalThis.localStorage?.getItem(STORAGE_KEY);
+    if (!raw) return { ...DEFAULTS };
+    const parsed = JSON.parse(raw) as Partial<AudioSettingsState>;
+    return {
+      sfx: clamp01(typeof parsed.sfx === 'number' ? parsed.sfx : DEFAULTS.sfx),
+      music: clamp01(typeof parsed.music === 'number' ? parsed.music : DEFAULTS.music),
+    };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+function persist(): void {
+  try {
+    globalThis.localStorage?.setItem(STORAGE_KEY, JSON.stringify(state));
+  } catch {
+    /* private mode */
+  }
+}
+
+function emit(): void {
+  for (const listener of listeners) listener({ ...state });
+}
+
+export function getAudioSettings(): AudioSettingsState {
+  return { ...state };
+}
+
+export function getSfxVolume(): number {
+  return state.sfx;
+}
+
+export function getMusicVolume(): number {
+  return state.music;
+}
+
+export function setSfxVolume(value: number): void {
+  state = { ...state, sfx: clamp01(value) };
+  persist();
+  emit();
+}
+
+export function setMusicVolume(value: number): void {
+  state = { ...state, music: clamp01(value) };
+  persist();
+  ensureMusicPad().setVolume(state.music);
+  emit();
+}
+
+export function subscribeAudioSettings(listener: (next: AudioSettingsState) => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** Call once after first user gesture so the demo music pad can start. */
+export function unlockAudioSettings(): void {
+  ensureMusicPad().unlock();
+  ensureMusicPad().setVolume(state.music);
+}
+
+function ensureMusicPad(): DemoMusicPad {
+  if (!musicPad) musicPad = new DemoMusicPad();
+  return musicPad;
+}
+
+/**
+ * Soft sine pad so Music slider is audible without a BGM file.
+ * Stops when volume is 0.
+ */
+class DemoMusicPad {
+  private ctx: AudioContext | undefined;
+  private gain: GainNode | undefined;
+  private osc: OscillatorNode | undefined;
+  private started = false;
+
+  unlock(): void {
+    const Ctx = globalThis.AudioContext || (globalThis as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext;
+    if (!Ctx) return;
+    if (!this.ctx) this.ctx = new Ctx();
+    void this.ctx.resume();
+  }
+
+  setVolume(volume01: number): void {
+    const volume = clamp01(volume01);
+    this.unlock();
+    if (!this.ctx) return;
+
+    if (volume <= 0.001) {
+      this.stopOsc();
+      return;
+    }
+
+    if (!this.gain) {
+      this.gain = this.ctx.createGain();
+      this.gain.connect(this.ctx.destination);
+    }
+    this.gain.gain.setTargetAtTime(volume * 0.045, this.ctx.currentTime, 0.05);
+
+    if (!this.started) {
+      this.osc = this.ctx.createOscillator();
+      this.osc.type = 'sine';
+      this.osc.frequency.value = 110;
+      this.osc.connect(this.gain);
+      this.osc.start();
+      this.started = true;
+    }
+  }
+
+  private stopOsc(): void {
+    if (this.osc) {
+      try {
+        this.osc.stop();
+      } catch {
+        /* already stopped */
+      }
+      this.osc.disconnect();
+      this.osc = undefined;
+    }
+    this.started = false;
+    if (this.gain && this.ctx) {
+      this.gain.gain.setTargetAtTime(0, this.ctx.currentTime, 0.05);
+    }
+  }
+}

package/plugins/phaser-casual-game-factory/templates/ui/bind-factory-dom-press.ts

@@ -0,0 +1,108 @@
+/**
+ * DOM cream-button press: keep pressed visual until pointer **release**,
+ * even after drag-off (Settings close / phaser-ui-motion contract).
+ * Uses class `.is-pressed` (see factory-cream-casual.css) + setPointerCapture.
+ *
+ * @see skills/theme-cream-casual/SKILL.md
+ * @see skills/phaser-ui-motion/SKILL.md
+ */
+
+const PRESSED = 'is-pressed';
+
+export type BindFactoryDomPressOptions = {
+  /** Root to query (default document). */
+  root?: ParentNode;
+  /**
+   * Selector for pressable controls.
+   * Default: product chrome buttons under .factory-page / .factory-ui, plus factory-* / modal-close.
+   * Excludes Test tools FAB/panel and param-group toggles.
+   */
+  selector?: string;
+};
+
+const DEFAULT_SELECTOR = [
+  '.factory-page button',
+  '.factory-ui button',
+  'button.factory-button',
+  'button.factory-button-primary',
+  'button.factory-button-gold',
+  'button.factory-button-hot',
+  'button.factory-button-danger',
+  'button.factory-button-surface',
+  'button.factory-close',
+  'button.modal-close',
+].join(', ');
+
+const SKIP_CLOSEST =
+  '#tools-fab, .tools-fab, .tool-panel, .anim-group-toggle, .tool-param-group-toggle, .tool-section-toggle';
+
+function shouldSkip(el: Element): boolean {
+  if (el.closest(SKIP_CLOSEST)) return true;
+  if (el instanceof HTMLButtonElement && el.disabled) return true;
+  if (el.getAttribute('aria-disabled') === 'true') return true;
+  return false;
+}
+
+/**
+ * Bind press-held-until-release on cream DOM buttons.
+ * Call once after DOM ready (and after dynamic buttons are inserted, or re-call).
+ */
+export function bindFactoryDomPress(
+  options: BindFactoryDomPressOptions = {},
+): { destroy: () => void } {
+  const root = options.root ?? (typeof document !== 'undefined' ? document : null);
+  if (!root) return { destroy: () => undefined };
+
+  const selector = options.selector ?? DEFAULT_SELECTOR;
+  const active = new Map<number, HTMLElement>();
+
+  const clear = (pointerId: number) => {
+    const el = active.get(pointerId);
+    if (!el) return;
+    el.classList.remove(PRESSED);
+    active.delete(pointerId);
+    try {
+      if (el.hasPointerCapture?.(pointerId)) el.releasePointerCapture(pointerId);
+    } catch {
+      /* ignore */
+    }
+  };
+
+  const onPointerDown = (event: Event) => {
+    const e = event as PointerEvent;
+    if (e.button != null && e.button !== 0) return;
+    const target = e.target;
+    if (!(target instanceof Element)) return;
+    const btn = target.closest(selector);
+    if (!(btn instanceof HTMLElement) || shouldSkip(btn)) return;
+
+    active.set(e.pointerId, btn);
+    btn.classList.add(PRESSED);
+    try {
+      btn.setPointerCapture(e.pointerId);
+    } catch {
+      /* ignore */
+    }
+  };
+
+  // Capture on window so release outside the Phaser canvas / letterbox still clears press.
+  const onPointerUp = (event: Event) => {
+    const e = event as PointerEvent;
+    clear(e.pointerId);
+  };
+
+  root.addEventListener('pointerdown', onPointerDown, true);
+  window.addEventListener('pointerup', onPointerUp, true);
+  window.addEventListener('pointercancel', onPointerUp, true);
+  window.addEventListener('lostpointercapture', onPointerUp, true);
+
+  return {
+    destroy: () => {
+      root.removeEventListener('pointerdown', onPointerDown, true);
+      window.removeEventListener('pointerup', onPointerUp, true);
+      window.removeEventListener('pointercancel', onPointerUp, true);
+      window.removeEventListener('lostpointercapture', onPointerUp, true);
+      for (const id of [...active.keys()]) clear(id);
+    },
+  };
+}