steamsheep-ts-game-engine 1.0.0

package/dist/core/index.d.mts

@@ -0,0 +1,328 @@
+import { G as GameState } from '../types-CZueoTHl.mjs';
+export { A as ActionDef, E as EffectDef, b as LocationDef, L as LogEntry, a as NotificationPayload, N as NotificationType, R as RequirementDef, S as StatRequirement, W as WorldState } from '../types-CZueoTHl.mjs';
+
+/**
+ * 系统消息常量
+ *
+ * 使用特殊的标识符（sys: 前缀），让 UI 层知道这需要翻译。
+ * 这些常量用于系统级别的提示消息，应该在 UI 层进行本地化处理。
+ */
+declare const SystemMessages: {
+    /** 资源不足提示 */
+    readonly NOT_ENOUGH_RESOURCES: "sys:not_enough_resources";
+    /** 条件不满足提示 */
+    readonly REQUIREMENT_NOT_MET: "sys:requirement_not_met";
+    /** 操作成功提示 */
+    readonly ACTION_SUCCESS: "sys:action_success";
+    /** 时间回溯成功提示 */
+    readonly UNDO_SUCCESS: "sys:undo_success";
+};
+
+/**
+ * 全局常量定义
+ */
+/**
+ * 引擎版本
+ */
+declare const ENGINE_VERSION = "1.0.0";
+/**
+ * 默认配置
+ */
+declare const DEFAULT_CONFIG: {
+    /** 默认存档键名 */
+    readonly DEFAULT_SAVE_KEY: "game-save";
+    /** 最大日志条数 */
+    readonly MAX_LOG_ENTRIES: 50;
+    /** 最大历史快照数 */
+    readonly MAX_HISTORY_SNAPSHOTS: 20;
+    /** 飘字显示时长（毫秒） */
+    readonly TOAST_DURATION: 3000;
+};
+/**
+ * 日志类型颜色映射
+ */
+declare const LOG_TYPE_COLORS: {
+    readonly info: "#3b82f6";
+    readonly success: "#10b981";
+    readonly warn: "#f59e0b";
+    readonly error: "#ef4444";
+    readonly result: "#6366f1";
+};
+/**
+ * 默认属性值
+ */
+declare const DEFAULT_STATS: {
+    /** 默认生命值 */
+    readonly DEFAULT_HP: 100;
+    /** 默认金币 */
+    readonly DEFAULT_GOLD: 0;
+};
+/**
+ * 游戏时间常量
+ */
+declare const TIME_CONSTANTS: {
+    /** 一天的小时数 */
+    readonly HOURS_PER_DAY: 24;
+    /** 早晨开始时间 */
+    readonly MORNING_START: 6;
+    /** 中午开始时间 */
+    readonly NOON_START: 12;
+    /** 傍晚开始时间 */
+    readonly EVENING_START: 18;
+    /** 夜晚开始时间 */
+    readonly NIGHT_START: 22;
+};
+/**
+ * UI 常量
+ */
+declare const UI_CONSTANTS: {
+    /** 侧边栏宽度 */
+    readonly SIDEBAR_WIDTH: 288;
+    /** 日志栏宽度 */
+    readonly LOG_WIDTH: 320;
+    /** Toast 容器 z-index */
+    readonly TOAST_Z_INDEX: 1000;
+    /** Modal 容器 z-index */
+    readonly MODAL_Z_INDEX: 2000;
+};
+/**
+ * 验证常量
+ */
+declare const VALIDATION: {
+    /** 最小属性值 */
+    readonly MIN_STAT_VALUE: 0;
+    /** 最大属性值 */
+    readonly MAX_STAT_VALUE: 9999;
+    /** 最大背包容量 */
+    readonly MAX_INVENTORY_SIZE: 100;
+    /** 最小动作 ID 长度 */
+    readonly MIN_ACTION_ID_LENGTH: 1;
+    /** 最大动作 ID 长度 */
+    readonly MAX_ACTION_ID_LENGTH: 50;
+};
+
+/**
+ * 工具函数集合
+ */
+
+/**
+ * 生成唯一 ID
+ *
+ * @returns 唯一标识符字符串
+ *
+ * @example
+ * ```typescript
+ * const id = generateId(); // "1234567890-abc123"
+ * ```
+ */
+declare function generateId(): string;
+/**
+ * 深拷贝对象
+ *
+ * 使用 JSON 序列化实现深拷贝，注意会丢失函数、Symbol 等特殊类型
+ *
+ * @param obj - 要拷贝的对象
+ * @returns 深拷贝后的对象
+ *
+ * @example
+ * ```typescript
+ * const copy = deepClone(originalObject);
+ * ```
+ */
+declare function deepClone<T>(obj: T): T;
+/**
+ * 限制数值在指定范围内
+ *
+ * @param value - 要限制的值
+ * @param min - 最小值
+ * @param max - 最大值
+ * @returns 限制后的值
+ *
+ * @example
+ * ```typescript
+ * clamp(150, 0, 100); // 100
+ * clamp(-10, 0, 100); // 0
+ * clamp(50, 0, 100);  // 50
+ * ```
+ */
+declare function clamp(value: number, min: number, max: number): number;
+/**
+ * 格式化数字，添加千位分隔符
+ *
+ * @param num - 要格式化的数字
+ * @returns 格式化后的字符串
+ *
+ * @example
+ * ```typescript
+ * formatNumber(1234567); // "1,234,567"
+ * ```
+ */
+declare function formatNumber(num: number): string;
+/**
+ * 获取时间段描述
+ *
+ * @param hour - 小时数 (0-23)
+ * @returns 时间段描述
+ *
+ * @example
+ * ```typescript
+ * getTimeOfDay(8);  // "早晨"
+ * getTimeOfDay(14); // "下午"
+ * getTimeOfDay(20); // "傍晚"
+ * ```
+ */
+declare function getTimeOfDay(hour: number): string;
+/**
+ * 计算百分比
+ *
+ * @param current - 当前值
+ * @param max - 最大值
+ * @returns 百分比 (0-100)
+ *
+ * @example
+ * ```typescript
+ * getPercentage(75, 100); // 75
+ * getPercentage(0, 100);  // 0
+ * ```
+ */
+declare function getPercentage(current: number, max: number): number;
+/**
+ * 随机整数
+ *
+ * @param min - 最小值（包含）
+ * @param max - 最大值（包含）
+ * @returns 随机整数
+ *
+ * @example
+ * ```typescript
+ * randomInt(1, 6); // 1-6 之间的随机整数（模拟骰子）
+ * ```
+ */
+declare function randomInt(min: number, max: number): number;
+/**
+ * 从数组中随机选择一个元素
+ *
+ * @param array - 数组
+ * @returns 随机选择的元素，如果数组为空则返回 undefined
+ *
+ * @example
+ * ```typescript
+ * randomChoice(['剑', '盾', '药水']); // 随机返回一个
+ * ```
+ */
+declare function randomChoice<T>(array: T[]): T | undefined;
+/**
+ * 打乱数组顺序（Fisher-Yates 算法）
+ *
+ * @param array - 要打乱的数组
+ * @returns 打乱后的新数组
+ *
+ * @example
+ * ```typescript
+ * shuffle([1, 2, 3, 4, 5]); // [3, 1, 5, 2, 4]
+ * ```
+ */
+declare function shuffle<T>(array: T[]): T[];
+/**
+ * 延迟执行
+ *
+ * @param ms - 延迟毫秒数
+ * @returns Promise
+ *
+ * @example
+ * ```typescript
+ * await delay(1000); // 延迟 1 秒
+ * ```
+ */
+declare function delay(ms: number): Promise<void>;
+/**
+ * 检查对象是否为空
+ *
+ * @param obj - 要检查的对象
+ * @returns 是否为空
+ *
+ * @example
+ * ```typescript
+ * isEmpty({}); // true
+ * isEmpty({ a: 1 }); // false
+ * ```
+ */
+declare function isEmpty(obj: object): boolean;
+/**
+ * 安全地获取嵌套属性
+ *
+ * @param obj - 对象
+ * @param path - 属性路径，用点分隔
+ * @param defaultValue - 默认值
+ * @returns 属性值或默认值
+ *
+ * @example
+ * ```typescript
+ * const obj = { a: { b: { c: 123 } } };
+ * get(obj, 'a.b.c', 0); // 123
+ * get(obj, 'a.x.y', 0); // 0
+ * ```
+ */
+declare function get<T>(obj: unknown, path: string, defaultValue?: T): T;
+/**
+ * 防抖函数
+ *
+ * @param fn - 要防抖的函数
+ * @param wait - 等待时间（毫秒）
+ * @returns 防抖后的函数
+ *
+ * @example
+ * ```typescript
+ * const debouncedSave = debounce(() => saveGame(), 1000);
+ * debouncedSave(); // 1秒内多次调用只执行最后一次
+ * ```
+ */
+declare function debounce<T extends (...args: never[]) => unknown>(fn: T, wait: number): (...args: Parameters<T>) => void;
+/**
+ * 节流函数
+ *
+ * @param fn - 要节流的函数
+ * @param wait - 等待时间（毫秒）
+ * @returns 节流后的函数
+ *
+ * @example
+ * ```typescript
+ * const throttledUpdate = throttle(() => updateUI(), 100);
+ * throttledUpdate(); // 100ms 内只执行一次
+ * ```
+ */
+declare function throttle<T extends (...args: never[]) => unknown>(fn: T, wait: number): (...args: Parameters<T>) => void;
+/**
+ * 格式化游戏时间
+ *
+ * @param day - 天数
+ * @param time - 小时数
+ * @returns 格式化的时间字符串
+ *
+ * @example
+ * ```typescript
+ * formatGameTime(5, 14); // "第 5 天 下午 2:00"
+ * ```
+ */
+declare function formatGameTime(day: number, time: number): string;
+/**
+ * 计算两个状态之间的差异
+ *
+ * @param oldState - 旧状态
+ * @param newState - 新状态
+ * @returns 差异对象
+ *
+ * @example
+ * ```typescript
+ * const diff = getStateDiff(oldState, newState);
+ * console.log(diff.stats); // { hp: -10, gold: 5 }
+ * ```
+ */
+declare function getStateDiff<S extends string, I extends string, F extends string, X>(oldState: GameState<S, I, F, X>, newState: GameState<S, I, F, X>): {
+    stats: Partial<Record<S, number>>;
+    itemsAdded: I[];
+    itemsRemoved: I[];
+    flagsChanged: Partial<Record<F, boolean>>;
+};
+
+export { DEFAULT_CONFIG, DEFAULT_STATS, ENGINE_VERSION, GameState, LOG_TYPE_COLORS, SystemMessages, TIME_CONSTANTS, UI_CONSTANTS, VALIDATION, clamp, debounce, deepClone, delay, formatGameTime, formatNumber, generateId, get, getPercentage, getStateDiff, getTimeOfDay, isEmpty, randomChoice, randomInt, shuffle, throttle };

package/dist/core/index.d.ts

@@ -0,0 +1,328 @@
+import { G as GameState } from '../types-CZueoTHl.js';
+export { A as ActionDef, E as EffectDef, b as LocationDef, L as LogEntry, a as NotificationPayload, N as NotificationType, R as RequirementDef, S as StatRequirement, W as WorldState } from '../types-CZueoTHl.js';
+
+/**
+ * 系统消息常量
+ *
+ * 使用特殊的标识符（sys: 前缀），让 UI 层知道这需要翻译。
+ * 这些常量用于系统级别的提示消息，应该在 UI 层进行本地化处理。
+ */
+declare const SystemMessages: {
+    /** 资源不足提示 */
+    readonly NOT_ENOUGH_RESOURCES: "sys:not_enough_resources";
+    /** 条件不满足提示 */
+    readonly REQUIREMENT_NOT_MET: "sys:requirement_not_met";
+    /** 操作成功提示 */
+    readonly ACTION_SUCCESS: "sys:action_success";
+    /** 时间回溯成功提示 */
+    readonly UNDO_SUCCESS: "sys:undo_success";
+};
+
+/**
+ * 全局常量定义
+ */
+/**
+ * 引擎版本
+ */
+declare const ENGINE_VERSION = "1.0.0";
+/**
+ * 默认配置
+ */
+declare const DEFAULT_CONFIG: {
+    /** 默认存档键名 */
+    readonly DEFAULT_SAVE_KEY: "game-save";
+    /** 最大日志条数 */
+    readonly MAX_LOG_ENTRIES: 50;
+    /** 最大历史快照数 */
+    readonly MAX_HISTORY_SNAPSHOTS: 20;
+    /** 飘字显示时长（毫秒） */
+    readonly TOAST_DURATION: 3000;
+};
+/**
+ * 日志类型颜色映射
+ */
+declare const LOG_TYPE_COLORS: {
+    readonly info: "#3b82f6";
+    readonly success: "#10b981";
+    readonly warn: "#f59e0b";
+    readonly error: "#ef4444";
+    readonly result: "#6366f1";
+};
+/**
+ * 默认属性值
+ */
+declare const DEFAULT_STATS: {
+    /** 默认生命值 */
+    readonly DEFAULT_HP: 100;
+    /** 默认金币 */
+    readonly DEFAULT_GOLD: 0;
+};
+/**
+ * 游戏时间常量
+ */
+declare const TIME_CONSTANTS: {
+    /** 一天的小时数 */
+    readonly HOURS_PER_DAY: 24;
+    /** 早晨开始时间 */
+    readonly MORNING_START: 6;
+    /** 中午开始时间 */
+    readonly NOON_START: 12;
+    /** 傍晚开始时间 */
+    readonly EVENING_START: 18;
+    /** 夜晚开始时间 */
+    readonly NIGHT_START: 22;
+};
+/**
+ * UI 常量
+ */
+declare const UI_CONSTANTS: {
+    /** 侧边栏宽度 */
+    readonly SIDEBAR_WIDTH: 288;
+    /** 日志栏宽度 */
+    readonly LOG_WIDTH: 320;
+    /** Toast 容器 z-index */
+    readonly TOAST_Z_INDEX: 1000;
+    /** Modal 容器 z-index */
+    readonly MODAL_Z_INDEX: 2000;
+};
+/**
+ * 验证常量
+ */
+declare const VALIDATION: {
+    /** 最小属性值 */
+    readonly MIN_STAT_VALUE: 0;
+    /** 最大属性值 */
+    readonly MAX_STAT_VALUE: 9999;
+    /** 最大背包容量 */
+    readonly MAX_INVENTORY_SIZE: 100;
+    /** 最小动作 ID 长度 */
+    readonly MIN_ACTION_ID_LENGTH: 1;
+    /** 最大动作 ID 长度 */
+    readonly MAX_ACTION_ID_LENGTH: 50;
+};
+
+/**
+ * 工具函数集合
+ */
+
+/**
+ * 生成唯一 ID
+ *
+ * @returns 唯一标识符字符串
+ *
+ * @example
+ * ```typescript
+ * const id = generateId(); // "1234567890-abc123"
+ * ```
+ */
+declare function generateId(): string;
+/**
+ * 深拷贝对象
+ *
+ * 使用 JSON 序列化实现深拷贝，注意会丢失函数、Symbol 等特殊类型
+ *
+ * @param obj - 要拷贝的对象
+ * @returns 深拷贝后的对象
+ *
+ * @example
+ * ```typescript
+ * const copy = deepClone(originalObject);
+ * ```
+ */
+declare function deepClone<T>(obj: T): T;
+/**
+ * 限制数值在指定范围内
+ *
+ * @param value - 要限制的值
+ * @param min - 最小值
+ * @param max - 最大值
+ * @returns 限制后的值
+ *
+ * @example
+ * ```typescript
+ * clamp(150, 0, 100); // 100
+ * clamp(-10, 0, 100); // 0
+ * clamp(50, 0, 100);  // 50
+ * ```
+ */
+declare function clamp(value: number, min: number, max: number): number;
+/**
+ * 格式化数字，添加千位分隔符
+ *
+ * @param num - 要格式化的数字
+ * @returns 格式化后的字符串
+ *
+ * @example
+ * ```typescript
+ * formatNumber(1234567); // "1,234,567"
+ * ```
+ */
+declare function formatNumber(num: number): string;
+/**
+ * 获取时间段描述
+ *
+ * @param hour - 小时数 (0-23)
+ * @returns 时间段描述
+ *
+ * @example
+ * ```typescript
+ * getTimeOfDay(8);  // "早晨"
+ * getTimeOfDay(14); // "下午"
+ * getTimeOfDay(20); // "傍晚"
+ * ```
+ */
+declare function getTimeOfDay(hour: number): string;
+/**
+ * 计算百分比
+ *
+ * @param current - 当前值
+ * @param max - 最大值
+ * @returns 百分比 (0-100)
+ *
+ * @example
+ * ```typescript
+ * getPercentage(75, 100); // 75
+ * getPercentage(0, 100);  // 0
+ * ```
+ */
+declare function getPercentage(current: number, max: number): number;
+/**
+ * 随机整数
+ *
+ * @param min - 最小值（包含）
+ * @param max - 最大值（包含）
+ * @returns 随机整数
+ *
+ * @example
+ * ```typescript
+ * randomInt(1, 6); // 1-6 之间的随机整数（模拟骰子）
+ * ```
+ */
+declare function randomInt(min: number, max: number): number;
+/**
+ * 从数组中随机选择一个元素
+ *
+ * @param array - 数组
+ * @returns 随机选择的元素，如果数组为空则返回 undefined
+ *
+ * @example
+ * ```typescript
+ * randomChoice(['剑', '盾', '药水']); // 随机返回一个
+ * ```
+ */
+declare function randomChoice<T>(array: T[]): T | undefined;
+/**
+ * 打乱数组顺序（Fisher-Yates 算法）
+ *
+ * @param array - 要打乱的数组
+ * @returns 打乱后的新数组
+ *
+ * @example
+ * ```typescript
+ * shuffle([1, 2, 3, 4, 5]); // [3, 1, 5, 2, 4]
+ * ```
+ */
+declare function shuffle<T>(array: T[]): T[];
+/**
+ * 延迟执行
+ *
+ * @param ms - 延迟毫秒数
+ * @returns Promise
+ *
+ * @example
+ * ```typescript
+ * await delay(1000); // 延迟 1 秒
+ * ```
+ */
+declare function delay(ms: number): Promise<void>;
+/**
+ * 检查对象是否为空
+ *
+ * @param obj - 要检查的对象
+ * @returns 是否为空
+ *
+ * @example
+ * ```typescript
+ * isEmpty({}); // true
+ * isEmpty({ a: 1 }); // false
+ * ```
+ */
+declare function isEmpty(obj: object): boolean;
+/**
+ * 安全地获取嵌套属性
+ *
+ * @param obj - 对象
+ * @param path - 属性路径，用点分隔
+ * @param defaultValue - 默认值
+ * @returns 属性值或默认值
+ *
+ * @example
+ * ```typescript
+ * const obj = { a: { b: { c: 123 } } };
+ * get(obj, 'a.b.c', 0); // 123
+ * get(obj, 'a.x.y', 0); // 0
+ * ```
+ */
+declare function get<T>(obj: unknown, path: string, defaultValue?: T): T;
+/**
+ * 防抖函数
+ *
+ * @param fn - 要防抖的函数
+ * @param wait - 等待时间（毫秒）
+ * @returns 防抖后的函数
+ *
+ * @example
+ * ```typescript
+ * const debouncedSave = debounce(() => saveGame(), 1000);
+ * debouncedSave(); // 1秒内多次调用只执行最后一次
+ * ```
+ */
+declare function debounce<T extends (...args: never[]) => unknown>(fn: T, wait: number): (...args: Parameters<T>) => void;
+/**
+ * 节流函数
+ *
+ * @param fn - 要节流的函数
+ * @param wait - 等待时间（毫秒）
+ * @returns 节流后的函数
+ *
+ * @example
+ * ```typescript
+ * const throttledUpdate = throttle(() => updateUI(), 100);
+ * throttledUpdate(); // 100ms 内只执行一次
+ * ```
+ */
+declare function throttle<T extends (...args: never[]) => unknown>(fn: T, wait: number): (...args: Parameters<T>) => void;
+/**
+ * 格式化游戏时间
+ *
+ * @param day - 天数
+ * @param time - 小时数
+ * @returns 格式化的时间字符串
+ *
+ * @example
+ * ```typescript
+ * formatGameTime(5, 14); // "第 5 天 下午 2:00"
+ * ```
+ */
+declare function formatGameTime(day: number, time: number): string;
+/**
+ * 计算两个状态之间的差异
+ *
+ * @param oldState - 旧状态
+ * @param newState - 新状态
+ * @returns 差异对象
+ *
+ * @example
+ * ```typescript
+ * const diff = getStateDiff(oldState, newState);
+ * console.log(diff.stats); // { hp: -10, gold: 5 }
+ * ```
+ */
+declare function getStateDiff<S extends string, I extends string, F extends string, X>(oldState: GameState<S, I, F, X>, newState: GameState<S, I, F, X>): {
+    stats: Partial<Record<S, number>>;
+    itemsAdded: I[];
+    itemsRemoved: I[];
+    flagsChanged: Partial<Record<F, boolean>>;
+};
+
+export { DEFAULT_CONFIG, DEFAULT_STATS, ENGINE_VERSION, GameState, LOG_TYPE_COLORS, SystemMessages, TIME_CONSTANTS, UI_CONSTANTS, VALIDATION, clamp, debounce, deepClone, delay, formatGameTime, formatNumber, generateId, get, getPercentage, getStateDiff, getTimeOfDay, isEmpty, randomChoice, randomInt, shuffle, throttle };