@zhin.js/plugin-text-adventure 1.1.15 → 1.1.16

package/src/game-flow.ts

@@ -1,4 +1,7 @@
-import type { GameMessageLike, GameReply } from '@zhin.js/game-kit';
+import { createMessages, resolveLocale } from 'zhin.js/i18n';
+import { gameCommandHint, type GameMessageLike, type GameReply } from '@zhin.js/game-kit';
+import { regionLabel, endingLabel } from './story-catalog.js';
+import { itemLabel } from './story-items.js';
 import type { AdvProfileRow, AdvSessionRow } from './models.js';
 import { formatNewAchievements } from './profile-format.js';
 import { buildSceneInteractive } from './scene-view.js';
@@ -22,7 +25,7 @@ export async function sendOrEditScene(
     ?? await services.profiles.getOrCreate(session.player_id, session.player_name);
   const content = buildSceneInteractive(session, extraNarrative, prof, message.$channel.type);
   if (!content) {
-    return '场景数据异常，请 adv quit 后重新开始。';
+    return messages(resolveLocale(session.locale), 'invalidScene');
   }
   return content;
 }
@@ -35,9 +38,11 @@ export async function startAdventure(
   const active = await services.sessions.getActiveByChannel(ch);
   if (active) {
     if (active.player_id === message.$sender.id) {
-      return '你已有进行中的冒险。发送 adv continue 继续，或 adv quit 放弃。';
+      const locale = resolveLocale(active.locale);
+      const command = message.formatCommand?.('adv');
+      return messages(locale, 'active') + (command === undefined ? '' : messages(locale, 'activeHint', { command }));
     }
-    return `本频道已有玩家 ${active.player_name} 的冒险进行中。`;
+    return messages(resolveLocale(message.locale), 'channelBusy', { player: active.player_name });
   }
 
   await services.profiles.onRunStarted(message.$sender.id, message.$sender.name?.trim() || message.$sender.id);
@@ -58,25 +63,27 @@ export async function handleChoice(
   choiceId: string,
 ): Promise<GameReply | null> {
   const session = await services.sessions.getById(sessionId);
+  const locale = resolveLocale(session ? session.locale : message.locale);
   // 踏进 terminal 场景时 status 必为 completed，终局需放行「再玩一次」（restart）
   if (!session || (session.status !== 'active' && !(session.status === 'completed' && choiceId === 'restart'))) {
-    return '冒险不存在或已结束。';
+    return messages(locale, 'ended');
   }
   if (session.player_id !== message.$sender.id) {
-    return '这是别人的冒险。';
+    return messages(locale, 'otherPlayer');
   }
 
   const state = stateFromSession(session);
   const scene = getScene(state.sceneId);
-  if (!scene) return '场景丢失，请 adv quit 后重新开始。';
+  if (!scene) return messages(locale, 'invalidScene');
 
   if (scene.terminal && choiceId !== 'restart') {
-    return '本局已结束，请点击「再玩一次」或发送 adv start。';
+    return messages(locale, 'restart');
   }
 
   if (choiceId === 'restart') {
     await services.sessions.updateSession(session.id, {
       scene_id: 'start',
+      locale: resolveLocale(message.locale),
       hp: 100,
       inventory: '[]',
       flags: '{}',
@@ -92,11 +99,11 @@ export async function handleChoice(
 
   // 服务端校验：选项必须当前可见（requires 门槛不能只靠视图层过滤，payload 可绕过）
   if (!visibleChoices(scene, state).some((c) => c.id === choiceId)) {
-    return '该选项不可用。';
+    return messages(locale, 'unavailable');
   }
 
   const result = resolveChoice(state, choiceId);
-  if (!result) return '该选项不可用。';
+  if (!result) return messages(locale, 'unavailable');
 
   const next = applyChoiceResult(state, result);
   const nextScene = getScene(next.sceneId);
@@ -139,7 +146,7 @@ export async function handleChoice(
   }
 
   const updated = (await services.sessions.getById(session.id))!;
-  const extra = formatNewAchievements(newAchievements);
+  const extra = formatNewAchievements(newAchievements, locale);
   return sendOrEditScene(services, message, updated, extra);
 }
 
@@ -151,23 +158,45 @@ export async function continueAdventure(
     `${message.$adapter}-${message.$endpoint}-${message.$channel.type}:${message.$channel.id}`,
     message.$sender.id,
   );
-  if (!session) return '你没有进行中的冒险，发送 adv start 开始。';
+  if (!session) return messages(resolveLocale(message.locale), 'noGame') + gameCommandHint(message, 'adv');
   return sendOrEditScene(services, message, session);
 }
 
 export function sessionSummary(session: AdvSessionRow): string {
-  const scene = getScene(session.scene_id);
+  const locale = resolveLocale(session.locale);
   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}`,
+    messages(locale, 'summary', {
+      id: session.id,
+      player: session.player_name,
+      scene: regionLabel(session.scene_id, locale),
+      hp: session.hp,
+      items: state.inventory.length ? state.inventory.map((id) => itemLabel(id, locale)).join(', ') : messages(locale, 'none'),
+      steps: session.step_count,
+      status: messages(locale, session.status === 'active' ? 'activeStatus' : session.status === 'completed' ? 'completedStatus' : 'abortedStatus'),
+    }),
   ];
-  if (session.ending_id) lines.push(`结局：${session.ending_id}`);
+  if (session.ending_id) lines.push(messages(locale, 'ending', { ending: endingLabel(session.ending_id, locale) }));
   return lines.join('\n');
 }
+
+const messages = createMessages({
+  invalidScene: { 'zh-CN': '场景数据异常，请结束当前冒险后重新开始。', en: 'The scene is unavailable. End this adventure and start again.' },
+  active: { 'zh-CN': '你已有进行中的冒险。', en: 'You already have an active adventure.' },
+  activeHint: { 'zh-CN': '发送「{command} continue」继续，或「{command} quit」放弃。', en: 'Send “{command} continue” to continue or “{command} quit” to leave.' },
+  channelBusy: { 'zh-CN': '本频道已有玩家 {player} 的冒险进行中。', en: '{player} already has an adventure in progress in this channel.' },
+  ended: { 'zh-CN': '冒险不存在或已结束。', en: 'This adventure does not exist or has ended.' },
+  otherPlayer: { 'zh-CN': '这是别人的冒险。', en: 'This adventure belongs to another player.' },
+  restart: { 'zh-CN': '本局已结束，请点击「再玩一次」开始新冒险。', en: 'This adventure has ended. Select “Play again” to start a new one.' },
+  unavailable: { 'zh-CN': '该选项不可用。', en: 'That choice is not available.' },
+  noGame: { 'zh-CN': '你没有进行中的冒险。', en: 'You have no active adventure.' },
+  none: { 'zh-CN': '无', en: 'None' },
+  activeStatus: { 'zh-CN': '进行中', en: 'Active' },
+  completedStatus: { 'zh-CN': '已完成', en: 'Completed' },
+  abortedStatus: { 'zh-CN': '已放弃', en: 'Abandoned' },
+  summary: {
+    'zh-CN': '冒险 {id}\n玩家：{player}\n场景：{scene}\n生命：{hp}\n物品：{items}\n步数：{steps}\n状态：{status}',
+    en: 'Adventure {id}\nPlayer: {player}\nScene: {scene}\nHealth: {hp}\nItems: {items}\nSteps: {steps}\nStatus: {status}',
+  },
+  ending: { 'zh-CN': '结局：{ending}', en: 'Ending: {ending}' },
+});

package/src/models.ts

@@ -6,6 +6,7 @@ declare module '@zhin.js/core' {
   interface Models {
     adv_sessions: {
       id: string;
+      locale?: 'zh-CN' | 'en' | null;
       adapter: string;
       endpoint: string;
       channel_type: string;
@@ -46,10 +47,11 @@ export type AdvModelName = 'adv_sessions' | 'adv_profiles';
 
 
 export function defineHostTables(
-  db: { define: (name: string, definition: Record<string, unknown>) => void },
+  db: { define: (name: string, definition: Record<string, unknown>, options?: { readonly addColumns?: readonly string[] }) => void },
 ): void {
   db.define('adv_sessions', {
     id: { type: 'text', primary: true },
+    locale: { type: 'text', nullable: true },
     adapter: { type: 'text', nullable: false },
     endpoint: { type: 'text', nullable: false },
     channel_type: { type: 'text', nullable: false },
@@ -66,7 +68,7 @@ export function defineHostTables(
     step_count: { type: 'integer', default: 0 },
     updated_at: { type: 'bigint', default: 0 },
     created_at: { type: 'bigint', default: 0 },
-  });
+  }, { addColumns: ['locale'] });
   db.define('adv_profiles', {
     player_id: { type: 'text', primary: true },
     player_name: { type: 'text', default: '' },

package/src/profile-format.ts

@@ -1,3 +1,4 @@
+import { type Locale } from 'zhin.js/i18n';
 import { achievementById, ACHIEVEMENTS, totalAchievements } from './achievements.js';
 import {
   endingIds,
@@ -18,45 +19,46 @@ export function formatProgressCompact(profile: AdvProfileRow): string {
   return `🗺️ ${visited}/${totalRegions}  ·  🎬 ${endings}/${totalEndings}  ·  🏅 ${achievements}/${totalAchievements()}`;
 }
 
-export function formatMapProgress(profile: AdvProfileRow): string {
+export function formatMapProgress(profile: AdvProfileRow, locale: Locale = 'zh-CN'): 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}%）`,
+    `🗺️ **${locale === 'en' ? 'Exploration' : '探索进度'}** ${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)}`;
+      return `${mark} ${regionLabel(id, locale)}`;
     });
-    lines.push(`**${zone.name}**`);
+    lines.push(`**${locale === 'en' ? zone.nameEn : 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(`**${locale === 'en' ? 'Endings' : '结局图鉴'}** ${endings.size}/${allEndings.length}`);
   lines.push(
     allEndings
-      .map((id) => `${endings.has(id) ? '✅' : '⬜'} ${endingLabel(id)}`)
+      .map((id) => `${endings.has(id) ? '✅' : '⬜'} ${endingLabel(id, locale)}`)
       .join('  '),
   );
   return lines.join('\n').trimEnd();
 }
 
-export function formatAchievements(profile: AdvProfileRow, showHidden = false): string {
+export function formatAchievements(profile: AdvProfileRow, showHidden = false, locale: Locale = 'zh-CN'): string {
   const unlocked = parseStringSet(profile.achievements);
   const lines = [
-    `🏅 **成就** ${unlocked.size}/${totalAchievements()}`,
-    `完成局数：${profile.runs_completed}  ·  生涯步数：${profile.total_steps}`,
+    `🏅 **${locale === 'en' ? 'Achievements' : '成就'}** ${unlocked.size}/${totalAchievements()}`,
+    locale === 'en' ? `Completed adventures: ${profile.runs_completed} · Lifetime steps: ${profile.total_steps}` : `完成局数：${profile.runs_completed}  ·  生涯步数：${profile.total_steps}`,
     '',
   ];
 
-  for (const def of ACHIEVEMENTS) {
+  for (const entry of ACHIEVEMENTS) {
+    const def = achievementById(entry.id, locale)!;
     const got = unlocked.has(def.id);
     if (def.hidden && !got && !showHidden) continue;
     const mark = got ? '✅' : '⬜';
@@ -65,11 +67,11 @@ export function formatAchievements(profile: AdvProfileRow, showHidden = false):
   return lines.join('\n');
 }
 
-export function formatNewAchievements(ids: string[]): string {
+export function formatNewAchievements(ids: string[], locale: Locale = 'zh-CN'): string {
   if (!ids.length) return '';
-  const lines = ['', '🏅 **新成就解锁！**'];
+  const lines = ['', locale === 'en' ? '🏅 **New achievement unlocked!**' : '🏅 **新成就解锁！**'];
   for (const id of ids) {
-    const def = achievementById(id);
+    const def = achievementById(id, locale);
     if (def) lines.push(`${def.icon} ${def.title} — ${def.description}`);
   }
   return lines.join('\n');

package/src/scene-view.ts

@@ -1,3 +1,4 @@
+import { resolveLocale } from 'zhin.js/i18n';
 import type { SendContent } from '@zhin.js/core/runtime';
 import { buildChoiceKeyboard } from '@zhin.js/game-kit';
 import type { AdvProfileRow, AdvSessionRow } from './models.js';
@@ -16,14 +17,15 @@ export function buildSceneInteractive(
   profile?: AdvProfileRow,
   channelType?: string,
 ): SendContent | null {
-  const scene = getScene(session.scene_id);
+  const locale = resolveLocale(session.locale);
+  const scene = getScene(session.scene_id, locale);
   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);
+  let narrative = sceneNarrative(scene, state, locale);
   if (profile && !terminal) {
     narrative = `${formatProgressCompact(profile)}\n\n${narrative}`;
   }
@@ -42,7 +44,7 @@ export function buildSceneInteractive(
     })),
     terminal,
     buttonsPerRow: 2,
-    fallbackHint: '回复数字选择（仅编号）',
+    fallbackHint: locale === 'en' ? 'Reply with the choice number only' : '回复数字选择（仅编号）',
     interactionProfile: terminal ? 'terminal' : 'gameplay',
     channelType,
   });

package/src/session-service.ts

@@ -37,6 +37,7 @@ export class SessionService extends BaseSessionService<AdvSessionRow> {
     const id = generateSessionId();
     const row: AdvSessionRow = {
       id,
+      locale: message.locale ?? 'zh-CN',
       adapter: String(message.$adapter),
       endpoint: message.$endpoint,
       channel_type: message.$channel.type,

package/src/story-catalog.ts

@@ -1,3 +1,4 @@
+import { type Locale } from 'zhin.js/i18n';
 import { SCENES } from './story-scenes.js';
 
 /** 区域中文名（用于地图 / 成就展示） */
@@ -54,25 +55,25 @@ export const ENDING_LABELS: Record<string, string> = {
 };
 
 /** 地图分区（便于 adv map 分组展示） */
-export const MAP_ZONES: Array<{ name: string; sceneIds: string[] }> = [
+export const MAP_ZONES: Array<{ name: string; nameEn: string; sceneIds: string[] }> = [
   {
-    name: '入口与塔',
+    name: '入口与塔', nameEn: 'Entrance and Tower',
     sceneIds: ['start', 'rubble', 'watchtower', 'observatory', 'vine_path'],
   },
   {
-    name: '主廊与泉',
+    name: '主廊与泉', nameEn: 'Corridor and Spring',
     sceneIds: ['corridor', 'mural_room', 'whisper_gallery', 'spring', 'flooded_hall', 'bell_tower'],
   },
   {
-    name: '庭院书库',
+    name: '庭院书库', nameEn: 'Garden and Library',
     sceneIds: ['garden', 'greenhouse', 'library', 'ember_forge'],
   },
   {
-    name: '冥域水线',
+    name: '冥域水线', nameEn: 'River of the Dead',
     sceneIds: ['market_ruins', 'ghost_bridge', 'crystal_cave', 'moon_pool', 'sunken_shrine'],
   },
   {
-    name: '墓穴深处',
+    name: '墓穴深处', nameEn: 'Deep Tombs',
     sceneIds: [
       'depths',
       'crypt_entry',
@@ -101,10 +102,62 @@ export function endingIds(): string[] {
     .map((s) => s.id);
 }
 
-export function regionLabel(id: string): string {
-  return REGION_LABELS[id] ?? ENDING_LABELS[id] ?? id;
+export function regionLabel(id: string, locale: Locale = 'zh-CN'): string {
+  return (locale === 'en' ? EN_REGION_LABELS : REGION_LABELS)[id] ?? endingLabel(id, locale);
 }
 
-export function endingLabel(id: string): string {
-  return ENDING_LABELS[id] ?? id;
+export function endingLabel(id: string, locale: Locale = 'zh-CN'): string {
+  return (locale === 'en' ? EN_ENDING_LABELS : ENDING_LABELS)[id] ?? id;
 }
+
+const EN_REGION_LABELS: Readonly<Record<string,string>> = {
+  "start": "Entrance to the Ruins",
+  "rubble": "Rubble Passage",
+  "watchtower": "Watchtower",
+  "observatory": "Observatory",
+  "vine_path": "Hidden Path",
+  "corridor": "Dark Corridor",
+  "mural_room": "Inscribed Mural",
+  "whisper_gallery": "Whispering Gallery",
+  "spring": "Spirit Spring",
+  "flooded_hall": "Flooded Hall",
+  "bell_tower": "Bell Tower",
+  "garden": "Ancient Garden",
+  "greenhouse": "Greenhouse",
+  "library": "Dusty Library",
+  "ember_forge": "Forge",
+  "market_ruins": "Ruined Market",
+  "ghost_bridge": "Ghost Bridge",
+  "crystal_cave": "Crystal Cave",
+  "moon_pool": "Moon Pool",
+  "sunken_shrine": "Sunken Shrine",
+  "depths": "Tomb Crossroads",
+  "crypt_entry": "Crypt Entrance",
+  "catacombs": "Catacombs",
+  "ossuary": "Ossuary",
+  "prison_cell": "Prison Cell",
+  "spider_nest": "Spider Nest",
+  "shadow_maze": "Shadow Maze",
+  "sealed_gates": "Sealed Chamber",
+  "vault": "Treasure Antechamber",
+  "vault_open": "Vault",
+  "throne_room": "Throne Room"
+};
+
+const EN_ENDING_LABELS: Readonly<Record<string,string>> = {
+  "treasure": "Treasure of the Ruins",
+  "ascension": "Starlight Restored",
+  "wisdom": "A Scholar's Return",
+  "curse": "The Price of Greed",
+  "escape": "Survival",
+  "defeat": "Fallen",
+  "coward": "A Coward's Return",
+  "hermit": "Garden Hermit",
+  "redemption": "A Spirit Set Free",
+  "drowned": "Cold-Water Slumber",
+  "spider": "Soul in a Cocoon",
+  "labyrinth": "Lost in the Maze",
+  "star_keeper": "Star Keeper's Oath",
+  "mask_king": "King of Masks",
+  "merchant": "The Merchant's Ending"
+};

package/src/story-items.ts

@@ -1,3 +1,4 @@
+import { type Locale } from 'zhin.js/i18n';
 /** 15 种可收集道具 */
 export const ITEM_LABELS: Record<string, string> = {
   torch: '火把',
@@ -19,6 +20,24 @@ export const ITEM_LABELS: Record<string, string> = {
 
 export const ITEM_IDS = Object.keys(ITEM_LABELS);
 
-export function itemLabel(id: string): string {
-  return ITEM_LABELS[id] ?? id;
+const EN_ITEM_LABELS: Readonly<Record<string, string>> = {
+  "torch": "Torch",
+  "key": "Rusty key",
+  "gem": "Blue gem",
+  "herb": "Luminous herb",
+  "scroll": "Torn scroll",
+  "amulet": "Elven amulet",
+  "silver_coin": "Ancient silver coin",
+  "rusted_blade": "Rusty blade",
+  "moon_shard": "Moon shard",
+  "elixir": "Healing elixir",
+  "compass": "Astral compass",
+  "spirit_bell": "Echo bell",
+  "elf_feather": "Silver feather",
+  "masquerade_mask": "Ritual mask",
+  "star_chart": "Star chart fragment"
+};
+
+export function itemLabel(id: string, locale: Locale = 'zh-CN'): string {
+  return (locale === 'en' ? EN_ITEM_LABELS : ITEM_LABELS)[id] ?? id;
 }