第04章 - 核心契约与游戏生命周期

// packages/game-kit/src/contract.ts（节选）
export interface GameModule {
  manifest: GameManifest;
  mount(ctx: GameContext): Promise<void>;
  unmount(): Promise<void>;
  pause(): void;
  resume(): void;
}

export interface GameManifest {
  id: TaskId;
  title: string;
  version: string;
  template: TemplateId;
  designSize: { width: number; height: number };
  ageRange: [number, number];
}

export type Stars = 0 | 1 | 2 | 3;

export interface GameEventMap {
  'session:start': { at: number };
  'scene:enter': { scene: string };
  /** 做错/需要重来时发一次（不惩罚，只用于复盘与自动化观测） */
  'task:retry': { taskId: TaskId; step: string };
  'task:complete': {
    taskId: TaskId;
    stars: Stars;
    mistakes: number;
    correct: number;
    total: number;
    durationMs: number;
  };
  /** replay = 孩子点了「再玩一次」：外壳原地重开这一局，不用回任务页再找 */
  'session:exit': { reason: 'complete' | 'quit' | 'replay'; progress: number };
}

export interface PlatformServices {
  storage: ProgressStore;
  audio: AudioBus;
  lifecycle: LifecycleBus;
  telemetry: Telemetry;
  now(): number;
}

export interface AudioBus {
  unlock(): Promise<void>;
  play(key: SfxKey): void;
  tone(freq: number, durationMs: number): void;
  speak(text: string, locale: Locale): SpeechHandle;
  stopSpeech(): void;
  setMuted(muted: boolean): void;
  isMuted(): boolean;
}

export const SAVE_SCHEMA_VERSION = 1;

export interface SaveData {
  schemaVersion: number;
  updatedAt: number;
  pet: PetState;
  tasks: Record<TaskId, TaskProgress>;
  /** 只保留最近 30 天，避免存档无限增长 */
  days: Record<string, DayRecord>;
}

// packages/templates/src/defineGame.ts
export interface GameDefinition {
  manifest: GameManifest;
  /**
   * 这一局的场景编排。关卡脚本在构建期由 content:check 用模板 schema 校验，
   * 运行时不再跑 zod（否则 zod + 全部模板 schema 会进每个游戏 chunk）。
   */
  scenes: (ctx: GameContext) => Phaser.Types.Scenes.SceneType[];
}

export function defineGame(definition: GameDefinition): GameModule {
  let game: Phaser.Game | null = null;

  return {
    manifest: definition.manifest,

    async mount(ctx: GameContext): Promise<void> {
      game = createPhaserGame(ctx, { scenes: definition.scenes(ctx) });
    },

    async unmount(): Promise<void> {
      game?.destroy(true);
      game = null;
    },

    pause(): void {
      game?.loop.sleep();
    },

    resume(): void {
      game?.loop.wake();
    },
  };
}

// packages/phaser-kit/src/createGame.ts
export function createPhaserGame(ctx: GameContext, opts: CreateGameOptions): Phaser.Game {
  const { width, height } = ctx.manifest.designSize;
  return new Phaser.Game({
    type: Phaser.AUTO,
    parent: ctx.container,
    width,
    height,
    backgroundColor: THEME.ink,
    scale: {
      mode: Phaser.Scale.FIT,
      autoCenter: Phaser.Scale.CENTER_BOTH,
    },
    audio: { noAudio: true },
    scene: opts.scenes,
  });
}

export interface GameContext {
  container: HTMLElement;
  manifest: GameManifest;
  task: TaskDetail;
  services: PlatformServices;
  locale: Locale;
  reducedMotion: boolean;
  debug?: DebugOptions;
  /** 这个任务之前完成过没有（外壳从存档里读） */
  completedBefore: boolean;
  emit<K extends keyof GameEventMap>(type: K, payload: GameEventMap[K]): void;
  requestExit(reason?: 'quit' | 'replay'): void;
}

export async function createGameContext(
  manifest: GameManifest,
  container: HTMLElement,
  hooks: GameHostHooks,
  completedBefore: boolean,
  locale: Locale,
): Promise<GameContext> {
  const task = await loadTask(manifest.id, locale);
  if (!task) throw new Error('找不到玩法内容：' + manifest.id);

  return {
    container,
    manifest,
    task,
    services: platform,
    locale,
    reducedMotion: window.matchMedia('(prefers-reduced-motion: reduce)').matches,
    debug: readDebugOptions(),
    completedBefore,
    emit(type, payload) {
      platform.telemetry.track(type, payload);
      recordDebugEvent(type, detailOf(type, payload));
      hooks.onEvent(type, payload);
    },
    requestExit(reason) {
      hooks.onExit(reason);
    },
  };
}

export interface GameHostHooks {
  onExit: (reason?: 'quit' | 'replay') => void;
  onEvent: <K extends keyof GameEventMap>(type: K, payload: GameEventMap[K]) => void;
}

// apps/site/src/registry.ts
export type GameLoader = () => Promise<{ default: GameModule }>;

export const registry: Record<TaskId, GameLoader> = {
  brush: () => import('@bamboo/game-daily/brush'),
  wash: () => import('@bamboo/game-daily/wash'),
  feed: () => import('@bamboo/game-daily/feed'),
  dress: () => import('@bamboo/game-daily/dress'),
  bath: () => import('@bamboo/game-daily/bath'),
  sleep: () => import('@bamboo/game-daily/sleep'),
  tidy: () => import('@bamboo/game-daily/tidy'),
  sport: () => import('@bamboo/game-daily/sport'),
  emotion: () => import('@bamboo/game-daily/emotion'),
  learn: () => import('@bamboo/game-daily/learn'),
};

// apps/site/src/views/PlayView.vue（节选）
const props = defineProps<{ taskId: TaskId }>();
const host = ref<HTMLDivElement | null>(null);
/** ★ 必须用 shallowRef：ref 会深度代理整个 Phaser 对象图 */
const mod = shallowRef<GameModule | null>(null);
let disposed = false;

async function start(): Promise<void> {
  if (disposed || !host.value) return;
  loading.value = true;
  try {
    // 先等读档完成，再挂游戏：深链直达时，秒通关的写入不能被旧快照盖掉
    await progress.init();
    const load = registry[props.taskId];
    if (!load) {
      error.value = t('play.notFound') + props.taskId;
      return;
    }
    const loaded = (await load()).default;
    if (disposed || !host.value) return;
    mod.value = loaded;
    const context = await createGameContext(
      loaded.manifest,
      host.value,
      { onExit: handleExit, onEvent: handleEvent },
      progress.completedBefore(props.taskId),
      locale.current,
    );
    if (disposed || !host.value) return;
    await loaded.mount(context);
    bindLifecycle();
  } catch (cause) {
    error.value = t('play.loadFailed');
    recordDebugError(cause instanceof Error ? cause.message : String(cause));
  } finally {
    loading.value = false;
  }
}

onBeforeUnmount(async () => {
  disposed = true;
  releaseLifecycle();
  platform.audio.stopSpeech();
  await mod.value?.unmount();
  mod.value = null;
});

protected finishTask(opts: CompletionOptions = {}): void {
  if (this.completionShown) return;
  this.completionShown = true;
  const stars = opts.stars ?? starsForSession(this.session);
  const durationMs = this.ctx.services.now() - this.session.startedAt;
  this.ctx.emit('task:complete', {
    taskId: this.ctx.manifest.id,
    stars,
    mistakes: this.session.mistakes,
    correct: this.session.correct,
    total: Math.max(this.session.total, 1),
    durationMs,
  });
  this.sfx('complete');
  if (!this.reducedMotion) this.cameras.main.flash(260, 255, 250, 220);
  this.showCompletionOverlay(stars, opts.praise ?? this.ctx.task.done);
  if (this.autoplay) {
    this.time.delayedCall(opts.autoExitMs ?? 450, () => this.exit('complete'));
  }
}

// apps/site/src/shell/debug.ts
export interface BambooDebugBridge {
  /** 事件序列：'session:start' / 'scene:enter:<scene>' / 'task:complete:<id>' … */
  events: string[];
  /** 最新存档快照（每次存档变化都换成一个新对象） */
  save: SaveData;
  /** 最近一次载入失败的技术详情 */
  lastError?: string;
}

const MAX_EVENTS = 600;

export function initDebugBridge(now = Date.now()): BambooDebugBridge {
  const w = window;
  if (!w.__bamboo) w.__bamboo = { events: [], save: emptySave(now) };
  return w.__bamboo;
}

export function recordDebugEvent(type: string, detail?: string): void {
  const bridge = initDebugBridge();
  bridge.events.push(detail ? type + ':' + detail : type);
  if (bridge.events.length > MAX_EVENTS) bridge.events.shift();
}

catch (cause) {
  error.value = t('play.loadFailed');           // 给孩子：一句人话 + 两个出口
  recordDebugError(cause instanceof Error ? cause.message : String(cause)); // 给自动化
  console.error('[bamboo] 玩法载入失败：' + props.taskId, cause);            // 给开发
}

// games/daily/src/games/brush.ts
import { getTaskSummary } from '@bamboo/content';
import { defineGame } from '@bamboo/templates/core';
import { DESIGN } from '@bamboo/templates/layout';
import { createScrubScene } from '@bamboo/templates/scrub';
import type { ScrubLevel } from '@bamboo/templates/scrub.logic';

const summary = getTaskSummary('brush')!;

/** 刷牙：房间、工具、目标点全部来自内容 JSON 的 levelScript */
export default defineGame({
  manifest: {
    id: 'brush',
    title: summary.title,
    version: '0.1.0',
    template: summary.template,
    designSize: { width: DESIGN.width, height: DESIGN.height },
    ageRange: summary.ageRange,
  },
  scenes: (ctx) => [createScrubScene(ctx, ctx.task.levelScript as ScrubLevel)],
});

// games/daily/src/games/learn.ts（节选）
const summary = getTaskSummary('learn');
if (!summary) throw new Error('缺少任务内容：learn');

export default defineGame({
  manifest: { id: 'learn', title: summary.title, version: '0.1.0', template: summary.template,
    designSize: { width: DESIGN.width, height: DESIGN.height }, ageRange: summary.ageRange },
  scenes: (ctx) => [createLearnScene(ctx, ctx.task.levelScript as LearnLevel)],
});