steamsheep-ts-game-engine 1.0.0 → 1.1.0

package/README.md

@@ -189,7 +189,7 @@ interface ExtraData {
 
 ```typescript
 // src/game/config/init.ts
-import type { GameState } from '@/engine/core/types';
+import type { GameState } from 'steamsheep-ts-game-engine/core';
 
 export const initialState: GameState<Stats, Items, Flags, ExtraData> = {
   stats: {
@@ -220,7 +220,7 @@ export const initialState: GameState<Stats, Items, Flags, ExtraData> = {
 
 ```typescript
 // src/game/store.ts
-import { createGameEngineStore } from '@/engine/state/store';
+import { createGameEngineStore } from 'steamsheep-ts-game-engine/state';
 import { initialState } from './config/init';
 
 export const useGameStore = createGameEngineStore(
@@ -235,7 +235,7 @@ export type GameStore = ReturnType<typeof useGameStore>;
 
 ```typescript
 // src/game/content/actions.ts
-import type { ActionDef } from '@/engine/core/types';
+import type { ActionDef } from 'steamsheep-ts-game-engine/core';
 
 export const attackAction: ActionDef<Stats, Items, Flags, ExtraData> = {
   id: 'attack_goblin',
@@ -276,8 +276,8 @@ export const attackAction: ActionDef<Stats, Items, Flags, ExtraData> = {
 ```typescript
 // src/components/GameUI.tsx
 import { useGameStore } from '@/game/store';
-import { FlowSystem } from '@/engine/systems/flow';
-import { QuerySystem } from '@/engine/systems/query';
+import { FlowSystem } from 'steamsheep-ts-game-engine/systems';
+import { QuerySystem } from 'steamsheep-ts-game-engine/systems';
 import { attackAction } from '@/game/content/actions';
 
 function GameUI() {
@@ -399,7 +399,7 @@ export const EngineEvents = {
 #### 监听事件
 
 ```typescript
-import { gameEvents, EngineEvents } from '@/engine/systems/events';
+import { gameEvents, EngineEvents } from 'steamsheep-ts-game-engine/systems';
 
 // 监听属性变化
 const unsubscribe = gameEvents.on(EngineEvents.STAT_CHANGE, (data) => {
@@ -489,7 +489,7 @@ static executeAction(...) {
 #### 使用方法
 
 ```typescript
-import { FlowSystem } from '@/engine/systems/flow';
+import { FlowSystem } from 'steamsheep-ts-game-engine/systems';
 
 const success = FlowSystem.executeAction(store, action);
 
@@ -509,7 +509,7 @@ if (success) {
 #### 常用查询
 
 ```typescript
-import { QuerySystem } from '@/engine/systems/query';
+import { QuerySystem } from 'steamsheep-ts-game-engine/systems';
 
 // 检查是否有物品
 const hasKey = QuerySystem.hasItem(state, 'key');
@@ -619,8 +619,8 @@ store.showModal('警告：此操作不可撤销', 'warn');
 
 ```typescript
 // src/App.tsx
-import { OverlaySystem } from '@/engine/ui/OverlaySystem';
-import { LogStream } from '@/engine/ui/LogStream';
+import { OverlaySystem } from 'steamsheep-ts-game-engine/ui';
+import { LogStream } from 'steamsheep-ts-game-engine/ui';
 
 function App() {
   return (
@@ -1053,7 +1053,7 @@ store.showToast('获得 10 金币', 'success');
 2. **添加 `OverlaySystem` 组件**
    ```typescript
    // src/App.tsx
-   import { OverlaySystem } from '@/engine/ui/OverlaySystem';
+   import { OverlaySystem } from 'steamsheep-ts-game-engine/ui';
    
    function App() {
      return (

package/dist/core/index.d.mts

@@ -1,5 +1,5 @@
-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';
+import { G as GameState } from '../types-BLjkeE3R.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-BLjkeE3R.mjs';
 
 /**
  * 系统消息常量

package/dist/core/index.d.ts

@@ -1,5 +1,5 @@
-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';
+import { G as GameState } from '../types-BLjkeE3R.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-BLjkeE3R.js';
 
 /**
  * 系统消息常量

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-export { A as ActionDef, E as EffectDef, G as GameState, 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';
+export { A as ActionDef, E as EffectDef, G as GameState, b as LocationDef, L as LogEntry, a as NotificationPayload, N as NotificationType, R as RequirementDef, S as StatRequirement, W as WorldState } from './types-BLjkeE3R.mjs';
 export { DEFAULT_CONFIG, DEFAULT_STATS, ENGINE_VERSION, 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 } from './core/index.mjs';
-export { a as GameStore, G as GameStoreActions, c as createGameEngineStore } from './store-BeEHel1o.mjs';
+export { a as GameStore, G as GameStoreActions, c as createGameEngineStore } from './store-xBiJ2MvB.mjs';
 export { HistoryManager } from './state/index.mjs';
 export { EngineEvents, EventBus, FlowSystem, QuerySystem, gameEvents } from './systems/index.mjs';
 export { Layout, LogStream, MainContent, OverlaySystem } from './ui/index.mjs';

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { A as ActionDef, E as EffectDef, G as GameState, 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';
+export { A as ActionDef, E as EffectDef, G as GameState, b as LocationDef, L as LogEntry, a as NotificationPayload, N as NotificationType, R as RequirementDef, S as StatRequirement, W as WorldState } from './types-BLjkeE3R.js';
 export { DEFAULT_CONFIG, DEFAULT_STATS, ENGINE_VERSION, 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 } from './core/index.js';
-export { a as GameStore, G as GameStoreActions, c as createGameEngineStore } from './store-BP5bpjRr.js';
+export { a as GameStore, G as GameStoreActions, c as createGameEngineStore } from './store-D0SE7zJK.js';
 export { HistoryManager } from './state/index.js';
 export { EngineEvents, EventBus, FlowSystem, QuerySystem, gameEvents } from './systems/index.js';
 export { Layout, LogStream, MainContent, OverlaySystem } from './ui/index.js';

package/dist/state/index.d.mts

@@ -1,5 +1,5 @@
-export { a as GameStore, G as GameStoreActions, c as createGameEngineStore } from '../store-BeEHel1o.mjs';
-import { G as GameState } from '../types-CZueoTHl.mjs';
+export { a as GameStore, G as GameStoreActions, c as createGameEngineStore } from '../store-xBiJ2MvB.mjs';
+import { G as GameState } from '../types-BLjkeE3R.mjs';
 import 'zustand/middleware';
 import 'zustand';
 

package/dist/state/index.d.ts

@@ -1,5 +1,5 @@
-export { a as GameStore, G as GameStoreActions, c as createGameEngineStore } from '../store-BP5bpjRr.js';
-import { G as GameState } from '../types-CZueoTHl.js';
+export { a as GameStore, G as GameStoreActions, c as createGameEngineStore } from '../store-D0SE7zJK.js';
+import { G as GameState } from '../types-BLjkeE3R.js';
 import 'zustand/middleware';
 import 'zustand';
 

package/dist/{store-BP5bpjRr.d.ts → store-D0SE7zJK.d.ts}

@@ -1,6 +1,6 @@
 import * as zustand_middleware from 'zustand/middleware';
 import * as zustand from 'zustand';
-import { L as LogEntry, G as GameState } from './types-CZueoTHl.js';
+import { L as LogEntry, G as GameState } from './types-BLjkeE3R.js';
 
 /**
  * 游戏Store操作方法接口 - 定义所有可用的状态操作

package/dist/{store-BeEHel1o.d.mts → store-xBiJ2MvB.d.mts}

@@ -1,6 +1,6 @@
 import * as zustand_middleware from 'zustand/middleware';
 import * as zustand from 'zustand';
-import { L as LogEntry, G as GameState } from './types-CZueoTHl.mjs';
+import { L as LogEntry, G as GameState } from './types-BLjkeE3R.mjs';
 
 /**
  * 游戏Store操作方法接口 - 定义所有可用的状态操作

package/dist/systems/index.d.mts

@@ -1,5 +1,5 @@
-import { a as GameStore } from '../store-BeEHel1o.mjs';
-import { A as ActionDef, G as GameState, R as RequirementDef } from '../types-CZueoTHl.mjs';
+import { a as GameStore } from '../store-xBiJ2MvB.mjs';
+import { A as ActionDef, G as GameState, R as RequirementDef } from '../types-BLjkeE3R.mjs';
 import 'zustand/middleware';
 import 'zustand';
 

package/dist/systems/index.d.ts

@@ -1,5 +1,5 @@
-import { a as GameStore } from '../store-BP5bpjRr.js';
-import { A as ActionDef, G as GameState, R as RequirementDef } from '../types-CZueoTHl.js';
+import { a as GameStore } from '../store-D0SE7zJK.js';
+import { A as ActionDef, G as GameState, R as RequirementDef } from '../types-BLjkeE3R.js';
 import 'zustand/middleware';
 import 'zustand';
 

package/dist/{types-CZueoTHl.d.mts → types-BLjkeE3R.d.mts}

@@ -425,18 +425,44 @@ interface ActionDef<S extends string, I extends string, F extends string, X = Re
  * @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']
+ *   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> {
+interface LocationDef<S extends string, I extends string, F extends string, X = Record<string, unknown>> {
     /** 地点的唯一标识符 */
     id: string;
     /** 地点名称 - 显示在UI上的地点名称 */
@@ -446,7 +472,7 @@ interface LocationDef<S extends string, I extends string, F extends string> {
      * 可以是静态字符串或根据游戏状态动态生成的函数
      * 例如：根据时间显示不同的描述
      */
-    description: string | ((state: GameState<S, I, F>) => string);
+    description: string | ((state: GameState<S, I, F, X>) => string);
     /**
      * 该地点可执行的动作ID列表
      *
@@ -459,6 +485,52 @@ interface LocationDef<S extends string, I extends string, F extends string> {
      * 使用时需要配合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 };

package/dist/{types-CZueoTHl.d.ts → types-BLjkeE3R.d.ts}

@@ -425,18 +425,44 @@ interface ActionDef<S extends string, I extends string, F extends string, X = Re
  * @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']
+ *   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> {
+interface LocationDef<S extends string, I extends string, F extends string, X = Record<string, unknown>> {
     /** 地点的唯一标识符 */
     id: string;
     /** 地点名称 - 显示在UI上的地点名称 */
@@ -446,7 +472,7 @@ interface LocationDef<S extends string, I extends string, F extends string> {
      * 可以是静态字符串或根据游戏状态动态生成的函数
      * 例如：根据时间显示不同的描述
      */
-    description: string | ((state: GameState<S, I, F>) => string);
+    description: string | ((state: GameState<S, I, F, X>) => string);
     /**
      * 该地点可执行的动作ID列表
      *
@@ -459,6 +485,52 @@ interface LocationDef<S extends string, I extends string, F extends string> {
      * 使用时需要配合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 };

package/dist/ui/index.d.mts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { L as LogEntry } from '../types-CZueoTHl.mjs';
+import { L as LogEntry } from '../types-BLjkeE3R.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-CZueoTHl.js';
+import { L as LogEntry } from '../types-BLjkeE3R.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": "1.0.0",
+  "version": "1.1.0",
   "description": "通用游戏引擎框架 - 基于 TypeScript 和 Zustand 构建的文字冒险/RPG 游戏引擎",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",