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

export interface GameManifest {
  id: string;                        // 'caochong-elephant'，与典故内容 id 一致
  title: string;                     // '曹冲称象'
  version: string;                   // semver，用于存档迁移
  template: TemplateId;              // 主玩法模板 id，用于筛选与展示
  orientation: 'portrait' | 'landscape';
  designSize: { width: number; height: number };   // 逻辑分辨率 750×1334
  ageRange: [number, number];        // [7, 10]
  sessionSeconds: [number, number];  // 单局时长 [150, 300]
  skills: string[];                  // ['观察', '等量代换', '浮力']
  curriculum: { dynasty: string; yearApprox?: number; figures: string[] };
  assets: { cover: string };         // 阶段 0 全部 'none'（无图片资源）
}

import type { GameManifest } from '@chags/game-kit';
import { DESIGN } from '@chags/templates';

export const manifest: GameManifest = {
  id: 'pangu',
  title: '盘古开天辟地',
  version: '0.1.0',
  template: 'grow',
  orientation: 'portrait',
  designSize: { width: DESIGN.width, height: DESIGN.height },
  ageRange: [7, 10],
  sessionSeconds: [150, 300],
  skills: ['想象', '坚持', '联想'],
  curriculum: { dynasty: '上古', yearApprox: -9999, figures: ['盘古'] },
  assets: { cover: 'none' },
};

export interface GameContext {
  container: HTMLElement;            // Vue 提供的挂载容器
  manifest: GameManifest;
  content: AllusionContent;          // ★ 已经是目标语言的翻译结果
  services: PlatformServices;        // 存档 / 音频 / 生命周期 / 分享 / 遥测
  locale: 'zh-CN' | 'en';            // 语音与格式化用
  reducedMotion: boolean;            // prefers-reduced-motion
  debug?: DebugOptions;              // ?autoplay=1&seed=... 解析结果
  emit<K extends keyof GameEventMap>(type: K, payload: GameEventMap[K]): void;
  requestExit(): void;               // 把控制权交还外壳
}

/** 唯一的平台出口：游戏不许直接碰 localStorage / fetch / wx.* */
export interface PlatformServices {
  storage: ProgressStore;         // Web: IndexedDB   | 小游戏: wx.setStorage
  audio: AudioBus;                // 含 iOS 解锁与静音策略
  lifecycle: LifecycleBus;        // 前后台切换、暂停
  share(opts: ShareOptions): Promise<void>;
  telemetry: Telemetry;           // 默认 no-op（本地缓冲，绝不上报个人信息）
  now(): number;
}

export interface ProgressStore {
  load(): Promise<SaveData>;
  save(data: SaveData): Promise<void>;
}

export interface AudioBus {
  unlock(): Promise<void>;                      // iOS / 微信必须由用户手势触发解锁
  play(key: SfxKey): void;                      // 六种合成音效
  tone(freq: number, durationMs: number): void; // 指定音高的一声（进度"听得见"）
  speak(text: string, locale: Locale): void;    // 旁白：按语言选嗓音
  stopSpeech(): void;
  setMuted(muted: boolean): void;
  isMuted(): boolean;
}

export interface LifecycleBus {
  onPause(cb: () => void): () => void;
  onResume(cb: () => void): () => void;
}

export interface Telemetry {
  track<K extends keyof GameEventMap>(type: K, payload: GameEventMap[K]): void;
  flush(): Promise<void>;
}

export interface GameEventMap {
  'session:start':  { at: number };
  'scene:enter':    { scene: string };
  'beat:enter':     { beatId: string };
  'choice:made':    { beatId: string; choiceId: string; correct: boolean; latencyMs: number };
  'hint:used':      { beatId: string; level: number };
  'level:complete': {
    levelId: string;
    stars: 0 | 1 | 2 | 3;
    mistakes: number;
    correct: number;
    total: number;
    durationMs: number;
  };
  'card:unlocked':  { allusionId: string; cardId: string };
  'session:exit':   { reason: 'complete' | 'quit' | 'background'; progress: number };
}

export interface GameModule {
  manifest: GameManifest;
  mount(ctx: GameContext): Promise<void>;   // 内部 new Phaser.Game(...)
  unmount(): Promise<void>;                 // 必须 game.destroy(true)，零全局残留
  pause(): void;
  resume(): void;
}

export interface GameDefinition {
  manifest: GameManifest;
  /** 分幕插图：每个典故自己画 */
  drawBeat?: (g, index, rect) => void;
  /** 玩法场景。拿到内容与一局状态，返回这一局的场景编排。 */
  gameplay: (ctx: GameContext, session: SessionState) => GameplayStage;
}

export interface GameplayStage {
  entry: string;                             // 分幕之后进入哪一幕
  scenes: Phaser.Types.Scenes.SceneType[];   // 中间的玩法场景（一到多个）
}

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

  return {
    manifest: definition.manifest,

    async mount(ctx) {
      const session = createSessionState(ctx.services.now());
      const stage = definition.gameplay(ctx, session);
      game = createPhaserGame(ctx, {
        scenes: [
          createStoryScene(ctx, {
            beats: ctx.content.story,
            nextSceneKey: stage.entry,
            drawBeat: definition.drawBeat,
          }),
          ...stage.scenes,
          createRewardScene(ctx, {
            allusionId: ctx.content.id,
            title: ctx.content.title,
            pinyin: ctx.content.pinyin,
            moral: ctx.content.moral,
            keywords: ctx.content.keywords,
            source: ctx.content.source,
            session,
          }),
        ],
      });
    },

    async unmount() {
      game?.destroy(true);
      game = null;
    },

    pause() { game?.loop.sleep(); },
    resume() { game?.loop.wake(); },
  };
}

// games/pangu/src/index.ts
export default defineGame({
  manifest,
  drawBeat,

  gameplay: (ctx, session) => ({
    entry: SCENE_KEYS.chaos,
    scenes: [
      // 开：连点蛋壳，混沌炸开（这个场景是盘古专属，不进模板库）
      createChaosScene(ctx, { nextSceneKey: SCENE_KEYS.tap, tapsToBreak: 4 }),
      // 撑：把天一点点顶上去，撑够一万八千年
      createTapScene(ctx, {
        level: tapLevel(ctx.content),
        session,
        nextSceneKey: SCENE_KEYS.place,
        titleKey: 'scene.hold',
        drawStage: drawHoldStage,
        drawFinale: drawHoldFinale,
      }),
      // 化：把自己一件件放回世界
      createPlaceScene(ctx, {
        level: placeLevel(ctx.content),
        session,
        nextSceneKey: SCENE_KEYS.reward,
        drawPiece,
        drawOrb,
        reveal: ctx.content.keyMoment.reveal,
      }),
    ],
  }),
});