steamsheep-ts-game-engine 3.0.0 → 3.1.0

package/dist/{types-C3Q7UPWy.d.mts → types-D-nDlnv3.d.mts}

@@ -1429,17 +1429,23 @@ interface ActionDef<S extends string, I extends string, F extends string, X = Re
      * 如果是函数，它会在所有效果（包括 afterEffects）执行完成后调用，
      * 因此可以基于最终状态生成准确的反馈文本。
      *
+     * ⚠️ 增强功能：函数可以接收第二个参数（原始状态）
+     *
+     * 这允许你比较执行前后的状态变化，生成更准确的反馈文本，
+     * 而无需通过 afterEffects + extra 的方式传递信息。
+     *
      * 注意事项：
      * 1. 不应在这里修改游戏状态（使用 afterEffects 代替）
-     * 2. 函数接收的是所有效果执行后的最终状态
-     * 3. 返回的文本会作为 'result' 类型的日志添加到游戏日志中
+     * 2. 第一个参数是所有效果执行后的最终状态
+     * 3. 第二个参数是动作执行前的原始状态（可选）
+     * 4. 返回的文本会作为 'result' 类型的日志添加到游戏日志中
      *
      * @example
      * ```typescript
      * // 静态文本
      * resultText: '你完成了探索'
      *
-     * // 动态文本 - 基于最终状态
+     * // 动态文本 - 基于最终状态（单参数，向后兼容）
      * resultText: (state) => {
      *   const sanity = state.stats.sanity;
      *   if (sanity < 20) {
@@ -1451,35 +1457,78 @@ interface ActionDef<S extends string, I extends string, F extends string, X = Re
      *   }
      * }
      *
-     * // 基于标记生成文本
-     * resultText: (state) => {
-     *   if (state.flags.scholar_achievement) {
-     *     return '你的知识达到了新的高度！【成就解锁：博学者】';
-     *   }
-     *   return '你学到了新的知识。';
+     * // 比较前后状态（双参数，推荐）
+     * resultText: (state, original) => {
+     *   const gainedGnosis = state.stats.gnosis > original.stats.gnosis;
+     *   return gainedGnosis
+     *     ? '你在冥想中获得了灵知！'
+     *     : '你平静地冥想了一会儿。';
      * }
      *
-     * // 基于多个状态生成复杂文本
-     * resultText: (state) => {
-     *   const parts: string[] = ['你凝视着星空'];
+     * // 显示具体的变化量
+     * resultText: (state, original) => {
+     *   const hpChange = state.stats.hp - original.stats.hp;
+     *   const goldChange = state.stats.gold - original.gold;
      *
-     *   if (state.world.time === 0) {
-     *     parts.push('午夜的星空格外诡异');
-     *   }
+     *   const parts: string[] = ['战斗结束'];
      *
-     *   if (state.stats.sanity < 30) {
-     *     parts.push('你看到了不该看到的东西');
+     *   if (hpChange < 0) {
+     *     parts.push(`失去了 ${-hpChange} 点生命值`);
      *   }
      *
-     *   if (state.flags.going_mad) {
-     *     parts.push('理智正在崩溃...');
+     *   if (goldChange > 0) {
+     *     parts.push(`获得了 ${goldChange} 金币`);
      *   }
      *
      *   return parts.join('，') + '。';
      * }
+     *
+     * // 检测是否触发了特殊效果
+     * resultText: (state, original) => {
+     *   const leveledUp = state.stats.level > original.stats.level;
+     *   const gotAchievement = state.flags.new_achievement && !original.flags.new_achievement;
+     *
+     *   if (leveledUp && gotAchievement) {
+     *     return '恭喜升级！同时解锁了新成就！';
+     *   } else if (leveledUp) {
+     *     return '恭喜升级！';
+     *   } else if (gotAchievement) {
+     *     return '解锁了新成就！';
+     *   } else {
+     *     return '获得了经验值。';
+     *   }
+     * }
+     *
+     * // 显示物品变化
+     * resultText: (state, original) => {
+     *   const itemsGained = state.inventory.length - original.inventory.length;
+     *
+     *   if (itemsGained > 0) {
+     *     const newItems = state.inventory.slice(-itemsGained);
+     *     return `获得了物品：${newItems.join('、')}`;
+     *   }
+     *
+     *   return '打开了宝箱，但里面是空的。';
+     * }
+     *
+     * // 条件效果的结果反馈
+     * resultText: (state, original) => {
+     *   // 检查是否触发了条件效果
+     *   const triggeredMadness = state.flags.going_mad && !original.flags.going_mad;
+     *   const gotCursedItem = state.inventory.includes('cursed_artifact') &&
+     *                         !original.inventory.includes('cursed_artifact');
+     *
+     *   if (triggeredMadness && gotCursedItem) {
+     *     return '仪式完成了，但你感到理智正在崩溃，手中多了一件诅咒物品...';
+     *   } else if (triggeredMadness) {
+     *     return '仪式完成了，但代价是你的理智...';
+     *   } else {
+     *     return '仪式顺利完成。';
+     *   }
+     * }
      * ```
      */
-    resultText: string | ((state: GameState<S, I, F, X>) => string);
+    resultText: string | ((state: GameState<S, I, F, X>, original?: GameState<S, I, F, X>) => string);
 }
 /**
  * 地点定义接口 - 定义游戏中的一个地点/场景

package/dist/{types-C3Q7UPWy.d.ts → types-D-nDlnv3.d.ts}

@@ -1429,17 +1429,23 @@ interface ActionDef<S extends string, I extends string, F extends string, X = Re
      * 如果是函数，它会在所有效果（包括 afterEffects）执行完成后调用，
      * 因此可以基于最终状态生成准确的反馈文本。
      *
+     * ⚠️ 增强功能：函数可以接收第二个参数（原始状态）
+     *
+     * 这允许你比较执行前后的状态变化，生成更准确的反馈文本，
+     * 而无需通过 afterEffects + extra 的方式传递信息。
+     *
      * 注意事项：
      * 1. 不应在这里修改游戏状态（使用 afterEffects 代替）
-     * 2. 函数接收的是所有效果执行后的最终状态
-     * 3. 返回的文本会作为 'result' 类型的日志添加到游戏日志中
+     * 2. 第一个参数是所有效果执行后的最终状态
+     * 3. 第二个参数是动作执行前的原始状态（可选）
+     * 4. 返回的文本会作为 'result' 类型的日志添加到游戏日志中
      *
      * @example
      * ```typescript
      * // 静态文本
      * resultText: '你完成了探索'
      *
-     * // 动态文本 - 基于最终状态
+     * // 动态文本 - 基于最终状态（单参数，向后兼容）
      * resultText: (state) => {
      *   const sanity = state.stats.sanity;
      *   if (sanity < 20) {
@@ -1451,35 +1457,78 @@ interface ActionDef<S extends string, I extends string, F extends string, X = Re
      *   }
      * }
      *
-     * // 基于标记生成文本
-     * resultText: (state) => {
-     *   if (state.flags.scholar_achievement) {
-     *     return '你的知识达到了新的高度！【成就解锁：博学者】';
-     *   }
-     *   return '你学到了新的知识。';
+     * // 比较前后状态（双参数，推荐）
+     * resultText: (state, original) => {
+     *   const gainedGnosis = state.stats.gnosis > original.stats.gnosis;
+     *   return gainedGnosis
+     *     ? '你在冥想中获得了灵知！'
+     *     : '你平静地冥想了一会儿。';
      * }
      *
-     * // 基于多个状态生成复杂文本
-     * resultText: (state) => {
-     *   const parts: string[] = ['你凝视着星空'];
+     * // 显示具体的变化量
+     * resultText: (state, original) => {
+     *   const hpChange = state.stats.hp - original.stats.hp;
+     *   const goldChange = state.stats.gold - original.gold;
      *
-     *   if (state.world.time === 0) {
-     *     parts.push('午夜的星空格外诡异');
-     *   }
+     *   const parts: string[] = ['战斗结束'];
      *
-     *   if (state.stats.sanity < 30) {
-     *     parts.push('你看到了不该看到的东西');
+     *   if (hpChange < 0) {
+     *     parts.push(`失去了 ${-hpChange} 点生命值`);
      *   }
      *
-     *   if (state.flags.going_mad) {
-     *     parts.push('理智正在崩溃...');
+     *   if (goldChange > 0) {
+     *     parts.push(`获得了 ${goldChange} 金币`);
      *   }
      *
      *   return parts.join('，') + '。';
      * }
+     *
+     * // 检测是否触发了特殊效果
+     * resultText: (state, original) => {
+     *   const leveledUp = state.stats.level > original.stats.level;
+     *   const gotAchievement = state.flags.new_achievement && !original.flags.new_achievement;
+     *
+     *   if (leveledUp && gotAchievement) {
+     *     return '恭喜升级！同时解锁了新成就！';
+     *   } else if (leveledUp) {
+     *     return '恭喜升级！';
+     *   } else if (gotAchievement) {
+     *     return '解锁了新成就！';
+     *   } else {
+     *     return '获得了经验值。';
+     *   }
+     * }
+     *
+     * // 显示物品变化
+     * resultText: (state, original) => {
+     *   const itemsGained = state.inventory.length - original.inventory.length;
+     *
+     *   if (itemsGained > 0) {
+     *     const newItems = state.inventory.slice(-itemsGained);
+     *     return `获得了物品：${newItems.join('、')}`;
+     *   }
+     *
+     *   return '打开了宝箱，但里面是空的。';
+     * }
+     *
+     * // 条件效果的结果反馈
+     * resultText: (state, original) => {
+     *   // 检查是否触发了条件效果
+     *   const triggeredMadness = state.flags.going_mad && !original.flags.going_mad;
+     *   const gotCursedItem = state.inventory.includes('cursed_artifact') &&
+     *                         !original.inventory.includes('cursed_artifact');
+     *
+     *   if (triggeredMadness && gotCursedItem) {
+     *     return '仪式完成了，但你感到理智正在崩溃，手中多了一件诅咒物品...';
+     *   } else if (triggeredMadness) {
+     *     return '仪式完成了，但代价是你的理智...';
+     *   } else {
+     *     return '仪式顺利完成。';
+     *   }
+     * }
      * ```
      */
-    resultText: string | ((state: GameState<S, I, F, X>) => string);
+    resultText: string | ((state: GameState<S, I, F, X>, original?: GameState<S, I, F, X>) => string);
 }
 /**
  * 地点定义接口 - 定义游戏中的一个地点/场景

package/dist/ui/index.d.mts

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