@zhin.js/plugin-dungeon-expedition 1.0.0

package/src/game-flow.ts

@@ -0,0 +1,126 @@
+import {
+  GameSessionConflictError,
+  SessionRevisionConflictError,
+  channelKey,
+  type GameMessageLike,
+  type GameReply,
+} from '@zhin.js/game-kit';
+import {
+  DungeonRuleError,
+  type DungeonAction,
+} from './engine.js';
+import type { DungeonSessionRow } from './models.js';
+import {
+  type SessionService,
+  stateFromSession,
+} from './session-service.js';
+import {
+  buildDungeonView,
+  parseDungeonSessionToken,
+} from './view.js';
+
+export async function startDungeon(
+  service: SessionService,
+  message: GameMessageLike,
+): Promise<GameReply> {
+  const active = await service.getActiveByChannel(channelKey(message));
+  if (active) return buildDungeonView(active, stateFromSession(active), message.$channel.type);
+  try {
+    const session = await service.createSession(message);
+    return buildDungeonView(session, stateFromSession(session), message.$channel.type);
+  } catch (error) {
+    if (error instanceof GameSessionConflictError) return error.message;
+    throw error;
+  }
+}
+
+export async function continueDungeon(
+  service: SessionService,
+  message: GameMessageLike,
+): Promise<GameReply> {
+  const session = await service.getActiveByChannel(channelKey(message));
+  if (!session) return '当前频道没有进行中的地牢远征。发送「地牢 开始」创建队伍。';
+  return buildDungeonView(session, stateFromSession(session), message.$channel.type);
+}
+
+export async function handleDungeonChoice(
+  service: SessionService,
+  message: GameMessageLike,
+  sessionToken: string,
+  choiceId: string,
+): Promise<GameReply> {
+  const token = parseDungeonSessionToken(sessionToken);
+  if (!token) return '无效的地牢操作。';
+  const session = await service.getById(token.sessionId);
+  if (!session || session.channel_key !== channelKey(message)) {
+    return '远征不存在，或不属于当前频道。';
+  }
+  if (choiceId === 'restart') {
+    if (session.status === 'active') return '当前远征尚未结束。';
+    if (session.owner_id !== message.$sender.id) return '只有原队长可以重新创建远征。';
+    return startDungeon(service, message);
+  }
+  const action = actionFromChoice(choiceId, message);
+  if (!action) return '未知的地牢操作。';
+  try {
+    const result = await service.performAction({
+      sessionId: session.id,
+      actorId: message.$sender.id,
+      actorName: message.$sender.name?.trim() || message.$sender.id,
+      action,
+      expectedRevision: token.revision,
+      actionId: `${session.id}:${token.revision}:${message.$sender.id}:${choiceId}`,
+    });
+    return buildDungeonView(
+      result.session,
+      stateFromSession(result.session),
+      message.$channel.type,
+    );
+  } catch (error) {
+    if (error instanceof DungeonRuleError
+      || error instanceof GameSessionConflictError) {
+      return error.message;
+    }
+    if (error instanceof SessionRevisionConflictError) {
+      const latest = await service.getById(session.id);
+      if (!latest) return '远征状态已变化，请重新打开当前界面。';
+      const view = buildDungeonView(
+        latest,
+        stateFromSession(latest),
+        message.$channel.type,
+      );
+      return Array.isArray(view)
+        ? ['操作来自旧回合，已为你刷新最新状态。', ...view]
+        : ['操作来自旧回合，已为你刷新最新状态。', view];
+    }
+    throw error;
+  }
+}
+
+export function commandActionId(
+  session: DungeonSessionRow,
+  actorId: string,
+  choiceId: string,
+): string {
+  return `${session.id}:${session.revision}:${actorId}:${choiceId}`;
+}
+
+function actionFromChoice(
+  choiceId: string,
+  message: GameMessageLike,
+): DungeonAction | null {
+  if (choiceId === 'join') {
+    return {
+      type: 'join',
+      name: message.$sender.name?.trim() || message.$sender.id,
+    };
+  }
+  if (choiceId === 'ready') return { type: 'ready' };
+  if (choiceId === 'start') return { type: 'start' };
+  if (choiceId === 'explore') return { type: 'explore' };
+  if (choiceId === 'attack') return { type: 'attack' };
+  if (choiceId === 'defend') return { type: 'defend' };
+  if (choiceId === 'potion') return { type: 'potion' };
+  if (choiceId === 'abort') return { type: 'abort' };
+  return null;
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+export {
+  DUNGEON_HELP,
+  normalizeDungeonAction,
+  runDungeonCommand,
+} from './dungeon-command.js';
+export {
+  DUNGEON_SCHEMA_VERSION,
+  DungeonRuleError,
+  applyDungeonAction,
+  createDungeonState,
+  decodeDungeonState,
+  type DungeonAction,
+  type DungeonState,
+} from './engine.js';
+export {
+  createServices,
+  SessionService,
+  stateFromSession,
+} from './session-service.js';
+export {
+  DUNGEON_PREFIX,
+  buildDungeonView,
+  choicesForState,
+} from './view.js';
+export {
+  gameServicesToken,
+  resolveGameServices,
+} from './runtime-store.js';

package/src/models.ts

@@ -0,0 +1,59 @@
+import type { Models } from '@zhin.js/core';
+
+export type DungeonSessionStatus = 'active' | 'completed' | 'aborted';
+
+declare module '@zhin.js/core' {
+  interface Models {
+    dungeon_sessions: {
+      id: string;
+      adapter: string;
+      endpoint: string;
+      channel_type: string;
+      channel_id: string;
+      channel_key: string;
+      owner_id: string;
+      owner_name: string;
+      state_json: string;
+      phase: string;
+      turn: string;
+      rng_state: number;
+      schema_version: number;
+      revision: number;
+      processed_actions: string;
+      deadline_at: number;
+      status: DungeonSessionStatus;
+      updated_at: number;
+      created_at: number;
+    };
+  }
+}
+
+export type DungeonSessionRow = Models['dungeon_sessions'];
+
+export function defineHostTables(
+  database: {
+    define(name: string, definition: Record<string, unknown>): void;
+  },
+): void {
+  database.define('dungeon_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 },
+    owner_id: { type: 'text', nullable: false },
+    owner_name: { type: 'text', default: '' },
+    state_json: { type: 'text', nullable: false },
+    phase: { type: 'text', default: 'lobby' },
+    turn: { type: 'text', default: '' },
+    rng_state: { type: 'integer', default: 1 },
+    schema_version: { type: 'integer', default: 1 },
+    revision: { type: 'integer', default: 0 },
+    processed_actions: { type: 'text', default: '[]' },
+    deadline_at: { type: 'integer', default: 0 },
+    status: { type: 'text', default: 'active' },
+    updated_at: { type: 'integer', default: 0 },
+    created_at: { type: 'integer', default: 0 },
+  });
+}

package/src/runtime-store.ts

@@ -0,0 +1,12 @@
+import { createToken } from '@zhin.js/plugin-runtime';
+import type { SessionService } from './session-service.js';
+
+export const gameServicesToken = createToken<SessionService>(
+  'zhin.game.dungeon-expedition.services',
+);
+
+export function resolveGameServices(
+  context: { use<T>(token: typeof gameServicesToken): T },
+): SessionService {
+  return context.use(gameServicesToken) as SessionService;
+}

package/src/session-service.ts

@@ -0,0 +1,157 @@
+import type { Database, Models } from '@zhin.js/core';
+import {
+  DeterministicRandom,
+  VersionedSessionService,
+  channelKey,
+  gameSessionCoordinator,
+  generateCompactId,
+  type GameMessageLike,
+  type GameOutcome,
+  type GameSessionDatabase,
+  type SessionMutationResult,
+} from '@zhin.js/game-kit';
+import {
+  activePlayer,
+  applyDungeonAction,
+  createDungeonState,
+  decodeDungeonState,
+  type DungeonAction,
+  type DungeonState,
+} from './engine.js';
+import type { DungeonSessionRow } from './models.js';
+
+export type DungeonDatabase = Database<unknown, Models, string>;
+
+export interface PerformDungeonActionOptions {
+  readonly sessionId: string;
+  readonly actorId: string;
+  readonly actorName: string;
+  readonly action: DungeonAction;
+  readonly actionId: string;
+  readonly expectedRevision?: number;
+}
+
+export class SessionService extends VersionedSessionService<DungeonSessionRow> {
+  constructor(database: DungeonDatabase) {
+    super(database as unknown as GameSessionDatabase<DungeonSessionRow>, {
+      gameId: 'dungeon',
+      table: 'dungeon_sessions',
+      userFields: ['owner_id'],
+      projectOutcomes: projectDungeonOutcomes,
+    });
+  }
+
+  async createSession(
+    message: GameMessageLike,
+    seed?: string | number,
+  ): Promise<DungeonSessionRow> {
+    const now = Date.now();
+    const id = generateCompactId('dng_');
+    const ownerName = message.$sender.name?.trim() || message.$sender.id;
+    const state = createDungeonState(message.$sender.id, ownerName);
+    const random = DeterministicRandom.fromSeed(seed ?? id);
+    return this.createRow({
+      id,
+      adapter: String(message.$adapter),
+      endpoint: message.$endpoint,
+      channel_type: message.$channel.type,
+      channel_id: message.$channel.id,
+      channel_key: channelKey(message),
+      owner_id: message.$sender.id,
+      owner_name: ownerName,
+      state_json: JSON.stringify(state),
+      phase: state.phase,
+      turn: activePlayer(state)?.id ?? '',
+      rng_state: random.state,
+      schema_version: state.schemaVersion,
+      revision: 0,
+      processed_actions: '[]',
+      deadline_at: now + 5 * 60_000,
+      status: 'active',
+      updated_at: now,
+      created_at: now,
+    });
+  }
+
+  override async getActiveForUser(
+    channelKeyValue: string,
+    userId: string,
+  ): Promise<DungeonSessionRow | null> {
+    const rows = await this.model.findAll({
+      channel_key: channelKeyValue,
+      status: 'active',
+    });
+    return rows.find((row) =>
+      decodeDungeonState(row.state_json).players.some(
+        (player) => player.id === userId,
+      )) ?? null;
+  }
+
+  async performAction(
+    options: PerformDungeonActionOptions,
+  ): Promise<SessionMutationResult<DungeonSessionRow>> {
+    const existing = await this.getById(options.sessionId);
+    if (!existing) {
+      return this.mutateSession(options.sessionId, {
+        actionId: options.actionId,
+        apply: {},
+      });
+    }
+    if (options.action.type === 'join') {
+      await gameSessionCoordinator.assertAvailable(
+        this.gameId,
+        existing.channel_key,
+        [options.actorId],
+      );
+    }
+    return this.mutateSession(options.sessionId, {
+      actionId: options.actionId,
+      expectedRevision: options.expectedRevision,
+      apply: (session) => {
+        const state = decodeDungeonState(session.state_json);
+        const random = DeterministicRandom.fromState(session.rng_state);
+        const next = applyDungeonAction(
+          state,
+          options.actorId,
+          options.action,
+          random,
+        );
+        return {
+          state_json: JSON.stringify(next),
+          phase: next.phase,
+          turn: activePlayer(next)?.id ?? '',
+          rng_state: random.state,
+          schema_version: next.schemaVersion,
+          deadline_at: Date.now() + 5 * 60_000,
+          status: next.phase === 'completed'
+            ? next.result === 'aborted' ? 'aborted' : 'completed'
+            : 'active',
+        };
+      },
+    });
+  }
+}
+
+export function createServices(database: DungeonDatabase): SessionService {
+  return new SessionService(database);
+}
+
+export function stateFromSession(session: DungeonSessionRow): DungeonState {
+  return decodeDungeonState(session.state_json);
+}
+
+function projectDungeonOutcomes(
+  session: Readonly<DungeonSessionRow>,
+): readonly GameOutcome[] {
+  const state = decodeDungeonState(session.state_json);
+  return state.players.map((player) => ({
+    userId: player.id,
+    userName: player.name,
+    result: session.status === 'aborted' || state.result === 'aborted'
+      ? 'aborted'
+      : state.result === 'victory'
+      ? player.hp > 0 ? 'won' : 'lost'
+      : 'lost',
+    score: state.roomsCleared * 10 + player.gold,
+  }));
+}

package/src/view.ts

@@ -0,0 +1,113 @@
+import type { SendContent } from '@zhin.js/core';
+import {
+  buildChoiceKeyboard,
+  type ChoiceOption,
+} from '@zhin.js/game-kit';
+import { activePlayer, type DungeonState } from './engine.js';
+import type { DungeonSessionRow } from './models.js';
+
+export const DUNGEON_PREFIX = 'dungeon';
+
+export function dungeonSessionToken(session: DungeonSessionRow): string {
+  return `${session.id}@${session.revision}`;
+}
+
+export function parseDungeonSessionToken(
+  token: string,
+): { sessionId: string; revision: number } | null {
+  const match = /^(.+)@(\d+)$/.exec(token);
+  if (!match?.[1] || match[2] === undefined) return null;
+  return { sessionId: match[1], revision: Number(match[2]) };
+}
+
+export function choicesForState(state: Readonly<DungeonState>): ChoiceOption[] {
+  if (state.phase === 'completed') {
+    return [{
+      id: 'restart',
+      label: '再来一局',
+      style: 'primary',
+      keepEnabledWhenTerminal: true,
+    }];
+  }
+  if (state.phase === 'lobby') {
+    return [
+      { id: 'join', label: '加入队伍', style: 'secondary' },
+      { id: 'ready', label: '准备/取消', style: 'secondary' },
+      { id: 'start', label: '开始远征', style: 'primary' },
+      { id: 'abort', label: '解散队伍', style: 'danger' },
+    ];
+  }
+  if (state.phase === 'combat') {
+    return [
+      { id: 'attack', label: '攻击', style: 'primary' },
+      { id: 'defend', label: '防御', style: 'secondary' },
+      { id: 'potion', label: '药水', style: 'secondary' },
+      { id: 'abort', label: '结束远征', style: 'danger' },
+    ];
+  }
+  return [
+    { id: 'explore', label: '探索下一房间', style: 'primary' },
+    { id: 'potion', label: '使用药水', style: 'secondary' },
+    { id: 'abort', label: '结束远征', style: 'danger' },
+  ];
+}
+
+export function buildDungeonView(
+  session: DungeonSessionRow,
+  state: Readonly<DungeonState>,
+  channelType?: string,
+): SendContent {
+  const current = activePlayer(state);
+  const lines = [
+    `地牢远征 · 第 ${state.floor}/${3} 层 · 房间 ${state.room}/${4}`,
+    `状态：${phaseLabel(state)}`,
+    '',
+    ...state.players.map((player, index) => {
+      const turn = current?.id === player.id && state.phase !== 'lobby' ? ' <- 当前回合' : '';
+      const ready = state.phase === 'lobby' ? player.ready ? ' [已准备]' : ' [未准备]' : '';
+      return `${index + 1}. ${player.name}${ready} HP ${player.hp}/${player.maxHp}`
+        + ` · 药水 ${player.potions} · 金币 ${player.gold}${turn}`;
+    }),
+  ];
+  if (state.enemy) {
+    lines.push(
+      '',
+      `${state.enemy.boss ? '守层者' : '敌人'}：${state.enemy.name}`,
+      `HP ${state.enemy.hp}/${state.enemy.maxHp} · 攻击 ${state.enemy.attack}`,
+    );
+  }
+  lines.push('', '最近事件：', ...state.log.slice(-4).map((line) => `- ${line}`));
+  if (state.phase === 'completed') {
+    lines.push(
+      '',
+      state.result === 'victory'
+        ? '远征胜利，地牢已被征服。'
+        : state.result === 'aborted'
+          ? '本次远征由队长结束。'
+          : '远征失败，队伍全员倒下。',
+    );
+  }
+
+  const choices = choicesForState(state);
+  return buildChoiceKeyboard({
+    gamePrefix: DUNGEON_PREFIX,
+    sessionId: dungeonSessionToken(session),
+    narrative: lines.join('\n'),
+    choices,
+    terminal: state.phase === 'completed',
+    buttonsPerRow: 2,
+    fallbackHint: choices.map((choice, index) =>
+      `${index + 1} ${choice.label}`).join(' · '),
+    interactionProfile: state.phase === 'completed' ? 'terminal' : 'gameplay',
+    channelType,
+  });
+}
+
+function phaseLabel(state: Readonly<DungeonState>): string {
+  if (state.phase === 'lobby') return '等待队员';
+  if (state.phase === 'exploring') return '探索中';
+  if (state.phase === 'combat') return '战斗中';
+  if (state.result === 'victory') return '胜利';
+  if (state.result === 'aborted') return '已结束';
+  return '失败';
+}