@zhin.js/plugin-text-adventure 1.0.0

package/src/commands.ts

@@ -0,0 +1,133 @@
+import {
+  Message,
+  MessageCommand,
+  getActionFromMessage,
+  type Plugin,
+} from 'zhin.js';
+import {
+  buildChoiceFallbackMap,
+  channelKey,
+  normalizeAdvAction,
+  parseChoicePayload,
+  registerGameTextMiddleware,
+} from '@zhin.js/game-shared';
+import { runAdvCommand } from './adv-command.js';
+import { handleChoice } from './game-flow.js';
+import { ADV_PREFIX, getScene, stateFromSession, visibleChoices } from './story.js';
+import type { GameServices } from './session-service.js';
+
+function registerAdvPattern(
+  plugin: Plugin,
+  pattern: string,
+  desc: string,
+  getServices: () => GameServices | null,
+): void {
+  plugin.addCommand(
+    new MessageCommand(pattern)
+      .desc(desc)
+      .action(async (message, result) => {
+        const services = getServices();
+        if (!services) return '文字冒险需要启用 database 配置。';
+        const raw = (result.params.action as string | undefined) ?? '';
+        const action = normalizeAdvAction(raw);
+        return runAdvCommand(plugin, services, message, action);
+      }),
+  );
+}
+
+async function resolveAdvChoice(
+  message: Message<any>,
+  services: GameServices,
+): Promise<{ sessionId: string; choiceId: string } | null> {
+  const action = getActionFromMessage(message);
+  if (!action) return null;
+
+  const fromPayload = parseChoicePayload(action.payload, ADV_PREFIX);
+  if (fromPayload) {
+    return { sessionId: fromPayload.sessionId, choiceId: fromPayload.choiceId };
+  }
+
+  const choiceId = action.id || action.payload;
+  if (!choiceId) return null;
+
+  const ch = channelKey(message);
+  const session =
+    await services.sessions.getActiveForUser(ch, message.$sender.id)
+    ?? (action.sourceMessageId
+      ? await services.sessions.getActiveByBoardMessageId(action.sourceMessageId)
+      : null);
+  if (!session || session.channel_key !== ch) return null;
+
+  const scene = getScene(session.scene_id);
+  if (!scene) return null;
+  const state = stateFromSession(session);
+  const choices = visibleChoices(scene, state);
+  if (!choices.some((c) => c.id === choiceId)) return null;
+
+  return { sessionId: session.id, choiceId };
+}
+
+export function registerCommands(
+  plugin: Plugin,
+  getServices: () => GameServices | null,
+): void {
+  registerAdvPattern(plugin, 'adv [action:word]', '秘境探险（adv）', getServices);
+  registerAdvPattern(plugin, '冒险 [action:word]', '秘境探险（中文）', getServices);
+  registerAdvPattern(plugin, '秘境 [action:word]', '秘境探险（简称）', getServices);
+}
+
+async function handleAdvAction(
+  plugin: Plugin,
+  getServices: () => GameServices | null,
+  message: Message<any>,
+): Promise<boolean> {
+  const services = getServices();
+  if (!services) return false;
+  const choice = await resolveAdvChoice(message, services);
+  if (!choice) return false;
+  const err = await handleChoice(plugin, services, message, choice.sessionId, choice.choiceId);
+  if (err) await message.$reply?.(err);
+  return true;
+}
+
+export function registerInteractive(
+  plugin: Plugin,
+  getServices: () => GameServices | null,
+): void {
+  plugin.registerInteractiveHandler(`${ADV_PREFIX}:`, (message) =>
+    handleAdvAction(plugin, getServices, message),
+  );
+}
+
+export function registerTextFallback(
+  plugin: Plugin,
+  getServices: () => GameServices | null,
+): void {
+  registerGameTextMiddleware(plugin, async (message, next) => {
+    const services = getServices();
+    if (!services) return next();
+
+    const action = getActionFromMessage(message);
+    if (action?.payload.startsWith(`${ADV_PREFIX}:`)) return next();
+
+    const ch = channelKey(message);
+    const session = await services.sessions.getActiveForUser(ch, message.$sender.id);
+    if (!session) return next();
+
+    const raw = message.$raw?.trim() ?? '';
+    const n = /^(\d+)$/.exec(raw);
+    if (!n) return next();
+
+    const scene = getScene(session.scene_id);
+    if (!scene) return next();
+    const state = stateFromSession(session);
+    const choices = visibleChoices(scene, state);
+    const map = buildChoiceFallbackMap(ADV_PREFIX, session.id, choices);
+    const payload = map[n[1]!];
+    const parsed = payload ? parseChoicePayload(payload, ADV_PREFIX) : null;
+    if (!parsed || parsed.sessionId !== session.id) return next();
+
+    const err = await handleChoice(plugin, services, message, session.id, parsed.choiceId);
+    if (err) await message.$reply?.(err);
+  }, 'adv:text');
+}

package/src/game-flow.ts

@@ -0,0 +1,196 @@
+import type { Adapter, Message, Plugin } from 'zhin.js';
+import type { AdvProfileRow, AdvSessionRow } from './models.js';
+import { formatNewAchievements } from './profile-format.js';
+import { buildSceneInteractive } from './scene-view.js';
+import {
+  applyChoiceResult,
+  getScene,
+  resolveChoice,
+  stateFromSession,
+} from './story.js';
+import type { GameServices } from './session-service.js';
+
+export async function sendOrEditScene(
+  plugin: Plugin,
+  services: GameServices,
+  message: Message<any>,
+  session: AdvSessionRow,
+  extraNarrative = '',
+  profile?: AdvProfileRow,
+): Promise<string> {
+  const prof = profile
+    ?? await services.profiles.getOrCreate(session.player_id, session.player_name);
+  const content = buildSceneInteractive(session, extraNarrative, prof);
+  if (!content) {
+    return '场景数据异常，请 adv quit 后重新开始。';
+  }
+
+  const adapter = plugin.root.inject(message.$adapter) as Adapter;
+
+  if (session.board_message_id) {
+    const msgId = await adapter.editMessage({
+      messageId: session.board_message_id,
+      context: String(message.$adapter),
+      endpoint: message.$endpoint,
+      id: message.$channel.id,
+      type: message.$channel.type,
+      content,
+    });
+    if (msgId !== session.board_message_id) {
+      await services.sessions.updateSession(session.id, { board_message_id: msgId });
+    }
+    return msgId;
+  }
+
+  const msgId = await message.$reply?.(content);
+  if (msgId) {
+    await services.sessions.updateSession(session.id, { board_message_id: msgId });
+  }
+  return msgId ?? '';
+}
+
+export async function startAdventure(
+  plugin: Plugin,
+  services: GameServices,
+  message: Message<any>,
+): Promise<string | undefined> {
+  const ch = `${message.$adapter}-${message.$endpoint}-${message.$channel.type}:${message.$channel.id}`;
+  const active = await services.sessions.getActiveByChannel(ch);
+  if (active) {
+    if (active.player_id === message.$sender.id) {
+      return '你已有进行中的冒险。发送 adv continue 继续，或 adv quit 放弃。';
+    }
+    return `本频道已有玩家 ${active.player_name} 的冒险进行中。`;
+  }
+
+  await services.profiles.onRunStarted(message.$sender.id, message.$sender.name?.trim() || message.$sender.id);
+  const session = await services.sessions.createSession(message);
+  await services.profiles.onStep(
+    message.$sender.id,
+    session.player_name,
+    'start',
+    [],
+  );
+  await sendOrEditScene(plugin, services, message, session);
+  return undefined;
+}
+
+export async function handleChoice(
+  plugin: Plugin,
+  services: GameServices,
+  message: Message<any>,
+  sessionId: string,
+  choiceId: string,
+): Promise<string | null> {
+  const session = await services.sessions.getById(sessionId);
+  if (!session || session.status !== 'active') {
+    return '冒险不存在或已结束。';
+  }
+  if (session.player_id !== message.$sender.id) {
+    return '这是别人的冒险。';
+  }
+
+  const state = stateFromSession(session);
+  const scene = getScene(state.sceneId);
+  if (!scene) return '场景丢失，请 adv quit 后重新开始。';
+
+  if (scene.terminal && choiceId !== 'restart') {
+    return '本局已结束，请点击「再玩一次」或发送 adv start。';
+  }
+
+  if (choiceId === 'restart') {
+    await services.sessions.updateSession(session.id, {
+      scene_id: 'start',
+      hp: 100,
+      inventory: '[]',
+      flags: '{}',
+      ending_id: '',
+      status: 'active',
+      step_count: 0,
+      board_message_id: '',
+    });
+    const updated = (await services.sessions.getById(session.id))!;
+    await services.profiles.onStep(updated.player_id, updated.player_name, 'start', []);
+    await sendOrEditScene(plugin, services, message, updated);
+    return null;
+  }
+
+  const result = resolveChoice(state, choiceId);
+  if (!result) return '该选项不可用。';
+
+  const next = applyChoiceResult(state, result);
+  const nextScene = getScene(next.sceneId);
+  const completed = !!nextScene?.terminal || next.hp <= 0;
+
+  if (next.hp <= 0 && !nextScene?.terminal) {
+    next.sceneId = 'defeat';
+  }
+
+  const finalScene = getScene(next.sceneId);
+  const status = completed || finalScene?.terminal ? 'completed' : 'active';
+  const newStepCount = session.step_count + 1;
+
+  await services.sessions.updateSession(session.id, {
+    scene_id: next.sceneId,
+    hp: next.hp,
+    inventory: JSON.stringify(next.inventory),
+    flags: JSON.stringify(next.flags),
+    ending_id: next.endingId,
+    status,
+    step_count: newStepCount,
+  });
+
+  const endingId = next.endingId || (finalScene?.terminal ? next.sceneId : '');
+  let newAchievements = await services.profiles.onStep(
+    session.player_id,
+    session.player_name,
+    next.sceneId,
+    next.inventory,
+  );
+  if (status === 'completed') {
+    const more = await services.profiles.onRunCompleted(
+      session.player_id,
+      session.player_name,
+      endingId,
+      newStepCount,
+      next.inventory,
+    );
+    newAchievements = [...new Set([...newAchievements, ...more])];
+  }
+
+  const updated = (await services.sessions.getById(session.id))!;
+  const extra = formatNewAchievements(newAchievements);
+  await sendOrEditScene(plugin, services, message, updated, extra);
+  return null;
+}
+
+export async function continueAdventure(
+  plugin: Plugin,
+  services: GameServices,
+  message: Message<any>,
+): Promise<string> {
+  const session = await services.sessions.getActiveForUser(
+    `${message.$adapter}-${message.$endpoint}-${message.$channel.type}:${message.$channel.id}`,
+    message.$sender.id,
+  );
+  if (!session) return '你没有进行中的冒险，发送 adv start 开始。';
+  await sendOrEditScene(plugin, services, message, session);
+  return '已刷新当前场景。';
+}
+
+export function sessionSummary(session: AdvSessionRow): string {
+  const scene = getScene(session.scene_id);
+  const state = stateFromSession(session);
+  const items = state.inventory;
+  const lines = [
+    `冒险 ${session.id}`,
+    `玩家：${session.player_name}`,
+    `场景：${scene?.id ?? session.scene_id}`,
+    `生命：${session.hp}`,
+    `物品：${items.length ? items.join(', ') : '无'}`,
+    `步数：${session.step_count}`,
+    `状态：${session.status}`,
+  ];
+  if (session.ending_id) lines.push(`结局：${session.ending_id}`);
+  return lines.join('\n');
+}

package/src/hub-register.ts

@@ -0,0 +1,32 @@
+import { getPlugin } from 'zhin.js';
+import { ensureGameHubService } from '@zhin.js/game-shared';
+import { runAdvCommand, ADV_HELP } from './adv-command.js';
+import type { GameServices } from './session-service.js';
+
+export function registerAdvHub(getServices: () => GameServices | null): () => void {
+  const plugin = getPlugin();
+  ensureGameHubService(plugin);
+  return plugin.registerGame({
+    id: 'adv',
+    title: '秘境探险',
+    icon: '🗺️',
+    description: '文字冒险，31 区域 · 15 结局 · 成就收集',
+    commandPrefix: '冒险',
+    quickStart: '开始',
+    aliases: ['adv', '秘境'],
+    menus: [
+      { id: 'start', label: '🚪 开始冒险', style: 'primary' },
+      { id: 'continue', label: '🔄 继续冒险' },
+      { id: 'map', label: '🗺️ 探索进度' },
+      { id: 'achievements', label: '🏅 成就' },
+      { id: 'help', label: '📖 玩法说明' },
+    ],
+    runAction: async (actionId, ctx) => {
+      const services = getServices();
+      if (!services) return '文字冒险需要启用 database 配置。';
+      return runAdvCommand(ctx.plugin, services, ctx.message, actionId);
+    },
+  });
+}
+
+export { ADV_HELP };

package/src/index.ts

@@ -0,0 +1,47 @@
+/**
+ * @zhin.js/plugin-text-adventure — 交互式文字冒险
+ *
+ * ```yaml
+ * plugins:
+ *   - "@zhin.js/plugin-text-adventure"
+ * database:
+ *   dialect: sqlite
+ *   storage: ./data/zhin.db
+ * ```
+ */
+import { Cron, formatCompact, usePlugin, type DatabaseFeature } from 'zhin.js';
+import { registerModels } from './models.js';
+import {
+  createServices,
+  resolveGameDatabase,
+  type GameServices,
+} from './session-service.js';
+import { registerCommands, registerInteractive, registerTextFallback } from './commands.js';
+import { registerAdvHub } from './hub-register.js';
+
+const plugin = usePlugin();
+const { logger, useContext, addCron } = plugin;
+
+registerModels(plugin);
+
+let services: GameServices | null = null;
+
+useContext('database', (dbFeature: DatabaseFeature) => {
+  services = createServices(resolveGameDatabase(dbFeature));
+  logger.info(formatCompact({ 模块: '文字冒险', 数据模型: '已就绪' }));
+});
+
+registerAdvHub(() => services);
+registerCommands(plugin, () => services);
+registerInteractive(plugin, () => services);
+registerTextFallback(plugin, () => services);
+
+addCron(
+  new Cron('0 */15 * * * *', async () => {
+    if (!services) return;
+    const n = await services.sessions.abortStale(60 * 60 * 1000);
+    if (n > 0) logger.debug(formatCompact({ 文字冒险: '清理超时局', count: n }));
+  }),
+);
+
+logger.info(formatCompact({ 模块: '文字冒险', 状态: '已加载' }));

package/src/models.ts

@@ -0,0 +1,84 @@
+import type { Models, Plugin } from 'zhin.js';
+
+export type AdvSessionStatus = 'active' | 'completed' | 'aborted';
+
+declare module 'zhin.js' {
+  interface Models {
+    adv_sessions: {
+      id: string;
+      adapter: string;
+      endpoint: string;
+      channel_type: string;
+      channel_id: string;
+      channel_key: string;
+      player_id: string;
+      player_name: string;
+      scene_id: string;
+      hp: number;
+      inventory: string;
+      flags: string;
+      ending_id: string;
+      status: AdvSessionStatus;
+      board_message_id: string;
+      step_count: number;
+      updated_at: number;
+      created_at: number;
+    };
+    adv_profiles: {
+      player_id: string;
+      player_name: string;
+      visited_scenes: string;
+      endings_seen: string;
+      items_found: string;
+      achievements: string;
+      runs_started: number;
+      runs_completed: number;
+      total_steps: number;
+      best_step_count: number;
+      updated_at: number;
+      created_at: number;
+    };
+  }
+}
+
+export type AdvSessionRow = Models['adv_sessions'];
+export type AdvProfileRow = Models['adv_profiles'];
+export type AdvModelName = 'adv_sessions' | 'adv_profiles';
+
+export function registerModels(plugin: Plugin): void {
+  plugin.defineModel('adv_sessions', {
+    id: { type: 'text', primary: true },
+    adapter: { type: 'text', nullable: false },
+    endpoint: { type: 'text', nullable: false },
+    channel_type: { type: 'text', nullable: false },
+    channel_id: { type: 'text', nullable: false },
+    channel_key: { type: 'text', nullable: false },
+    player_id: { type: 'text', nullable: false },
+    player_name: { type: 'text', default: '' },
+    scene_id: { type: 'text', default: 'start' },
+    hp: { type: 'integer', default: 100 },
+    inventory: { type: 'text', default: '[]' },
+    flags: { type: 'text', default: '{}' },
+    ending_id: { type: 'text', default: '' },
+    status: { type: 'text', default: 'active' },
+    board_message_id: { type: 'text', default: '' },
+    step_count: { type: 'integer', default: 0 },
+    updated_at: { type: 'integer', default: 0 },
+    created_at: { type: 'integer', default: 0 },
+  });
+
+  plugin.defineModel('adv_profiles', {
+    player_id: { type: 'text', primary: true },
+    player_name: { type: 'text', default: '' },
+    visited_scenes: { type: 'text', default: '[]' },
+    endings_seen: { type: 'text', default: '[]' },
+    items_found: { type: 'text', default: '[]' },
+    achievements: { type: 'text', default: '[]' },
+    runs_started: { type: 'integer', default: 0 },
+    runs_completed: { type: 'integer', default: 0 },
+    total_steps: { type: 'integer', default: 0 },
+    best_step_count: { type: 'integer', default: 0 },
+    updated_at: { type: 'integer', default: 0 },
+    created_at: { type: 'integer', default: 0 },
+  });
+}

package/src/profile-format.ts

@@ -0,0 +1,76 @@
+import { achievementById, ACHIEVEMENTS, totalAchievements } from './achievements.js';
+import {
+  endingIds,
+  endingLabel,
+  MAP_ZONES,
+  playableSceneIds,
+  regionLabel,
+} from './story-catalog.js';
+import type { AdvProfileRow } from './models.js';
+import { parseStringSet } from './profile-parse.js';
+
+export function formatProgressCompact(profile: AdvProfileRow): string {
+  const visited = parseStringSet(profile.visited_scenes).size;
+  const endings = parseStringSet(profile.endings_seen).size;
+  const achievements = parseStringSet(profile.achievements).size;
+  const totalRegions = playableSceneIds().length;
+  const totalEndings = endingIds().length;
+  return `🗺️ ${visited}/${totalRegions}  ·  🎬 ${endings}/${totalEndings}  ·  🏅 ${achievements}/${totalAchievements()}`;
+}
+
+export function formatMapProgress(profile: AdvProfileRow): string {
+  const visited = parseStringSet(profile.visited_scenes);
+  const total = playableSceneIds().length;
+  const pct = total ? Math.round((visited.size / total) * 100) : 0;
+  const lines = [
+    `🗺️ **探索进度** ${visited.size}/${total}（${pct}%）`,
+    '',
+  ];
+
+  for (const zone of MAP_ZONES) {
+    const parts = zone.sceneIds.map((id) => {
+      const mark = visited.has(id) ? '✅' : '⬜';
+      return `${mark} ${regionLabel(id)}`;
+    });
+    lines.push(`**${zone.name}**`);
+    lines.push(parts.join('  '));
+    lines.push('');
+  }
+
+  const endings = parseStringSet(profile.endings_seen);
+  const allEndings = endingIds();
+  lines.push(`**结局图鉴** ${endings.size}/${allEndings.length}`);
+  lines.push(
+    allEndings
+      .map((id) => `${endings.has(id) ? '✅' : '⬜'} ${endingLabel(id)}`)
+      .join('  '),
+  );
+  return lines.join('\n').trimEnd();
+}
+
+export function formatAchievements(profile: AdvProfileRow, showHidden = false): string {
+  const unlocked = parseStringSet(profile.achievements);
+  const lines = [
+    `🏅 **成就** ${unlocked.size}/${totalAchievements()}`,
+    `完成局数：${profile.runs_completed}  ·  生涯步数：${profile.total_steps}`,
+    '',
+  ];
+
+  for (const def of ACHIEVEMENTS) {
+    const got = unlocked.has(def.id);
+    if (def.hidden && !got && !showHidden) continue;
+    const mark = got ? '✅' : '⬜';
+    lines.push(`${mark} ${def.icon} **${def.title}** — ${def.description}`);
+  }
+  return lines.join('\n');
+}
+
+export function formatNewAchievements(ids: string[]): string {
+  if (!ids.length) return '';
+  const lines = ['', '🏅 **新成就解锁！**'];
+  for (const id of ids) {
+    const def = achievementById(id);
+    if (def) lines.push(`${def.icon} ${def.title} — ${def.description}`);
+  }
+  return lines.join('\n');
+}

package/src/profile-parse.ts

@@ -0,0 +1,19 @@
+/** 解析 DB 中的 JSON 字符串集合（兼容 SQLite 已自动 parse 的数组） */
+export function parseStringSet(value: string | string[] | unknown): Set<string> {
+  if (Array.isArray(value)) {
+    return new Set(value.filter((x): x is string => typeof x === 'string'));
+  }
+  if (typeof value !== 'string' || !value) return new Set();
+  try {
+    const v = JSON.parse(value);
+    return Array.isArray(v)
+      ? new Set(v.filter((x): x is string => typeof x === 'string'))
+      : new Set();
+  } catch {
+    return new Set();
+  }
+}
+
+export function serializeStringSet(set: Set<string>): string {
+  return JSON.stringify([...set].sort());
+}