steamsheep-ts-game-engine 2.0.0 → 3.0.0

package/dist/ui/index.d.mts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { L as LogEntry } from '../types-BLjkeE3R.mjs';
+import { L as LogEntry } from '../types-C3Q7UPWy.mjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 interface LayoutProps {

package/dist/ui/index.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { L as LogEntry } from '../types-BLjkeE3R.js';
+import { L as LogEntry } from '../types-C3Q7UPWy.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 interface LayoutProps {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "steamsheep-ts-game-engine",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "通用游戏引擎框架 - 基于 TypeScript 和 Zustand 构建的文字冒险/RPG 游戏引擎",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package/dist/types-BLjkeE3R.d.mts

@@ -1,536 +0,0 @@
-/**
- * 游戏状态接口 - 存储游戏的完整状态
- *
- * 这是整个游戏引擎的核心数据结构，包含了游戏运行所需的所有状态信息。
- * 使用泛型使其适用于任何类型的游戏，无需修改引擎代码。
- *
- * @template S - 数值属性键的联合类型
- * @template I - 物品ID的联合类型
- * @template F - 标记键的联合类型
- *
- * @example
- * ```typescript
- * type RPGState = GameState<
- *   'hp' | 'mp' | 'gold',
- *   'sword' | 'potion',
- *   'dragon_defeated' | 'has_key'
- * >;
- * ```
- */
-interface GameState<S extends string, I extends string, F extends string, X = Record<string, unknown>> {
-    /**
-     * 数值属性记录 (如生命值、金币、经验等)
-     * 使用Record类型确保所有定义的属性都有对应的数值
-     */
-    stats: Record<S, number>;
-    /**
-     * 物品清单 - 存储玩家拥有的物品ID
-     * 使用数组允许同一物品多次出现（如多个药水）
-     */
-    inventory: I[];
-    /**
-     * 布尔标记 - 用于追踪游戏状态、任务进度等
-     * 常用于记录剧情进度、解锁状态、触发条件等
-     */
-    flags: Record<F, boolean>;
-    /**
-     * 世界状态 - 包含位置、时间等世界级信息
-     */
-    world: WorldState;
-    /**
-     * 日志条目数组 - 记录游戏事件
-     * 用于显示游戏历史和玩家操作反馈
-     */
-    logs: LogEntry[];
-    /**
-     * 扩展数据 - 存储游戏特定的额外状态
-     *
-     * 这是一个灵活的字段，允许不同游戏存储自定义数据。
-     * 使用泛型 X 来定义具体的扩展数据类型。
-     *
-     * @example
-     * ```typescript
-     * // 定义扩展数据类型
-     * interface MyGameExtra {
-     *   reputation: number;
-     *   guild: string;
-     *   achievements: string[];
-     * }
-     *
-     * // 使用扩展数据
-     * type MyGameState = GameState<Stats, Items, Flags, MyGameExtra>;
-     * ```
-     */
-    extra: X;
-}
-/**
- * 世界状态接口 - 追踪游戏世界的时间和位置信息
- */
-interface WorldState {
-    /** 当前所在位置的唯一标识符 */
-    currentLocationId: string;
-    /** 游戏内的天数 - 用于追踪游戏进度 */
-    day: number;
-    /** 当前时间 - 可以是0-24的小时制或自定义时间单位 */
-    time: number;
-}
-/**
- * 日志条目接口 - 记录游戏中发生的事件
- *
- * ⚠️ 重要：LogEntry 是持久化的历史记录，会被保存到 localStorage
- *
- * 用于构建游戏日志系统，记录玩家操作、系统事件等信息。
- * 每条日志都有类型标记，便于UI层进行样式区分和过滤。
- *
- * 日志会：
- * - 被保存到 localStorage
- * - 在页面刷新后重新加载
- * - 永久显示在日志面板中
- * - 可以被玩家回顾
- */
-interface LogEntry {
-    /**
-     * 唯一标识符 - 用于React列表渲染的key
-     * 建议使用UUID或时间戳+随机数生成
-     */
-    id: string;
-    /**
-     * 日志文本内容 - 显示给玩家的消息
-     * 可以包含动态内容，如玩家名称、物品名称等
-     */
-    text: string;
-    /**
-     * 日志类型 - 用于UI显示不同样式和图标
-     * - info: 普通信息（灰色）
-     * - warn: 警告信息（黄色）
-     * - error: 错误信息（红色）
-     * - success: 成功信息（绿色）
-     * - result: 动作执行结果（黑色）
-     */
-    type: "info" | "warn" | "error" | "success" | "result";
-    /**
-     * 日志产生的时间戳 - 游戏内时间或真实时间戳
-     * 用于排序和显示时间信息
-     */
-    timestamp: number;
-}
-/**
- * 通知类型枚举
- *
- * ⚠️ 重要：通知是瞬时的 UI 状态，不会被持久化
- *
- * 定义不同强度的通知方式：
- * - toast: 飘字提示（轻量级，自动消失，不阻塞）
- * - modal: 弹窗消息（强提示，需要用户确认，阻塞式）
- */
-type NotificationType = 'toast' | 'modal';
-/**
- * 通知载荷 - 用于事件系统传递瞬时通知
- *
- * ⚠️ 与 LogEntry 的区别：
- * - NotificationPayload: 瞬时通知，不持久化，用于 UI 反馈
- * - LogEntry: 历史记录，持久化，用于回顾
- *
- * 通知会：
- * - 通过事件系统发送
- * - 仅在当前会话中显示
- * - 不会被保存到 localStorage
- * - 不会在页面刷新后重新出现
- */
-interface NotificationPayload {
-    /** 通知文本 */
-    text: string;
-    /** 通知类型（影响样式） */
-    type: LogEntry['type'];
-    /** 通知方式（toast 或 modal） */
-    notificationType: NotificationType;
-    /** 时间戳（仅用于生成唯一 ID 和去重，不在 UI 中显示） */
-    timestamp: number;
-}
-/**
- * 数值需求类型 - 定义属性检查的方式
- *
- * 可以是简单的数值（精确匹配）或范围对象（最小/最大值）
- *
- * @example
- * ```typescript
- * // 精确需求: 必须有10点体力
- * const exact: StatRequirement = 10;
- *
- * // 范围需求: 体力必须在5-20之间
- * const range: StatRequirement = { min: 5, max: 20 };
- *
- * // 最小需求: 至少需要5点体力
- * const minimum: StatRequirement = { min: 5 };
- * ```
- */
-type StatRequirement = number | {
-    min?: number;
-    max?: number;
-};
-/**
- * 需求定义接口 - 定义执行动作前必须满足的条件
- *
- * 用于检查玩家是否有资格执行某个动作。
- * 需求检查不会消耗资源，只是判断是否满足条件。
- *
- * @template S - 数值属性键的联合类型
- * @template I - 物品ID的联合类型
- * @template F - 标记键的联合类型
- *
- * @example
- * ```typescript
- * // 简单需求
- * const simpleReqs: RequirementDef<Stats, Items, Flags> = {
- *   hasItems: ['key'],
- *   stats: { strength: { min: 5 } }
- * };
- *
- * // 复杂逻辑使用 custom 函数
- * const complexReqs: RequirementDef<Stats, Items, Flags> = {
- *   custom: (state) => {
- *     // (有钥匙 AND 力量>=5) OR 有万能钥匙
- *     const hasKeyAndStrength =
- *       state.inventory.includes('key') && state.stats.strength >= 5;
- *     const hasMasterKey = state.inventory.includes('master_key');
- *     return hasKeyAndStrength || hasMasterKey;
- *   }
- * };
- * ```
- */
-interface RequirementDef<S extends string, I extends string, F extends string, X = Record<string, unknown>> {
-    /**
-     * 数值属性需求 - 检查玩家属性是否满足条件
-     * 使用Partial允许只检查部分属性
-     * 所有指定的属性必须同时满足（AND逻辑）
-     */
-    stats?: Partial<Record<S, StatRequirement>>;
-    /**
-     * 必须拥有的物品列表
-     * 玩家库存中必须包含所有列出的物品（AND逻辑）
-     */
-    hasItems?: I[];
-    /**
-     * 不能拥有的物品列表
-     * 玩家库存中不能包含任何列出的物品（OR逻辑）
-     */
-    noItems?: I[];
-    /**
-     * 必须为true的标记列表
-     * 所有列出的标记必须已设置为true（AND逻辑）
-     */
-    hasFlags?: F[];
-    /**
-     * 必须为false的标记列表
-     * 所有列出的标记必须为false或未设置（OR逻辑）
-     */
-    noFlags?: F[];
-    /**
-     * 自定义需求函数 - 用于复杂逻辑
-     *
-     * 当需要表达复杂的逻辑关系时使用此函数。
-     * 函数接收完整的游戏状态，返回true表示满足需求。
-     *
-     * 可以在函数中实现任意复杂的逻辑，包括：
-     * - OR 逻辑：A || B
-     * - 复杂组合：(A && B) || C
-     * - 嵌套逻辑：((A || B) && C) || D
-     * - 动态计算：基于多个状态的复杂判断
-     *
-     * @param state - 当前游戏状态
-     * @returns true表示满足需求，false表示不满足
-     *
-     * @example
-     * ```typescript
-     * // 示例1：OR 逻辑 - 有钥匙或撬锁工具
-     * custom: (state) =>
-     *   state.inventory.includes('key') ||
-     *   state.inventory.includes('lockpick')
-     *
-     * // 示例2：复杂组合 - (有钥匙 AND 力量>=5) OR 有万能钥匙
-     * custom: (state) => {
-     *   const hasKeyAndStrength =
-     *     state.inventory.includes('key') && state.stats.strength >= 5;
-     *   const hasMasterKey = state.inventory.includes('master_key');
-     *   return hasKeyAndStrength || hasMasterKey;
-     * }
-     *
-     * // 示例3：时间相关 - 夜晚时间
-     * custom: (state) =>
-     *   state.world.time >= 18 || state.world.time <= 6
-     *
-     * // 示例4：使用扩展数据
-     * custom: (state) =>
-     *   state.extra.reputation >= 100
-     * ```
-     */
-    custom?: (state: GameState<S, I, F, X>) => boolean;
-}
-/**
- * 效果定义接口 - 定义动作执行后对游戏状态的改变
- *
- * 描述执行动作后会产生的所有效果，包括属性变化、物品变化、
- * 标记设置、位置传送等。所有效果会同时应用。
- *
- * @template S - 数值属性键的联合类型
- * @template I - 物品ID的联合类型
- * @template F - 标记键的联合类型
- *
- * @example
- * ```typescript
- * const drinkPotionEffect: EffectDef<Stats, Items, Flags> = {
- *   statsChange: { hp: 20 },      // 恢复20点生命值
- *   itemsRemove: ['potion'],      // 消耗药水
- *   flagsSet: { used_potion: true } // 标记已使用过药水
- * };
- * ```
- */
-interface EffectDef<S extends string, I extends string, F extends string, X = Record<string, unknown>> {
-    /**
-     * 数值属性变更
-     * 正数表示增加，负数表示减少
-     * 例如: { hp: 10, gold: -5 } 表示增加10点生命值，减少5金币
-     */
-    statsChange?: Partial<Record<S, number>>;
-    /**
-     * 添加到库存的物品列表
-     * 物品会被添加到玩家的inventory数组中
-     */
-    itemsAdd?: I[];
-    /**
-     * 从库存移除的物品列表
-     * 每个物品只会移除一次（如果有多个相同物品）
-     */
-    itemsRemove?: I[];
-    /**
-     * 标记设置
-     * 设置指定标记的布尔值
-     * 例如: { quest_completed: true, door_locked: false }
-     */
-    flagsSet?: Partial<Record<F, boolean>>;
-    /**
-     * 传送目标位置ID
-     * 如果设置，玩家会被传送到指定位置
-     */
-    teleport?: string;
-    /**
-     * 触发特殊事件的标识符
-     * 用于触发游戏中的特殊事件或剧情
-     */
-    triggerEvent?: string;
-    /**
-     * 自定义效果函数 - 用于修改扩展数据
-     *
-     * 当需要修改 extra 字段中的自定义数据时使用。
-     * 函数接收当前的 extra 数据和完整游戏状态。
-     * 可以直接修改 draft（Immer 风格），或返回部分更新。
-     *
-     * @param draft - 当前的扩展数据（可直接修改）
-     * @param state - 完整的游戏状态（只读）
-     * @returns void 或部分更新对象
-     *
-     * @example
-     * ```typescript
-     * // 示例1：直接修改 draft
-     * custom: (draft) => {
-     *   draft.reputation += 10;
-     *   draft.achievements.push('first_quest');
-     * }
-     *
-     * // 示例2：返回部分更新
-     * custom: (draft, state) => {
-     *   return {
-     *     reputation: draft.reputation + 10,
-     *     lastAction: Date.now()
-     *   };
-     * }
-     * ```
-     */
-    custom?: (draft: X, state: GameState<S, I, F, X>) => void | Partial<X>;
-}
-/**
- * 动作定义接口 - 定义玩家可以执行的动作
- *
- * 动作是游戏交互的核心，包含了动作的显示信息、执行条件、
- * 消耗成本和产生的效果。
- *
- * @template S - 数值属性键的联合类型
- * @template I - 物品ID的联合类型
- * @template F - 标记键的联合类型
- *
- * @example
- * ```typescript
- * const attackAction: ActionDef<Stats, Items, Flags> = {
- *   id: 'attack_goblin',
- *   label: '攻击哥布林',
- *   description: '用你的武器攻击哥布林',
- *   costs: { stamina: 10 },       // 消耗10点体力
- *   requirements: {
- *     hasItems: ['weapon']         // 需要武器
- *   },
- *   effects: {
- *     statsChange: { exp: 5 },     // 获得5点经验
- *     flagsSet: { goblin_defeated: true }
- *   },
- *   resultText: '你击败了哥布林！'
- * };
- * ```
- */
-interface ActionDef<S extends string, I extends string, F extends string, X = Record<string, unknown>> {
-    /** 动作的唯一标识符 */
-    id: string;
-    /**
-     * 动作标签 - 显示在UI上的动作名称
-     * 可以是静态字符串或根据游戏状态动态生成的函数
-     */
-    label: string | ((state: GameState<S, I, F>) => string);
-    /**
-     * 动作描述 - 详细说明动作的效果
-     * 可选，可以是静态字符串或动态函数
-     */
-    description?: string | ((state: GameState<S, I, F>) => string);
-    /**
-     * 执行成本 - 执行动作时刚性扣除的资源
-     *
-     * 与requirements不同，costs会实际消耗资源。
-     * 例如: { stamina: 10, gold: 5 } 会扣除10点体力和5金币
-     */
-    costs?: Partial<Record<S, number>>;
-    /**
-     * 执行需求 - 执行动作前必须满足的条件
-     *
-     * 需求检查不会消耗资源，只是判断是否有资格执行。
-     * 如果不满足需求，动作将无法执行。
-     */
-    requirements?: RequirementDef<S, I, F, X>;
-    /**
-     * 执行效果 - 动作成功执行后产生的效果
-     *
-     * 包括属性变化、物品获得/失去、标记设置等。
-     * 所有效果会在扣除costs后立即应用。
-     */
-    effects?: EffectDef<S, I, F, X>;
-    /**
-     * 结果文本 - 动作执行后显示给玩家的反馈信息
-     * 可以是静态字符串或根据游戏状态动态生成的函数
-     */
-    resultText: string | ((state: GameState<S, I, F, X>) => string);
-}
-/**
- * 地点定义接口 - 定义游戏中的一个地点/场景
- *
- * 地点是游戏世界的基本单位，包含地点信息和可执行的动作列表。
- * 玩家在不同地点之间移动，每个地点提供不同的动作选项。
- *
- * @template S - 数值属性键的联合类型
- * @template I - 物品ID的联合类型
- * @template F - 标记键的联合类型
- * @template X - 扩展数据类型（默认为 Record<string, unknown>）
- *
- * @example
- * ```typescript
- * // 基础用法
- * const tavern: LocationDef<Stats, Items, Flags> = {
- *   id: 'tavern',
- *   name: '酒馆',
- *   description: '一个热闹的酒馆，充满了冒险者',
- *   actionIds: ['buy_drink', 'talk_bartender', 'rest'],
- *   extra: {}
- * };
- *
- * // 使用自定义扩展数据
- * interface LocationEnvironment {
- *   temperature: number;
- *   humidity: number;
- *   lightLevel: number;
- * }
- *
- * const cave: LocationDef<Stats, Items, Flags, LocationEnvironment> = {
- *   id: 'cave',
- *   name: '洞穴',
- *   description: (state) => {
- *     // 可以访问 state.extra
- *     const temp = state.extra.temperature;
- *     return temp < 0 ? '寒冷的洞穴' : '阴暗的洞穴';
- *   },
- *   actionIds: ['explore'],
- *   extra: {
- *     temperature: -5,
- *     humidity: 80,
- *     lightLevel: 2
- *   }
- * };
- * ```
- */
-interface LocationDef<S extends string, I extends string, F extends string, X = Record<string, unknown>> {
-    /** 地点的唯一标识符 */
-    id: string;
-    /** 地点名称 - 显示在UI上的地点名称 */
-    name: string;
-    /**
-     * 地点描述 - 描述地点的外观、氛围等
-     * 可以是静态字符串或根据游戏状态动态生成的函数
-     * 例如：根据时间显示不同的描述
-     */
-    description: string | ((state: GameState<S, I, F, X>) => string);
-    /**
-     * 该地点可执行的动作ID列表
-     *
-     * 存储动作ID而非完整的ActionDef对象，通过动作注册表查找实际定义。
-     * 这种设计提供了更好的解耦和灵活性：
-     * - 同一个动作可以在多个地点复用
-     * - 动作定义可以独立修改而不影响地点定义
-     * - 减少数据冗余和内存占用
-     *
-     * 使用时需要配合ActionRegistry来查找完整的动作定义。
-     */
-    actionIds: string[];
-    /**
-     * 扩展数据 - 存储地点特定的额外信息
-     *
-     * 这是一个灵活的字段，允许不同游戏为地点存储自定义元数据。
-     * 使用泛型 X 来定义具体的扩展数据类型。
-     *
-     * 常见用途：
-     * - 环境参数（温度、湿度、光照等）
-     * - 地点元数据（类别、发现时间、访问次数等）
-     * - 特殊属性（危险度、资源丰富度等）
-     * - 动态状态（天气、时间相关的变化等）
-     *
-     * @example
-     * ```typescript
-     * // 定义环境参数类型
-     * interface LocationEnvironment {
-     *   temperature: number;
-     *   humidity: number;
-     *   lightLevel: number;
-     *   danger: number;
-     * }
-     *
-     * // 使用扩展数据
-     * type MyLocation = LocationDef<Stats, Items, Flags, LocationEnvironment>;
-     *
-     * const location: MyLocation = {
-     *   id: 'forest',
-     *   name: '森林',
-     *   description: (state) => {
-     *     // 在 description 函数中访问扩展数据
-     *     if (state.extra.danger > 5) {
-     *       return '这片森林看起来很危险...';
-     *     }
-     *     return '一片宁静的森林';
-     *   },
-     *   actionIds: ['explore'],
-     *   extra: {
-     *     temperature: 20,
-     *     humidity: 60,
-     *     lightLevel: 8,
-     *     danger: 3
-     *   }
-     * };
-     * ```
-     */
-    extra: X;
-}
-
-export type { ActionDef as A, EffectDef as E, GameState as G, LogEntry as L, NotificationType as N, RequirementDef as R, StatRequirement as S, WorldState as W, NotificationPayload as a, LocationDef as b };