@zhin.js/plugin-roulette 0.1.14 → 0.1.15

package/src/models.ts

@@ -0,0 +1,75 @@
+import type { Models } from '@zhin.js/core';
+
+export type RouletteSessionStatus = 'active' | 'finished' | 'aborted';
+
+declare module '@zhin.js/core' {
+  interface Models {
+    roulette_sessions: {
+      id: string;
+      locale?: 'zh-CN' | 'en' | null;
+      adapter: string;
+      endpoint: string;
+      channel_type: string;
+      channel_id: string;
+      channel_key: string;
+      /** Exact Endpoint identity (`conversation.endpoint`), used for the mute lookup. */
+      endpoint_adapter: string;
+      endpoint_id: string;
+      host_id: string;
+      state_json: string;
+      phase: string;
+      turn: string;
+      revision: number;
+      processed_actions: string;
+      /** Epoch ms when the lobby or the current turn times out; 0 once the game is over. */
+      deadline_at: number;
+      status: RouletteSessionStatus;
+      updated_at: number;
+      created_at: number;
+    };
+    roulette_group_settings: {
+      /** The channel key, one row per group. */
+      id: string;
+      mute_penalty: number;
+      updated_by: string;
+      updated_at: number;
+    };
+  }
+}
+
+export type RouletteSessionRow = Models['roulette_sessions'];
+export type RouletteGroupSettingsRow = Models['roulette_group_settings'];
+
+export const ROULETTE_TABLES = ['roulette_sessions', 'roulette_group_settings'] as const;
+
+export function defineHostTables(
+  database: { define(name: string, definition: Record<string, unknown>, options?: { readonly addColumns?: readonly string[] }): void },
+): void {
+  database.define('roulette_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 },
+    channel_id: { type: 'text', nullable: false },
+    channel_key: { type: 'text', nullable: false },
+    endpoint_adapter: { type: 'text', default: '' },
+    endpoint_id: { type: 'text', default: '' },
+    host_id: { type: 'text', nullable: false },
+    state_json: { type: 'text', nullable: false },
+    phase: { type: 'text', default: 'lobby' },
+    turn: { type: 'text', default: '' },
+    revision: { type: 'integer', default: 0 },
+    processed_actions: { type: 'text', default: '[]' },
+    deadline_at: { type: 'bigint', default: 0 },
+    status: { type: 'text', default: 'active' },
+    updated_at: { type: 'bigint', default: 0 },
+    created_at: { type: 'bigint', default: 0 },
+  }, { addColumns: ['locale'] });
+  database.define('roulette_group_settings', {
+    id: { type: 'text', primary: true },
+    mute_penalty: { type: 'integer', default: 0 },
+    updated_by: { type: 'text', default: '' },
+    updated_at: { type: 'bigint', default: 0 },
+  });
+}

package/src/mute-penalty.ts

@@ -0,0 +1,88 @@
+import { adapterFeatureId, type AdapterIndex, type EndpointMuteRequest } from 'zhin.js/adapter';
+
+/**
+ * Where a game was played: the exact Endpoint identity from `message.conversation.endpoint`
+ * (adapter plugin owner + Endpoint capability id) plus the conversation itself.
+ */
+export interface PenaltyConversation {
+  readonly endpointAdapter: string;
+  readonly endpointId: string;
+  readonly kind: string;
+  readonly id: string;
+}
+
+export type MuteSupport =
+  /** The live Endpoint's management port implements `muteGroupMember` and this is a group. */
+  | 'supported'
+  /** Muting only exists for group members (not private chats or channels). */
+  | 'not-a-group'
+  /** No adapter projection, no such Endpoint, or its management port cannot mute. */
+  | 'unsupported';
+
+/**
+ * The only mute surface the game uses. It never looks at adapter names: support
+ * is whatever the live Endpoint's platform-neutral `EndpointManagement` implements.
+ */
+export interface MutePenaltyPort {
+  support(conversation: PenaltyConversation): MuteSupport;
+  mute(conversation: PenaltyConversation, userId: string, durationSeconds: number): Promise<void>;
+}
+
+/** The capability context of a command, middleware or schedule run. */
+export interface AdapterProjectionContext {
+  project<T>(feature: typeof adapterFeatureId): T;
+}
+
+type MuteGroupMember = (request: EndpointMuteRequest) => Promise<void>;
+
+type EndpointLookup = Pick<AdapterIndex, 'resolve' | 'management'>;
+
+export function resolveMutePenalty(context: AdapterProjectionContext): MutePenaltyPort {
+  return {
+    support(conversation) {
+      if (conversation.kind !== 'group') return 'not-a-group';
+      return findMuteGroupMember(context, conversation) ? 'supported' : 'unsupported';
+    },
+    async mute(conversation, userId, durationSeconds) {
+      const muteGroupMember = findMuteGroupMember(context, conversation);
+      if (!muteGroupMember) {
+        throw new Error('This Endpoint cannot mute group members');
+      }
+      await muteGroupMember({ groupId: conversation.id, userId, durationSeconds });
+    },
+  };
+}
+
+/** Resolve canonical identity, then capture its guarded management port from the same Index. */
+function findMuteGroupMember(
+  context: AdapterProjectionContext,
+  conversation: PenaltyConversation,
+): MuteGroupMember | undefined {
+  const adapters = readAdapterProjection(context);
+  if (!adapters) return undefined;
+  if (!conversation.endpointAdapter || !conversation.endpointId) return undefined;
+  let management: ReturnType<EndpointLookup['management']>;
+  try {
+    const id = adapters.resolve(conversation.endpointAdapter, conversation.endpointId);
+    management = id ? adapters.management(id) : undefined;
+  } catch {
+    return undefined;
+  }
+  const muteGroupMember = management?.muteGroupMember;
+  if (typeof muteGroupMember !== 'function') return undefined;
+  return muteGroupMember.bind(management);
+}
+
+function readAdapterProjection(context: AdapterProjectionContext): EndpointLookup | undefined {
+  let projection: unknown;
+  try {
+    projection = context.project<unknown>(adapterFeatureId);
+  } catch {
+    // No Adapter Feature in this runtime: score only.
+    return undefined;
+  }
+  if (!projection || typeof projection !== 'object') return undefined;
+  const lookup = projection as Partial<EndpointLookup>;
+  if (typeof lookup.resolve !== 'function' || typeof lookup.management !== 'function') return undefined;
+  return lookup as EndpointLookup;
+}

package/src/roulette-actions.ts

@@ -0,0 +1,76 @@
+import { createMessages } from 'zhin.js/i18n';
+import type { GamePlayer } from '@zhin.js/game-kit';
+export type RouletteCommandAction =
+  | 'help'
+  | 'open'
+  | 'join'
+  | 'start'
+  | 'fire'
+  | 'leave'
+  | 'cancel'
+  | 'status'
+  | 'penalty-on'
+  | 'penalty-off'
+  | 'penalty-status';
+
+const ACTION_WORDS: Readonly<Record<string, RouletteCommandAction>> = {
+  help: 'help',
+  帮助: 'help',
+  规则: 'help',
+  open: 'open',
+  开局: 'open',
+  创建: 'open',
+  join: 'join',
+  加入: 'join',
+  start: 'start',
+  开始: 'start',
+  fire: 'fire',
+  shoot: 'fire',
+  开枪: 'fire',
+  扣动扳机: 'fire',
+  leave: 'leave',
+  退出: 'leave',
+  离开: 'leave',
+  认输: 'leave',
+  cancel: 'cancel',
+  取消: 'cancel',
+  status: 'status',
+  状态: 'status',
+  'mute-on': 'penalty-on',
+  开启禁言: 'penalty-on',
+  'mute-off': 'penalty-off',
+  关闭禁言: 'penalty-off',
+  mute: 'penalty-status',
+  禁言: 'penalty-status',
+};
+
+/** Empty input means help; unknown words return null so normal chat is never hijacked. */
+export function normalizeRouletteAction(raw: string): RouletteCommandAction | null {
+  const word = raw.trim();
+  if (!word) return 'help';
+  return ACTION_WORDS[word] ?? ACTION_WORDS[word.toLowerCase()] ?? null;
+}
+
+
+const messages = createMessages({
+  title: { 'zh-CN': '🔫 俄罗斯轮盘（2 人起，轮流开枪，中弹者输）', en: '🔫 Russian Roulette (two or more players, take turns; the player hit loses)' },
+  open: { 'zh-CN': '创建一局并上桌', en: 'Open a lobby and join it' },
+  join: { 'zh-CN': '加入等待中的对局', en: 'Join a waiting lobby' },
+  start: { 'zh-CN': '房主开局（弹巢随机装 1 发子弹）', en: 'Host starts the game (one randomly placed bullet)' },
+  fire: { 'zh-CN': '轮到你时扣动扳机', en: 'Pull the trigger on your turn' },
+  leave: { 'zh-CN': '等待时离开；对局中离开算认输', en: 'Leave the lobby; leaving during play forfeits the game' },
+  cancel: { 'zh-CN': '房主或管理员取消本局（不计分）', en: 'Host or manager cancels the game (no score)' },
+  status: { 'zh-CN': '查看当前对局', en: 'View the current game' },
+  mute: { 'zh-CN': '查看禁言惩罚', en: 'View the mute penalty setting' },
+  'mute-on': { 'zh-CN': '开启本群禁言惩罚', en: 'Enable mute penalties for this group' },
+  'mute-off': { 'zh-CN': '关闭本群禁言惩罚', en: 'Disable mute penalties for this group' },
+  rules: { 'zh-CN': '规则：按加入顺序轮流开枪；轮到的人超时不开枪判负；幸存者各记 1 胜，输家记 1 负。禁言惩罚默认关闭。', en: 'Players take turns in join order. Missing your turn deadline loses the game. Each survivor gets one win; the loser gets one loss. Mute penalties are off by default.' },
+});
+export function getRouletteHelp(message: Pick<GamePlayer, 'locale' | 'formatCommand'> = {}): string {
+  const command = message.formatCommand?.('roulette');
+  const actions = ['open', 'join', 'start', 'fire', 'leave', 'cancel', 'status', 'mute', 'mute-on', 'mute-off'] as const;
+  return [messages(message.locale, 'title'),
+    ...(command === undefined ? [] : actions.map(action => `${command} ${action} — ${messages(message.locale, action)}`)),
+    '', messages(message.locale, 'rules')].join('\n');
+}
+export const ROULETTE_HELP = getRouletteHelp();

package/src/roulette-command.ts

@@ -0,0 +1,24 @@
+import { gamePlayerFromInput } from '@zhin.js/game-kit';
+import { runRouletteAction } from './game-flow.js';
+import { normalizeRouletteAction, getRouletteHelp } from './roulette-actions.js';
+import { resolveRouletteFlow, senderRolesOf, type RouletteCapabilityContext } from './runtime.js';
+
+/**
+ * Shared entry for the `roulette` command and the `轮盘` alias middleware.
+ * Returns null for unknown words so the alias middleware lets the chat through.
+ */
+export async function runRouletteCommand(
+  context: RouletteCapabilityContext,
+  input: unknown,
+  rawAction: string,
+): Promise<string | null> {
+  const action = normalizeRouletteAction(rawAction);
+  if (!action) return null;
+  if (action === 'help') return getRouletteHelp(gamePlayerFromInput(input, context));
+  const flow = resolveRouletteFlow(context);
+  const actor = {
+    message: gamePlayerFromInput(input, context),
+    roles: senderRolesOf(input),
+  };
+  return runRouletteAction(flow, actor, action);
+}

package/src/runtime.ts

@@ -0,0 +1,45 @@
+import type { Locale } from 'zhin.js/i18n';
+import { definePluginStore, type DeliveryTarget, type Token } from 'zhin.js';
+import { resolveRouletteConfig } from './config.js';
+import type { RouletteFlow } from './game-flow.js';
+import { resolveMutePenalty, type AdapterProjectionContext } from './mute-penalty.js';
+import type { RouletteServices } from './session-service.js';
+
+/** Owner-scoped services consumed by discovered commands, middleware and the deadline job. */
+export const rouletteServicesStore = definePluginStore<RouletteServices>('zhin.game.roulette.services');
+export const rouletteServicesToken = rouletteServicesStore;
+
+/**
+ * Whether roulette is enabled for one game conversation (ADR 0050 / 0055). The deadline sweep is
+ * not a message, so the dispatch gate does not see it; the sweep asks before announcing a result.
+ */
+export const rouletteFeatureGateStore = definePluginStore<RouletteFeatureGate>('zhin.game.roulette.feature-gate');
+export interface RouletteFeatureGate { isEnabledFor(target: DeliveryTarget): boolean }
+
+/** A command, middleware or schedule capability context. */
+export interface RouletteCapabilityContext extends AdapterProjectionContext {
+  readonly locale?: Locale;
+  readonly formatCommand?: (path: string) => string | undefined;
+  use<T>(token: Token<T>): T;
+  readonly config?: unknown;
+}
+
+export function resolveRouletteFlow(context: RouletteCapabilityContext): RouletteFlow {
+  return {
+    services: rouletteServicesStore.use(context),
+    config: resolveRouletteConfig(context.config),
+    penalty: resolveMutePenalty(context),
+  };
+}
+
+const CHAT_ROLE_CHAIN = ['owner', 'admin', 'trusted'] as const;
+
+/** Chat roles (ADR 0056, expanded: owner → owner / admin / trusted) of whoever sent the message. */
+export function senderRolesOf(input: unknown): readonly string[] {
+  if (!input || typeof input !== 'object') return [];
+  const sender = (input as { readonly sender?: unknown }).sender;
+  if (!sender || typeof sender !== 'object') return [];
+  const role = (sender as { readonly chatRole?: unknown }).chatRole;
+  const index = CHAT_ROLE_CHAIN.indexOf(role as typeof CHAT_ROLE_CHAIN[number]);
+  return index < 0 ? [] : CHAT_ROLE_CHAIN.slice(index);
+}

package/src/session-service.ts

@@ -0,0 +1,266 @@
+import { encodeStorageIdentity } from 'zhin.js/plugin-runtime';
+import type { Database, Models } from '@zhin.js/core';
+import {
+  VersionedSessionService,
+  generateCompactId,
+  secureRandomInt,
+  type GamePlayer,
+  type GameOutcome,
+  type GameSessionDatabase,
+} from '@zhin.js/game-kit';
+import type { RouletteConfig } from './config.js';
+import {
+  cancelGame,
+  createLobby,
+  currentPlayer,
+  decodeRouletteState,
+  expireLobby,
+  expireTurn,
+  isOpen,
+  joinLobby,
+  leaveGame,
+  pullTrigger,
+  startRound,
+  type RoulettePlayer,
+  type RouletteState,
+  type RouletteTableRules,
+} from './engine.js';
+import type {
+  RouletteGroupSettingsRow,
+  RouletteSessionRow,
+  RouletteSessionStatus,
+} from './models.js';
+
+export type RouletteDatabase = Database<unknown, Models, string>;
+
+export type RouletteAction =
+  | { readonly type: 'join'; readonly player: RoulettePlayer }
+  | { readonly type: 'start' }
+  | { readonly type: 'fire' }
+  | { readonly type: 'leave' }
+  | { readonly type: 'cancel' }
+  | { readonly type: 'expire' };
+
+export interface RouletteActionResult {
+  readonly session: RouletteSessionRow;
+  readonly state: RouletteState;
+  /** False when an identical action id was already applied (adapter retry). */
+  readonly applied: boolean;
+}
+
+export interface RouletteServiceOptions {
+  /** Picks the loaded chamber when a round starts; secure random by default. */
+  readonly chooseBulletChamber?: (chamberCount: number) => number;
+}
+
+export class RouletteSessionService extends VersionedSessionService<RouletteSessionRow> {
+  readonly #chooseBulletChamber: (chamberCount: number) => number;
+
+  constructor(database: RouletteDatabase, options: RouletteServiceOptions = {}) {
+    super(database as unknown as GameSessionDatabase<RouletteSessionRow>, {
+      gameId: 'roulette',
+      table: 'roulette_sessions',
+      userFields: ['host_id'],
+      projectOutcomes: projectRouletteOutcomes,
+    });
+    this.#chooseBulletChamber = options.chooseBulletChamber ?? secureRandomInt;
+  }
+
+  async createLobby(
+    message: GamePlayer,
+    config: RouletteConfig,
+  ): Promise<RouletteSessionRow> {
+    const now = Date.now();
+    const host = playerFromMessage(message);
+    const state = createLobby(host, tableRules(config));
+    return this.createRow({
+      target: message.target,
+      fields: {
+        id: generateCompactId('rlt_'),
+        locale: message.locale ?? 'zh-CN',
+        endpoint_adapter: encodeStorageIdentity(message.target.endpoint.adapter),
+        endpoint_id: encodeStorageIdentity(message.target.endpoint.id),
+        host_id: host.id,
+        state_json: JSON.stringify(state),
+        phase: state.phase,
+        turn: '',
+        revision: 0,
+        processed_actions: '[]',
+        deadline_at: now + config.lobbyTimeoutSeconds * 1000,
+        status: 'active',
+        updated_at: now,
+        created_at: now,
+      },
+    });
+  }
+
+  /** Every seated player counts as busy, not just the host. */
+  override async getActiveForUser(
+    channelKeyValue: string,
+    userId: string,
+  ): Promise<RouletteSessionRow | null> {
+    const rows = await this.model.findAll({ channel_key: channelKeyValue, status: 'active' });
+    const seated = rows.find((row) =>
+      decodeRouletteState(row.state_json).players.some((player) => player.id === userId));
+    return seated ?? null;
+  }
+
+  async applyAction(
+    session: RouletteSessionRow,
+    actorId: string,
+    action: RouletteAction,
+    config: RouletteConfig,
+  ): Promise<RouletteActionResult> {
+    if (action.type === 'join') {
+      await this.assertPlayersAvailable(session.channel_key, [action.player.id]);
+    }
+    const result = await this.mutateSession(session.id, {
+      actionId: `${session.id}:${session.revision}:${actorId}:${action.type}`,
+      expectedRevision: session.revision,
+      apply: (current) => {
+        const before = decodeRouletteState(current.state_json);
+        const after = this.#transition(before, actorId, action, config);
+        return rowPatch(after, config, Date.now());
+      },
+    });
+    return {
+      session: result.session,
+      state: decodeRouletteState(result.session.state_json),
+      applied: result.kind === 'applied',
+    };
+  }
+
+  /** Open sessions whose lobby or turn deadline has passed. */
+  async listOverdue(now: number): Promise<readonly RouletteSessionRow[]> {
+    const rows = await this.model.findAll({ status: 'active' });
+    return rows.filter((row) => row.deadline_at > 0 && row.deadline_at <= now);
+  }
+
+  #transition(
+    state: RouletteState,
+    actorId: string,
+    action: RouletteAction,
+    config: RouletteConfig,
+  ): RouletteState {
+    switch (action.type) {
+      case 'join':
+        return joinLobby(state, action.player, tableRules(config));
+      case 'start':
+        return startRound(state, actorId, this.#chooseBulletChamber(state.chamberCount));
+      case 'fire':
+        return pullTrigger(state, actorId).state;
+      case 'leave':
+        return leaveGame(state, actorId);
+      case 'cancel':
+        return cancelGame(state);
+      case 'expire':
+        return state.phase === 'lobby' ? expireLobby(state) : expireTurn(state);
+    }
+  }
+}
+
+interface GroupSettingsModel {
+  findOne(query: Record<string, unknown>): Promise<RouletteGroupSettingsRow | null>;
+  create(row: RouletteGroupSettingsRow): Promise<unknown>;
+  updateWhere(where: Record<string, unknown>, patch: Partial<RouletteGroupSettingsRow>): Promise<unknown>;
+}
+
+interface GroupSettingsDatabase {
+  readonly models: { get(name: string): unknown };
+}
+
+/** Per-group switches. The mute penalty is off until a group turns it on. */
+export class RouletteGroupSettings {
+  readonly #model: GroupSettingsModel;
+
+  constructor(database: RouletteDatabase) {
+    const model = (database as unknown as GroupSettingsDatabase).models.get('roulette_group_settings');
+    if (!model) throw new Error('roulette_group_settings not registered');
+    this.#model = model as GroupSettingsModel;
+  }
+
+  async isMutePenaltyEnabled(channelKeyValue: string): Promise<boolean> {
+    const row = await this.#model.findOne({ id: channelKeyValue });
+    return row?.mute_penalty === 1;
+  }
+
+  async setMutePenalty(channelKeyValue: string, enabled: boolean, actorId: string): Promise<void> {
+    const patch = {
+      mute_penalty: enabled ? 1 : 0,
+      updated_by: actorId,
+      updated_at: Date.now(),
+    };
+    const existing = await this.#model.findOne({ id: channelKeyValue });
+    if (existing) {
+      await this.#model.updateWhere({ id: channelKeyValue }, patch);
+      return;
+    }
+    await this.#model.create({ id: channelKeyValue, ...patch });
+  }
+}
+
+export interface RouletteServices {
+  readonly sessions: RouletteSessionService;
+  readonly settings: RouletteGroupSettings;
+}
+
+export function createServices(
+  database: RouletteDatabase,
+  options: RouletteServiceOptions = {},
+): RouletteServices {
+  return {
+    sessions: new RouletteSessionService(database, options),
+    settings: new RouletteGroupSettings(database),
+  };
+}
+
+export function stateOf(session: RouletteSessionRow): RouletteState {
+  return decodeRouletteState(session.state_json);
+}
+
+export function playerFromMessage(message: GamePlayer): RoulettePlayer {
+  const name = message.sender.name?.trim() || message.sender.id;
+  return { id: message.sender.id, name };
+}
+
+function tableRules(config: RouletteConfig): RouletteTableRules {
+  return { chamberCount: config.chambers, maxPlayers: config.maxPlayers };
+}
+
+function rowPatch(state: RouletteState, config: RouletteConfig, now: number): Partial<RouletteSessionRow> {
+  return {
+    state_json: JSON.stringify(state),
+    phase: state.phase,
+    turn: currentPlayer(state)?.id ?? '',
+    host_id: state.hostId,
+    deadline_at: deadlineFor(state, config, now),
+    status: statusFor(state),
+  };
+}
+
+function deadlineFor(state: RouletteState, config: RouletteConfig, now: number): number {
+  if (state.phase === 'playing') return now + config.turnTimeoutSeconds * 1000;
+  if (state.phase === 'lobby') return now + config.lobbyTimeoutSeconds * 1000;
+  return 0;
+}
+
+function statusFor(state: RouletteState): RouletteSessionStatus {
+  if (isOpen(state)) return 'active';
+  if (state.phase === 'finished') return 'finished';
+  return 'aborted';
+}
+
+/** Survivors win one point each; the loser records a loss. Aborted games record nothing. */
+function projectRouletteOutcomes(session: Readonly<RouletteSessionRow>): readonly GameOutcome[] {
+  if (session.status !== 'finished') return [];
+  const state = decodeRouletteState(session.state_json);
+  return state.players.map((player) => {
+    const lost = player.id === state.loserId;
+    return {
+      userId: player.id,
+      userName: player.name,
+      result: lost ? 'lost' : 'won',
+      score: lost ? 0 : 1,
+    };
+  });
+}

package/src/view.ts

@@ -0,0 +1,89 @@
+import { createMessages } from 'zhin.js/i18n';
+import type { GamePlayer } from '@zhin.js/game-kit';
+import type { RouletteConfig } from './config.js';
+import { MIN_ROULETTE_PLAYERS, currentPlayer, loserOf, remainingChambers, survivorsOf,
+  type RoulettePlayer, type RouletteState } from './engine.js';
+
+type Presentation = Pick<GamePlayer, 'locale' | 'formatCommand'>;
+const messages = createMessages({
+  title: { 'zh-CN': '🔫 俄罗斯轮盘', en: '🔫 Russian Roulette' },
+  lobby: { 'zh-CN': '{title} · 等待玩家（{count}/{max}）', en: '{title} · Waiting for players ({count}/{max})' },
+  players: { 'zh-CN': '玩家：{players}', en: 'Players: {players}' },
+  host: { 'zh-CN': '房主', en: 'Host' },
+  joinStart: { 'zh-CN': '发送「{join}」上桌；{host} 发送「{start}」开局（至少 {min} 人）。', en: 'Send “{join}” to join. {host}: send “{start}” to start (at least {min} players).' },
+  lobbyExpiry: { 'zh-CN': '{seconds} 秒内没有开始会自动解散。', en: 'The lobby closes if the game does not start within {seconds} seconds.' },
+  started: { 'zh-CN': '{title} · 开局！{chambers} 个弹巢里装了 1 发子弹，已转好弹巢。', en: '{title} · Started! One bullet in {chambers} chambers. The cylinder has been spun.' },
+  order: { 'zh-CN': '开枪顺序：', en: 'Turn order:' },
+  turn: { 'zh-CN': '👉 轮到 {name}：{instruction}{seconds} 秒内不开枪判负。（剩余 {chambers} 个弹巢）', en: '👉 {name} to play: {instruction}pull the trigger within {seconds} seconds or lose. ({chambers} chambers remaining)' },
+  fire: { 'zh-CN': '发送「{command}」，', en: 'send “{command}”; ' },
+  click: { 'zh-CN': '咔哒……{name} 的这一枪是空膛。', en: 'Click… {name} found an empty chamber.' },
+  survived: { 'zh-CN': '🏆 幸存：{names}（各 +1 胜）', en: '🏆 Survivors: {names} (+1 win each)' },
+  leaderboard: { 'zh-CN': '可在游戏大厅查看本群排行。', en: 'The group leaderboard is available in the game lobby.' },
+  expired: { 'zh-CN': '{title} 长时间没有开始，已自动解散。', en: '{title}: the lobby expired before the game started.' },
+  empty: { 'zh-CN': '{title} 所有人都离开了，已解散。', en: '{title}: everyone left; the lobby is closed.' },
+  aborted: { 'zh-CN': '{title} 已取消，本局不计分。', en: '{title}: cancelled. No scores were recorded.' },
+  status: { 'zh-CN': '{title} · 进行中，已开 {pulls} 枪', en: '{title} · In progress, {pulls} trigger pulls' },
+  timeout: { 'zh-CN': '⌛ {name} 超时没有开枪，判负！', en: '⌛ {name} ran out of time and loses!' },
+  forfeit: { 'zh-CN': '🏳️ {name} 中途离场，判负！', en: '🏳️ {name} left the game and forfeits!' },
+  shot: { 'zh-CN': '💥 砰！{name} 中弹出局（第 {pulls} 枪）。', en: '💥 Bang! {name} is out (trigger pull {pulls}).' },
+  none: { 'zh-CN': '无', en: 'None' },
+});
+export const ROULETTE_TITLE = messages('zh-CN', 'title');
+
+export function describeLobby(state: RouletteState, config: RouletteConfig, presentation: Presentation = {}): string {
+  const locale = presentation.locale;
+  const host = state.players.find(player => player.id === state.hostId);
+  const command = presentation.formatCommand?.('roulette');
+  return [messages(locale, 'lobby', { title: messages(locale, 'title'), count: state.players.length, max: config.maxPlayers }),
+    messages(locale, 'players', { players: listNames(state.players, presentation) }),
+    ...(command === undefined ? [] : [messages(locale, 'joinStart', { join: `${command} join`, start: `${command} start`, host: host?.name ?? messages(locale, 'host'), min: MIN_ROULETTE_PLAYERS })]),
+    messages(locale, 'lobbyExpiry', { seconds: config.lobbyTimeoutSeconds }),
+  ].join('\n');
+}
+
+export function describeRoundStart(state: RouletteState, config: RouletteConfig, presentation: Presentation = {}): string {
+  return [messages(presentation.locale, 'started', { title: messages(presentation.locale, 'title'), chambers: state.chamberCount }),
+    messages(presentation.locale, 'order'), ...state.players.map((player, index) => `${index + 1}. ${player.name}`),
+    describeTurn(state, config, presentation),
+  ].join('\n');
+}
+
+export function describeTurn(state: RouletteState, config: RouletteConfig, presentation: Presentation = {}): string {
+  const shooter = currentPlayer(state);
+  if (!shooter) return '';
+  const command = presentation.formatCommand?.('roulette');
+  return messages(presentation.locale, 'turn', { name: shooter.name, seconds: config.turnTimeoutSeconds,
+    chambers: remainingChambers(state), instruction: command === undefined ? ''
+      : messages(presentation.locale, 'fire', { command: `${command} fire` }) });
+}
+
+export function describeClick(shooter: RoulettePlayer, state: RouletteState, config: RouletteConfig, presentation: Presentation = {}): string {
+  return [messages(presentation.locale, 'click', { name: shooter.name }), describeTurn(state, config, presentation)].join('\n');
+}
+
+export function describeEnding(state: RouletteState, presentation: Presentation = {}): string {
+  const loser = loserOf(state);
+  if (!loser) return describeAbort(state, presentation);
+  const key = state.endReason === 'turn-timeout' ? 'timeout' : state.endReason === 'forfeit' ? 'forfeit' : 'shot';
+  return [messages(presentation.locale, key, { name: loser.name, pulls: state.pullsMade }),
+    messages(presentation.locale, 'survived', { names: listNames(survivorsOf(state), presentation) }),
+    messages(presentation.locale, 'leaderboard'),
+  ].join('\n');
+}
+
+export function describeAbort(state: RouletteState, presentation: Presentation = {}): string {
+  return messages(presentation.locale, state.endReason === 'lobby-expired' ? 'expired' : state.endReason === 'lobby-empty' ? 'empty' : 'aborted',
+    { title: messages(presentation.locale, 'title') });
+}
+
+export function describeStatus(state: RouletteState, config: RouletteConfig, presentation: Presentation = {}): string {
+  if (state.phase === 'lobby') return describeLobby(state, config, presentation);
+  return [messages(presentation.locale, 'status', { title: messages(presentation.locale, 'title'), pulls: state.pullsMade }),
+    messages(presentation.locale, 'players', { players: listNames(state.players, presentation) }),
+    describeTurn(state, config, presentation),
+  ].join('\n');
+}
+
+function listNames(players: readonly RoulettePlayer[], presentation: Presentation): string {
+  return players.length ? players.map(player => player.name).join(presentation.locale === 'en' ? ', ' : '、') : messages(presentation.locale, 'none');
+}