@zhin.js/plugin-text-adventure 1.0.0

package/src/profile-service.ts

@@ -0,0 +1,151 @@
+import type { Database, Models, RelatedModel } from 'zhin.js';
+import { evaluateAchievements, type AchievementContext } from './achievements.js';
+import type { AdvModelName, AdvProfileRow } from './models.js';
+import { parseStringSet, serializeStringSet } from './profile-parse.js';
+import { playableSceneIds } from './story-catalog.js';
+import type { AdvDatabase } from './session-service.js';
+
+const PLAYABLE = new Set(playableSceneIds());
+
+type AdvModel<K extends AdvModelName> = RelatedModel<unknown, Models, K>;
+
+function getModel<K extends AdvModelName>(db: AdvDatabase, name: K): AdvModel<K> {
+  const model = db.models.get(name);
+  if (!model) throw new Error(`Model ${name} is not registered`);
+  return model as AdvModel<K>;
+}
+
+export class ProfileService {
+  constructor(private readonly db: AdvDatabase) {}
+
+  async get(playerId: string): Promise<AdvProfileRow | null> {
+    return getModel(this.db, 'adv_profiles').findOne({ player_id: playerId });
+  }
+
+  async getOrCreate(playerId: string, playerName: string): Promise<AdvProfileRow> {
+    const existing = await this.get(playerId);
+    if (existing) {
+      if (playerName && existing.player_name !== playerName) {
+        await this.patch(playerId, { player_name: playerName });
+        return (await this.get(playerId))!;
+      }
+      return existing;
+    }
+    const now = Date.now();
+    const row: AdvProfileRow = {
+      player_id: playerId,
+      player_name: playerName || playerId,
+      visited_scenes: '[]',
+      endings_seen: '[]',
+      items_found: '[]',
+      achievements: '[]',
+      runs_started: 0,
+      runs_completed: 0,
+      total_steps: 0,
+      best_step_count: 0,
+      updated_at: now,
+      created_at: now,
+    };
+    await getModel(this.db, 'adv_profiles').create(row);
+    return row;
+  }
+
+  async patch(playerId: string, patch: Partial<AdvProfileRow>): Promise<void> {
+    await getModel(this.db, 'adv_profiles').updateWhere(
+      { player_id: playerId },
+      { ...patch, updated_at: Date.now() },
+    );
+  }
+
+  async onRunStarted(playerId: string, playerName: string): Promise<AdvProfileRow> {
+    const profile = await this.getOrCreate(playerId, playerName);
+    await this.patch(playerId, { runs_started: profile.runs_started + 1 });
+    return (await this.get(playerId))!;
+  }
+
+  /** 记录进入场景、步数、背包变化；返回新解锁成就 ID */
+  async onStep(
+    playerId: string,
+    playerName: string,
+    sceneId: string,
+    inventory: string[],
+  ): Promise<string[]> {
+    const profile = await this.getOrCreate(playerId, playerName);
+    const visited = parseStringSet(profile.visited_scenes);
+    const items = parseStringSet(profile.items_found);
+    let changed = false;
+    if (PLAYABLE.has(sceneId) && !visited.has(sceneId)) {
+      visited.add(sceneId);
+      changed = true;
+    }
+    for (const item of inventory) {
+      if (!items.has(item)) {
+        items.add(item);
+        changed = true;
+      }
+    }
+    const patch: Partial<AdvProfileRow> = {
+      total_steps: profile.total_steps + 1,
+    };
+    if (changed) {
+      patch.visited_scenes = serializeStringSet(visited);
+      patch.items_found = serializeStringSet(items);
+    }
+    await this.patch(playerId, patch);
+    const updated = (await this.get(playerId))!;
+    return this.unlockPending(updated);
+  }
+
+  /** 局终：记录结局、完成数、最佳步数 */
+  async onRunCompleted(
+    playerId: string,
+    playerName: string,
+    endingId: string,
+    stepCount: number,
+    inventory: string[],
+  ): Promise<string[]> {
+    const profile = await this.getOrCreate(playerId, playerName);
+    const endings = parseStringSet(profile.endings_seen);
+    const items = parseStringSet(profile.items_found);
+    if (endingId) endings.add(endingId);
+    for (const item of inventory) items.add(item);
+
+    await this.patch(playerId, {
+      endings_seen: serializeStringSet(endings),
+      items_found: serializeStringSet(items),
+      runs_completed: profile.runs_completed + 1,
+      best_step_count: Math.max(profile.best_step_count, stepCount),
+    });
+
+    const updated = (await this.get(playerId))!;
+    return this.unlockPending(updated, { stepCount, inventory, endingId });
+  }
+
+  private async unlockPending(
+    profile: AdvProfileRow,
+    lastRun?: AchievementContext['lastRun'],
+  ): Promise<string[]> {
+    const ctx: AchievementContext = {
+      visited: parseStringSet(profile.visited_scenes),
+      endings: parseStringSet(profile.endings_seen),
+      itemsFound: parseStringSet(profile.items_found),
+      runsCompleted: profile.runs_completed,
+      bestStepCount: profile.best_step_count,
+      lastRun,
+    };
+    const current = [...parseStringSet(profile.achievements)];
+    const newly = evaluateAchievements(current, ctx);
+    if (!newly.length) return [];
+
+    const merged = new Set(current);
+    for (const id of newly) merged.add(id);
+    await this.patch(profile.player_id, {
+      achievements: serializeStringSet(merged),
+    });
+    return newly;
+  }
+}
+
+export function createProfileService(db: AdvDatabase): ProfileService {
+  return new ProfileService(db);
+}

package/src/scene-view.ts

@@ -0,0 +1,46 @@
+import type { SendContent } from 'zhin.js';
+import { buildChoiceKeyboard } from '@zhin.js/game-shared';
+import type { AdvProfileRow, AdvSessionRow } from './models.js';
+import { formatProgressCompact } from './profile-format.js';
+import {
+  ADV_PREFIX,
+  getScene,
+  sceneNarrative,
+  stateFromSession,
+  visibleChoices,
+} from './story.js';
+
+export function buildSceneInteractive(
+  session: AdvSessionRow,
+  extraNarrative = '',
+  profile?: AdvProfileRow,
+): SendContent | null {
+  const scene = getScene(session.scene_id);
+  if (!scene) return null;
+
+  const state = stateFromSession(session);
+  const choices = visibleChoices(scene, state);
+  const terminal = scene.terminal || session.status !== 'active';
+
+  let narrative = sceneNarrative(scene, state);
+  if (profile && !terminal) {
+    narrative = `${formatProgressCompact(profile)}\n\n${narrative}`;
+  }
+  if (extraNarrative) {
+    narrative += extraNarrative;
+  }
+
+  return buildChoiceKeyboard({
+    gamePrefix: ADV_PREFIX,
+    sessionId: session.id,
+    narrative,
+    choices: choices.map((c) => ({
+      id: c.id,
+      label: c.label,
+      style: c.style,
+    })),
+    terminal,
+    buttonsPerRow: 2,
+    fallbackHint: '回复数字选择（仅编号）',
+  });
+}

package/src/session-service.ts

@@ -0,0 +1,113 @@
+import type { Database, DatabaseFeature, Message, Models, RelatedModel } from 'zhin.js';
+import { channelKey, generateSessionId } from '@zhin.js/game-shared';
+import type { AdvModelName, AdvSessionRow } from './models.js';
+import { createProfileService, ProfileService } from './profile-service.js';
+
+export type AdvDatabase = Database<unknown, Models, string>;
+type AdvModel<K extends AdvModelName> = RelatedModel<unknown, Models, K>;
+
+function getModel<K extends AdvModelName>(db: AdvDatabase, name: K): AdvModel<K> {
+  const model = db.models.get(name);
+  if (!model) throw new Error(`Model ${name} is not registered`);
+  return model as AdvModel<K>;
+}
+
+export interface GameServices {
+  sessions: SessionService;
+  profiles: ProfileService;
+}
+
+export class SessionService {
+  constructor(private readonly db: AdvDatabase) {}
+
+  async getActiveByChannel(channel: string): Promise<AdvSessionRow | null> {
+    const rows = await getModel(this.db, 'adv_sessions').findAll({
+      channel_key: channel,
+      status: 'active',
+    });
+    return rows[0] ?? null;
+  }
+
+  async getActiveForUser(channel: string, userId: string): Promise<AdvSessionRow | null> {
+    const row = await this.getActiveByChannel(channel);
+    if (!row || row.player_id !== userId) return null;
+    return row;
+  }
+
+  async getById(id: string): Promise<AdvSessionRow | null> {
+    return getModel(this.db, 'adv_sessions').findOne({ id });
+  }
+
+  async getActiveByBoardMessageId(messageId: string): Promise<AdvSessionRow | null> {
+    if (!messageId) return null;
+    const rows = await getModel(this.db, 'adv_sessions').findAll({ status: 'active' });
+    for (const row of rows) {
+      const stored = row.board_message_id;
+      if (!stored) continue;
+      if (stored === messageId) return row;
+      if (stored.endsWith(`:${messageId}`)) return row;
+      const tail = stored.split(':').pop();
+      if (tail && messageId.endsWith(tail)) return row;
+    }
+    return null;
+  }
+
+  async createSession(message: Message<any>): Promise<AdvSessionRow> {
+    const now = Date.now();
+    const id = generateSessionId();
+    const row: AdvSessionRow = {
+      id,
+      adapter: String(message.$adapter),
+      endpoint: message.$endpoint,
+      channel_type: message.$channel.type,
+      channel_id: message.$channel.id,
+      channel_key: channelKey(message),
+      player_id: message.$sender.id,
+      player_name: message.$sender.name?.trim() || message.$sender.id,
+      scene_id: 'start',
+      hp: 100,
+      inventory: '[]',
+      flags: '{}',
+      ending_id: '',
+      status: 'active',
+      board_message_id: '',
+      step_count: 0,
+      updated_at: now,
+      created_at: now,
+    };
+    await getModel(this.db, 'adv_sessions').create(row);
+    return row;
+  }
+
+  async updateSession(id: string, patch: Partial<AdvSessionRow>): Promise<void> {
+    await getModel(this.db, 'adv_sessions').updateWhere(
+      { id },
+      { ...patch, updated_at: Date.now() },
+    );
+  }
+
+  async abortStale(idleMs: number): Promise<number> {
+    const cutoff = Date.now() - idleMs;
+    const sessions = getModel(this.db, 'adv_sessions');
+    const rows = await sessions.findAll({ status: 'active' });
+    let n = 0;
+    for (const row of rows) {
+      if (row.updated_at < cutoff) {
+        await sessions.updateWhere({ id: row.id }, { status: 'aborted', updated_at: Date.now() });
+        n++;
+      }
+    }
+    return n;
+  }
+}
+
+export function createServices(db: AdvDatabase): GameServices {
+  return {
+    sessions: new SessionService(db),
+    profiles: createProfileService(db),
+  };
+}
+
+export function resolveGameDatabase(feature: DatabaseFeature): AdvDatabase {
+  return feature.db;
+}

package/src/story-catalog.ts

@@ -0,0 +1,110 @@
+import { SCENES } from './story-scenes.js';
+
+/** 区域中文名（用于地图 / 成就展示） */
+export const REGION_LABELS: Record<string, string> = {
+  start: '秘境入口',
+  rubble: '碎石廊',
+  watchtower: '瞭望石塔',
+  observatory: '星象台',
+  vine_path: '秘径',
+  corridor: '幽暗走廊',
+  mural_room: '铭文壁画',
+  whisper_gallery: '低语画廊',
+  spring: '精灵泉',
+  flooded_hall: '积水厅',
+  bell_tower: '钟楼',
+  garden: '古庭院',
+  greenhouse: '遗迹温室',
+  library: '尘封书库',
+  ember_forge: '锻炉间',
+  market_ruins: '废墟市集',
+  ghost_bridge: '冥河石桥',
+  crystal_cave: '晶洞',
+  moon_pool: '月池',
+  sunken_shrine: '水下沉殿',
+  depths: '墓穴岔口',
+  crypt_entry: '墓穴入口',
+  catacombs: '骸骨甬道',
+  ossuary: '龛室',
+  prison_cell: '囚室',
+  spider_nest: '蛛巢',
+  shadow_maze: '暗影迷宫',
+  sealed_gates: '封印密室',
+  vault: '宝藏前厅',
+  vault_open: '宝库',
+  throne_room: '王座厅',
+};
+
+export const ENDING_LABELS: Record<string, string> = {
+  treasure: '遗迹宝藏',
+  ascension: '星辉归位',
+  wisdom: '智者归途',
+  curse: '贪婪代价',
+  escape: '生还',
+  defeat: '陨落',
+  coward: '怯懦归途',
+  hermit: '庭院隐者',
+  redemption: '幽魂解脱',
+  drowned: '寒水沉眠',
+  spider: '茧中亡魂',
+  labyrinth: '迷宫迷失',
+  star_keeper: '星守誓约',
+  mask_king: '面具之王',
+  merchant: '行商结局',
+};
+
+/** 地图分区（便于 adv map 分组展示） */
+export const MAP_ZONES: Array<{ name: string; sceneIds: string[] }> = [
+  {
+    name: '入口与塔',
+    sceneIds: ['start', 'rubble', 'watchtower', 'observatory', 'vine_path'],
+  },
+  {
+    name: '主廊与泉',
+    sceneIds: ['corridor', 'mural_room', 'whisper_gallery', 'spring', 'flooded_hall', 'bell_tower'],
+  },
+  {
+    name: '庭院书库',
+    sceneIds: ['garden', 'greenhouse', 'library', 'ember_forge'],
+  },
+  {
+    name: '冥域水线',
+    sceneIds: ['market_ruins', 'ghost_bridge', 'crystal_cave', 'moon_pool', 'sunken_shrine'],
+  },
+  {
+    name: '墓穴深处',
+    sceneIds: [
+      'depths',
+      'crypt_entry',
+      'catacombs',
+      'ossuary',
+      'prison_cell',
+      'spider_nest',
+      'shadow_maze',
+      'sealed_gates',
+      'vault',
+      'vault_open',
+      'throne_room',
+    ],
+  },
+];
+
+export function playableSceneIds(): string[] {
+  return Object.values(SCENES)
+    .filter((s) => !s.terminal)
+    .map((s) => s.id);
+}
+
+export function endingIds(): string[] {
+  return Object.values(SCENES)
+    .filter((s) => s.terminal)
+    .map((s) => s.id);
+}
+
+export function regionLabel(id: string): string {
+  return REGION_LABELS[id] ?? ENDING_LABELS[id] ?? id;
+}
+
+export function endingLabel(id: string): string {
+  return ENDING_LABELS[id] ?? id;
+}

package/src/story-items.ts

@@ -0,0 +1,24 @@
+/** 15 种可收集道具 */
+export const ITEM_LABELS: Record<string, string> = {
+  torch: '火把',
+  key: '锈蚀钥匙',
+  gem: '幽蓝宝石',
+  herb: '荧光草药',
+  scroll: '残破卷轴',
+  amulet: '精灵护符',
+  silver_coin: '古银币',
+  rusted_blade: '生锈短剑',
+  moon_shard: '月华碎片',
+  elixir: '治愈灵药',
+  compass: '星象罗盘',
+  spirit_bell: '回音铃',
+  elf_feather: '银羽',
+  masquerade_mask: '仪式面具',
+  star_chart: '星图残页',
+};
+
+export const ITEM_IDS = Object.keys(ITEM_LABELS);
+
+export function itemLabel(id: string): string {
+  return ITEM_LABELS[id] ?? id;
+}

package/src/story-path.ts

@@ -0,0 +1,75 @@
+/**
+ * 估算最长可玩步数：允许往返同一场景（DFS + 深度上限）
+ */
+import type { GameState } from './story-types.js';
+import { SCENES } from './story-scenes.js';
+import { ITEM_IDS } from './story-items.js';
+import { resolveTransition } from './story-transitions.js';
+
+const OPTIMISTIC_FLAGS: Record<string, boolean> = {
+  spirit_met: true,
+  saw_map: true,
+  knows_sequence: true,
+  whisper_lore: true,
+  healed: true,
+  rested: true,
+  read_archive: true,
+  forged_blade: true,
+  amulet_upgraded: true,
+  moon_blessed: true,
+  shadow_banished: true,
+};
+
+function optimisticState(sceneId: string): GameState {
+  return {
+    sceneId,
+    hp: 100,
+    inventory: [...ITEM_IDS],
+    flags: { ...OPTIMISTIC_FLAGS },
+    endingId: '',
+  };
+}
+
+function visibleChoiceIds(state: GameState): string[] {
+  const scene = SCENES[state.sceneId];
+  if (!scene || scene.terminal) return [];
+  return scene.choices
+    .filter((c) => !c.requires || c.requires(state))
+    .map((c) => c.id);
+}
+
+/** 允许回路的最长路径（玩家可多次往返） */
+export function estimateLongestPlaythrough(maxDepth = 70): number {
+  let best = 0;
+  const memo = new Map<string, number>();
+
+  function walk(sceneId: string, depth: number): number {
+    if (depth >= maxDepth) return depth;
+    const key = `${sceneId}:${depth}`;
+    const cached = memo.get(key);
+    if (cached != null) return cached;
+
+    const scene = SCENES[sceneId];
+    if (scene?.terminal) {
+      best = Math.max(best, depth);
+      memo.set(key, depth);
+      return depth;
+    }
+
+    best = Math.max(best, depth);
+    let localBest = depth;
+    const state = optimisticState(sceneId);
+
+    for (const choiceId of visibleChoiceIds(state)) {
+      const result = resolveTransition(state, choiceId);
+      if (!result) continue;
+      localBest = Math.max(localBest, walk(result.nextSceneId, depth + 1));
+    }
+
+    memo.set(key, localBest);
+    return localBest;
+  }
+
+  walk('start', 0);
+  return best;
+}