steamsheep-ts-game-engine 1.0.0

package/dist/store-BP5bpjRr.d.ts

@@ -0,0 +1,327 @@
+import * as zustand_middleware from 'zustand/middleware';
+import * as zustand from 'zustand';
+import { L as LogEntry, G as GameState } from './types-CZueoTHl.js';
+
+/**
+ * 游戏Store操作方法接口 - 定义所有可用的状态操作
+ *
+ * 这个接口定义了修改游戏状态的所有方法。所有方法都是原子操作，
+ * 确保状态更新的一致性和可预测性。
+ *
+ * @template S - 数值属性键的联合类型
+ * @template I - 物品ID的联合类型
+ * @template F - 标记键的联合类型
+ *
+ * @example
+ * ```typescript
+ * const useStore = createGameEngineStore(initialState);
+ *
+ * // 在组件中使用
+ * function GameComponent() {
+ *   const updateStat = useStore(state => state.updateStat);
+ *   const addItem = useStore(state => state.addItem);
+ *
+ *   const handleAction = () => {
+ *     updateStat('hp', -10);  // 减少10点生命值
+ *     addItem('potion');       // 获得药水
+ *   };
+ * }
+ * ```
+ */
+interface GameStoreActions<S extends string, I extends string, F extends string, X = Record<string, unknown>> {
+    /**
+     * 更新单个数值属性
+     *
+     * 对指定属性进行增量更新（正数增加，负数减少）。
+     * 这是最常用的属性修改方法。
+     *
+     * @param stat - 要更新的属性键
+     * @param delta - 变化量（正数增加，负数减少）
+     *
+     * @example
+     * ```typescript
+     * updateStat('hp', 20);    // 恢复20点生命值
+     * updateStat('gold', -50); // 花费50金币
+     * ```
+     */
+    updateStat: (stat: S, delta: number) => void;
+    /**
+     * 批量更新多个数值属性
+     *
+     * 一次性更新多个属性，所有更新在同一个状态变更中完成。
+     * 适用于需要同时修改多个属性的场景。
+     *
+     * @param stats - 属性变化的部分记录
+     *
+     * @example
+     * ```typescript
+     * setStats({ hp: 10, mp: -5, gold: 100 });
+     * // 同时增加10点生命值，减少5点魔法值，增加100金币
+     * ```
+     */
+    setStats: (stats: Partial<Record<S, number>>) => void;
+    setExtra: (updater: Partial<X> | ((prev: X) => Partial<X>)) => void;
+    /**
+     * 添加物品到库存
+     *
+     * 将指定物品添加到玩家的库存中。
+     * 同一物品可以多次添加（如多个药水）。
+     *
+     * @param item - 要添加的物品ID
+     *
+     * @example
+     * ```typescript
+     * addItem('health_potion');
+     * addItem('health_potion'); // 可以添加多个相同物品
+     * ```
+     */
+    addItem: (item: I) => void;
+    /**
+     * 从库存移除物品
+     *
+     * 从玩家库存中移除指定物品的一个实例。
+     * 如果有多个相同物品，只移除第一个匹配的。
+     *
+     * @param item - 要移除的物品ID
+     *
+     * @example
+     * ```typescript
+     * removeItem('health_potion'); // 移除一个生命药水
+     * ```
+     */
+    removeItem: (item: I) => void;
+    /**
+     * 设置布尔标记
+     *
+     * 设置或清除游戏标记，用于追踪任务进度、解锁状态等。
+     * 标记是游戏逻辑的重要组成部分。
+     *
+     * @param flag - 标记键
+     * @param value - 标记值（true或false）
+     *
+     * @example
+     * ```typescript
+     * setFlag('quest_completed', true);  // 标记任务完成
+     * setFlag('door_locked', false);     // 解锁门
+     * ```
+     */
+    setFlag: (flag: F, value: boolean) => void;
+    /**
+     * 添加日志条目
+     *
+     * ⚠️ 重要：日志是持久化的历史记录
+     *
+     * 向游戏日志中添加新的消息，用于记录游戏事件。
+     * 日志会：
+     * - 被保存到 localStorage
+     * - 在页面刷新后重新加载
+     * - 永久显示在日志面板中
+     * - 自动限制在最近50条
+     *
+     * @param text - 日志文本内容
+     * @param type - 日志类型（默认为'info'）
+     *
+     * @example
+     * ```typescript
+     * addLog('你进入了森林', 'info');
+     * addLog('击败了哥布林', 'result');
+     * addLog('获得了传说武器', 'success');
+     * ```
+     */
+    addLog: (text: string, type?: LogEntry['type']) => void;
+    /**
+     * 显示飘字通知
+     *
+     * ⚠️ 重要：飘字是瞬时通知，不会被持久化
+     *
+     * 显示一个轻量级的飘字提示，会自动消失。
+     * 飘字通知：
+     * - 不会被保存到 localStorage
+     * - 不会在页面刷新后重新出现
+     * - 仅在当前会话中显示
+     * - 适用于轻量级反馈
+     *
+     * @param text - 通知文本
+     * @param type - 通知类型（默认为'info'）
+     *
+     * @example
+     * ```typescript
+     * showToast('获得 10 金币', 'success');
+     * showToast('体力不足', 'warn');
+     * ```
+     */
+    showToast: (text: string, type?: LogEntry['type']) => void;
+    /**
+     * 显示弹窗通知
+     *
+     * ⚠️ 重要：弹窗是瞬时通知，不会被持久化
+     *
+     * 显示一个模态弹窗，需要用户确认才能关闭。
+     * 弹窗通知：
+     * - 不会被保存到 localStorage
+     * - 不会在页面刷新后重新出现
+     * - 仅在当前会话中显示
+     * - 适用于重要信息和阻塞式交互
+     *
+     * @param text - 通知文本
+     * @param type - 通知类型（默认为'info'）
+     *
+     * @example
+     * ```typescript
+     * showModal('任务完成！获得传说装备', 'success');
+     * showModal('警告：此操作不可撤销', 'warn');
+     * ```
+     */
+    showModal: (text: string, type?: LogEntry['type']) => void;
+    /**
+     * 推进游戏时间
+     *
+     * 增加游戏内的天数，用于时间相关的游戏机制。
+     *
+     * @param amount - 要增加的天数（默认为1）
+     *
+     * @example
+     * ```typescript
+     * advanceTime();    // 推进1天
+     * advanceTime(7);   // 推进7天
+     * ```
+     */
+    advanceTime: (amount?: number) => void;
+    /**
+     * 传送到指定地点
+     *
+     * 将玩家传送到指定的地点ID。
+     * 这是改变玩家位置的主要方法。
+     *
+     * @param locationId - 目标地点的ID
+     *
+     * @example
+     * ```typescript
+     * teleport('town_square');  // 传送到城镇广场
+     * teleport('dungeon_1');    // 传送到地牢
+     * ```
+     */
+    teleport: (locationId: string) => void;
+    /**
+     * 重置游戏状态
+     *
+     * 将游戏状态重置为初始状态，清空所有日志。
+     * 用于开始新游戏或重置当前进度。
+     *
+     * @example
+     * ```typescript
+     * reset(); // 开始新游戏
+     * ```
+     */
+    reset: () => void;
+    /**
+     * 保存当前状态快照
+     *
+     * 将当前游戏状态保存到历史记录中，用于后续的撤销操作。
+     * 快照会自动排除日志数据以节省内存。
+     *
+     * @example
+     * ```typescript
+     * saveSnapshot(); // 在重要操作前保存快照
+     * ```
+     */
+    saveSnapshot: () => void;
+    /**
+     * 撤销到上一个状态
+     *
+     * 恢复到上一个保存的快照状态。
+     * 如果没有可用的历史记录，操作失败并返回false。
+     *
+     * @returns 是否成功撤销
+     *
+     * @example
+     * ```typescript
+     * if (undo()) {
+     *   console.log('撤销成功');
+     * } else {
+     *   console.log('没有可撤销的历史记录');
+     * }
+     * ```
+     */
+    undo: () => boolean;
+}
+/**
+ * 游戏Store类型 - 组合数据和操作方法
+ *
+ * 这是完整的Store类型，包含游戏状态数据和所有操作方法。
+ * 使用交叉类型将GameState和GameStoreActions合并。
+ *
+ * @template S - 数值属性键的联合类型
+ * @template I - 物品ID的联合类型
+ * @template F - 标记键的联合类型
+ *
+ * @example
+ * ```typescript
+ * const useGameStore: GameStore<'hp' | 'mp', 'sword', 'quest_done'>;
+ * ```
+ */
+type GameStore<S extends string, I extends string, F extends string, X = Record<string, unknown>> = GameState<S, I, F, X> & GameStoreActions<S, I, F, X>;
+/**
+ * 创建游戏引擎Store的工厂函数
+ *
+ * 这是创建游戏状态管理Store的核心函数。它使用Zustand创建一个
+ * 带有持久化功能的状态管理器，自动将游戏状态保存到localStorage。
+ *
+ * 工厂模式的优势：
+ * - 可以创建多个独立的游戏实例
+ * - 每个实例有自己的初始状态和存档名称
+ * - 完全的类型安全和泛型支持
+ *
+ * @template S - 数值属性键的联合类型
+ * @template I - 物品ID的联合类型
+ * @template F - 标记键的联合类型
+ *
+ * @param initialState - 游戏的初始状态
+ * @param persistName - localStorage中的存档键名（默认：'generic-rpg-save'）
+ *
+ * @returns Zustand store hook，可在React组件中使用
+ *
+ * @example
+ * ```typescript
+ * // 定义游戏类型
+ * type Stats = 'hp' | 'mp' | 'gold';
+ * type Items = 'sword' | 'potion';
+ * type Flags = 'quest_completed';
+ *
+ * // 创建初始状态
+ * const initialState: GameState<Stats, Items, Flags> = {
+ *   stats: { hp: 100, mp: 50, gold: 0 },
+ *   inventory: [],
+ *   flags: { quest_completed: false },
+ *   world: { currentLocationId: 'start', day: 1, time: 0 },
+ *   logs: []
+ * };
+ *
+ * // 创建store
+ * export const useGameStore = createGameEngineStore(
+ *   initialState,
+ *   'my-rpg-save'
+ * );
+ *
+ * // 在组件中使用
+ * function GameUI() {
+ *   const hp = useGameStore(state => state.stats.hp);
+ *   const updateStat = useGameStore(state => state.updateStat);
+ *
+ *   return <button onClick={() => updateStat('hp', -10)}>受伤</button>;
+ * }
+ * ```
+ */
+declare const createGameEngineStore: <S extends string, I extends string, F extends string, X = Record<string, unknown>>(initialState: GameState<S, I, F, X>, persistName?: string) => zustand.UseBoundStore<Omit<zustand.StoreApi<GameStore<S, I, F, X>>, "persist"> & {
+    persist: {
+        setOptions: (options: Partial<zustand_middleware.PersistOptions<GameStore<S, I, F, X>, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void> | void;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: GameStore<S, I, F, X>) => void) => () => void;
+        onFinishHydration: (fn: (state: GameStore<S, I, F, X>) => void) => () => void;
+        getOptions: () => Partial<zustand_middleware.PersistOptions<GameStore<S, I, F, X>, unknown>>;
+    };
+}>;
+
+export { type GameStoreActions as G, type GameStore as a, createGameEngineStore as c };

package/dist/store-BeEHel1o.d.mts

@@ -0,0 +1,327 @@
+import * as zustand_middleware from 'zustand/middleware';
+import * as zustand from 'zustand';
+import { L as LogEntry, G as GameState } from './types-CZueoTHl.mjs';
+
+/**
+ * 游戏Store操作方法接口 - 定义所有可用的状态操作
+ *
+ * 这个接口定义了修改游戏状态的所有方法。所有方法都是原子操作，
+ * 确保状态更新的一致性和可预测性。
+ *
+ * @template S - 数值属性键的联合类型
+ * @template I - 物品ID的联合类型
+ * @template F - 标记键的联合类型
+ *
+ * @example
+ * ```typescript
+ * const useStore = createGameEngineStore(initialState);
+ *
+ * // 在组件中使用
+ * function GameComponent() {
+ *   const updateStat = useStore(state => state.updateStat);
+ *   const addItem = useStore(state => state.addItem);
+ *
+ *   const handleAction = () => {
+ *     updateStat('hp', -10);  // 减少10点生命值
+ *     addItem('potion');       // 获得药水
+ *   };
+ * }
+ * ```
+ */
+interface GameStoreActions<S extends string, I extends string, F extends string, X = Record<string, unknown>> {
+    /**
+     * 更新单个数值属性
+     *
+     * 对指定属性进行增量更新（正数增加，负数减少）。
+     * 这是最常用的属性修改方法。
+     *
+     * @param stat - 要更新的属性键
+     * @param delta - 变化量（正数增加，负数减少）
+     *
+     * @example
+     * ```typescript
+     * updateStat('hp', 20);    // 恢复20点生命值
+     * updateStat('gold', -50); // 花费50金币
+     * ```
+     */
+    updateStat: (stat: S, delta: number) => void;
+    /**
+     * 批量更新多个数值属性
+     *
+     * 一次性更新多个属性，所有更新在同一个状态变更中完成。
+     * 适用于需要同时修改多个属性的场景。
+     *
+     * @param stats - 属性变化的部分记录
+     *
+     * @example
+     * ```typescript
+     * setStats({ hp: 10, mp: -5, gold: 100 });
+     * // 同时增加10点生命值，减少5点魔法值，增加100金币
+     * ```
+     */
+    setStats: (stats: Partial<Record<S, number>>) => void;
+    setExtra: (updater: Partial<X> | ((prev: X) => Partial<X>)) => void;
+    /**
+     * 添加物品到库存
+     *
+     * 将指定物品添加到玩家的库存中。
+     * 同一物品可以多次添加（如多个药水）。
+     *
+     * @param item - 要添加的物品ID
+     *
+     * @example
+     * ```typescript
+     * addItem('health_potion');
+     * addItem('health_potion'); // 可以添加多个相同物品
+     * ```
+     */
+    addItem: (item: I) => void;
+    /**
+     * 从库存移除物品
+     *
+     * 从玩家库存中移除指定物品的一个实例。
+     * 如果有多个相同物品，只移除第一个匹配的。
+     *
+     * @param item - 要移除的物品ID
+     *
+     * @example
+     * ```typescript
+     * removeItem('health_potion'); // 移除一个生命药水
+     * ```
+     */
+    removeItem: (item: I) => void;
+    /**
+     * 设置布尔标记
+     *
+     * 设置或清除游戏标记，用于追踪任务进度、解锁状态等。
+     * 标记是游戏逻辑的重要组成部分。
+     *
+     * @param flag - 标记键
+     * @param value - 标记值（true或false）
+     *
+     * @example
+     * ```typescript
+     * setFlag('quest_completed', true);  // 标记任务完成
+     * setFlag('door_locked', false);     // 解锁门
+     * ```
+     */
+    setFlag: (flag: F, value: boolean) => void;
+    /**
+     * 添加日志条目
+     *
+     * ⚠️ 重要：日志是持久化的历史记录
+     *
+     * 向游戏日志中添加新的消息，用于记录游戏事件。
+     * 日志会：
+     * - 被保存到 localStorage
+     * - 在页面刷新后重新加载
+     * - 永久显示在日志面板中
+     * - 自动限制在最近50条
+     *
+     * @param text - 日志文本内容
+     * @param type - 日志类型（默认为'info'）
+     *
+     * @example
+     * ```typescript
+     * addLog('你进入了森林', 'info');
+     * addLog('击败了哥布林', 'result');
+     * addLog('获得了传说武器', 'success');
+     * ```
+     */
+    addLog: (text: string, type?: LogEntry['type']) => void;
+    /**
+     * 显示飘字通知
+     *
+     * ⚠️ 重要：飘字是瞬时通知，不会被持久化
+     *
+     * 显示一个轻量级的飘字提示，会自动消失。
+     * 飘字通知：
+     * - 不会被保存到 localStorage
+     * - 不会在页面刷新后重新出现
+     * - 仅在当前会话中显示
+     * - 适用于轻量级反馈
+     *
+     * @param text - 通知文本
+     * @param type - 通知类型（默认为'info'）
+     *
+     * @example
+     * ```typescript
+     * showToast('获得 10 金币', 'success');
+     * showToast('体力不足', 'warn');
+     * ```
+     */
+    showToast: (text: string, type?: LogEntry['type']) => void;
+    /**
+     * 显示弹窗通知
+     *
+     * ⚠️ 重要：弹窗是瞬时通知，不会被持久化
+     *
+     * 显示一个模态弹窗，需要用户确认才能关闭。
+     * 弹窗通知：
+     * - 不会被保存到 localStorage
+     * - 不会在页面刷新后重新出现
+     * - 仅在当前会话中显示
+     * - 适用于重要信息和阻塞式交互
+     *
+     * @param text - 通知文本
+     * @param type - 通知类型（默认为'info'）
+     *
+     * @example
+     * ```typescript
+     * showModal('任务完成！获得传说装备', 'success');
+     * showModal('警告：此操作不可撤销', 'warn');
+     * ```
+     */
+    showModal: (text: string, type?: LogEntry['type']) => void;
+    /**
+     * 推进游戏时间
+     *
+     * 增加游戏内的天数，用于时间相关的游戏机制。
+     *
+     * @param amount - 要增加的天数（默认为1）
+     *
+     * @example
+     * ```typescript
+     * advanceTime();    // 推进1天
+     * advanceTime(7);   // 推进7天
+     * ```
+     */
+    advanceTime: (amount?: number) => void;
+    /**
+     * 传送到指定地点
+     *
+     * 将玩家传送到指定的地点ID。
+     * 这是改变玩家位置的主要方法。
+     *
+     * @param locationId - 目标地点的ID
+     *
+     * @example
+     * ```typescript
+     * teleport('town_square');  // 传送到城镇广场
+     * teleport('dungeon_1');    // 传送到地牢
+     * ```
+     */
+    teleport: (locationId: string) => void;
+    /**
+     * 重置游戏状态
+     *
+     * 将游戏状态重置为初始状态，清空所有日志。
+     * 用于开始新游戏或重置当前进度。
+     *
+     * @example
+     * ```typescript
+     * reset(); // 开始新游戏
+     * ```
+     */
+    reset: () => void;
+    /**
+     * 保存当前状态快照
+     *
+     * 将当前游戏状态保存到历史记录中，用于后续的撤销操作。
+     * 快照会自动排除日志数据以节省内存。
+     *
+     * @example
+     * ```typescript
+     * saveSnapshot(); // 在重要操作前保存快照
+     * ```
+     */
+    saveSnapshot: () => void;
+    /**
+     * 撤销到上一个状态
+     *
+     * 恢复到上一个保存的快照状态。
+     * 如果没有可用的历史记录，操作失败并返回false。
+     *
+     * @returns 是否成功撤销
+     *
+     * @example
+     * ```typescript
+     * if (undo()) {
+     *   console.log('撤销成功');
+     * } else {
+     *   console.log('没有可撤销的历史记录');
+     * }
+     * ```
+     */
+    undo: () => boolean;
+}
+/**
+ * 游戏Store类型 - 组合数据和操作方法
+ *
+ * 这是完整的Store类型，包含游戏状态数据和所有操作方法。
+ * 使用交叉类型将GameState和GameStoreActions合并。
+ *
+ * @template S - 数值属性键的联合类型
+ * @template I - 物品ID的联合类型
+ * @template F - 标记键的联合类型
+ *
+ * @example
+ * ```typescript
+ * const useGameStore: GameStore<'hp' | 'mp', 'sword', 'quest_done'>;
+ * ```
+ */
+type GameStore<S extends string, I extends string, F extends string, X = Record<string, unknown>> = GameState<S, I, F, X> & GameStoreActions<S, I, F, X>;
+/**
+ * 创建游戏引擎Store的工厂函数
+ *
+ * 这是创建游戏状态管理Store的核心函数。它使用Zustand创建一个
+ * 带有持久化功能的状态管理器，自动将游戏状态保存到localStorage。
+ *
+ * 工厂模式的优势：
+ * - 可以创建多个独立的游戏实例
+ * - 每个实例有自己的初始状态和存档名称
+ * - 完全的类型安全和泛型支持
+ *
+ * @template S - 数值属性键的联合类型
+ * @template I - 物品ID的联合类型
+ * @template F - 标记键的联合类型
+ *
+ * @param initialState - 游戏的初始状态
+ * @param persistName - localStorage中的存档键名（默认：'generic-rpg-save'）
+ *
+ * @returns Zustand store hook，可在React组件中使用
+ *
+ * @example
+ * ```typescript
+ * // 定义游戏类型
+ * type Stats = 'hp' | 'mp' | 'gold';
+ * type Items = 'sword' | 'potion';
+ * type Flags = 'quest_completed';
+ *
+ * // 创建初始状态
+ * const initialState: GameState<Stats, Items, Flags> = {
+ *   stats: { hp: 100, mp: 50, gold: 0 },
+ *   inventory: [],
+ *   flags: { quest_completed: false },
+ *   world: { currentLocationId: 'start', day: 1, time: 0 },
+ *   logs: []
+ * };
+ *
+ * // 创建store
+ * export const useGameStore = createGameEngineStore(
+ *   initialState,
+ *   'my-rpg-save'
+ * );
+ *
+ * // 在组件中使用
+ * function GameUI() {
+ *   const hp = useGameStore(state => state.stats.hp);
+ *   const updateStat = useGameStore(state => state.updateStat);
+ *
+ *   return <button onClick={() => updateStat('hp', -10)}>受伤</button>;
+ * }
+ * ```
+ */
+declare const createGameEngineStore: <S extends string, I extends string, F extends string, X = Record<string, unknown>>(initialState: GameState<S, I, F, X>, persistName?: string) => zustand.UseBoundStore<Omit<zustand.StoreApi<GameStore<S, I, F, X>>, "persist"> & {
+    persist: {
+        setOptions: (options: Partial<zustand_middleware.PersistOptions<GameStore<S, I, F, X>, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void> | void;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: GameStore<S, I, F, X>) => void) => () => void;
+        onFinishHydration: (fn: (state: GameStore<S, I, F, X>) => void) => () => void;
+        getOptions: () => Partial<zustand_middleware.PersistOptions<GameStore<S, I, F, X>, unknown>>;
+    };
+}>;
+
+export { type GameStoreActions as G, type GameStore as a, createGameEngineStore as c };