steamsheep-ts-game-engine 2.0.0 → 3.1.0

package/dist/index.mjs

@@ -323,37 +323,85 @@ var HistoryManager = class {
    * @param maxSnapshots - 最大保存的快照数量，默认使用配置中的值
    */
   constructor(maxSnapshots = DEFAULT_CONFIG.MAX_HISTORY_SNAPSHOTS) {
-    /** 存储的状态快照数组 */
+    /** 存储的状态快照数组（按时间顺序） */
     __publicField(this, "snapshots", []);
-    /** 最大快照数量限制 */
+    /** 命名快照映射表（name -> snapshot） */
+    __publicField(this, "namedSnapshots", /* @__PURE__ */ new Map());
+    /** 最大快照数量限制（不包括命名快照） */
     __publicField(this, "maxSnapshots");
     this.maxSnapshots = maxSnapshots;
   }
   /**
-   * 保存当前状态快照
+   * 保存当前状态快照（匿名快照）
    * 
-   * 通过深拷贝保存状态，防止后续修改影响历史记录
-   * 当快照数量超过最大限制时，自动移除最旧的快照
+   * 通过深拷贝保存状态，防止后续修改影响历史记录。
+   * 当快照数量超过最大限制时，自动移除最旧的快照。
+   * 
+   * 匿名快照用于常规的撤销操作，会受到数量限制。
    * 
    * @param state - 要保存的游戏状态
+   * @param description - 快照描述（可选）
    * 
    * @example
    * ```typescript
    * history.push(gameState);
+   * history.push(gameState, '攻击哥布林前');
    * ```
    */
-  push(state) {
-    const snapshot = JSON.parse(JSON.stringify(state));
+  push(state, description) {
+    const stateCopy = JSON.parse(JSON.stringify(state));
+    const snapshot = {
+      id: `snapshot_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+      timestamp: Date.now(),
+      description,
+      state: stateCopy
+    };
     this.snapshots.push(snapshot);
     if (this.snapshots.length > this.maxSnapshots) {
       this.snapshots.shift();
     }
   }
+  /**
+   * 保存命名快照
+   * 
+   * ⚠️ 新功能：保存可以通过名称访问的快照
+   * 
+   * 命名快照不受数量限制，不会被自动清理。
+   * 适用于重要的游戏节点，如Boss战前、章节开始等。
+   * 
+   * 如果已存在同名快照，会被覆盖。
+   * 
+   * @param state - 要保存的游戏状态
+   * @param name - 快照名称（唯一标识符）
+   * @param description - 快照描述（可选）
+   * 
+   * @example
+   * ```typescript
+   * // 保存Boss战前的状态
+   * history.pushNamed(gameState, 'before_boss_fight', '挑战最终Boss前');
+   * 
+   * // 保存章节开始的状态
+   * history.pushNamed(gameState, 'chapter_2_start', '第二章开始');
+   * ```
+   */
+  pushNamed(state, name, description) {
+    const stateCopy = JSON.parse(JSON.stringify(state));
+    const snapshot = {
+      id: `named_${name}_${Date.now()}`,
+      name,
+      timestamp: Date.now(),
+      description,
+      state: stateCopy
+    };
+    this.namedSnapshots.set(name, snapshot);
+  }
   /**
    * 回退到上一个状态（撤销操作）
    * 
-   * 移除并返回最近的一个快照
-   * 如果没有可用的快照，返回 undefined
+   * 移除并返回最近的一个匿名快照。
+   * 如果没有可用的快照，返回 undefined。
+   * 
+   * 注意：此操作不会影响命名快照。
    * 
    * @returns 上一个状态快照，如果历史为空则返回 undefined
    * 
@@ -367,13 +415,136 @@ var HistoryManager = class {
    * ```
    */
   pop() {
-    return this.snapshots.pop();
+    const snapshot = this.snapshots.pop();
+    return snapshot?.state;
+  }
+  /**
+   * 恢复到命名快照
+   * 
+   * ⚠️ 新功能：通过名称恢复到指定的快照
+   * 
+   * 返回指定名称的快照状态，但不从历史记录中删除它。
+   * 这允许多次恢复到同一个命名快照。
+   * 
+   * @param name - 快照名称
+   * @returns 指定名称的状态快照，如果不存在则返回 undefined
+   * 
+   * @example
+   * ```typescript
+   * // 恢复到Boss战前
+   * const savedState = history.restoreNamed('before_boss_fight');
+   * if (savedState) {
+   *   restoreState(savedState);
+   * } else {
+   *   console.log('快照不存在');
+   * }
+   * ```
+   */
+  restoreNamed(name) {
+    const snapshot = this.namedSnapshots.get(name);
+    return snapshot?.state;
+  }
+  /**
+   * 删除命名快照
+   * 
+   * 从历史记录中删除指定名称的快照。
+   * 
+   * @param name - 要删除的快照名称
+   * @returns 是否成功删除
+   * 
+   * @example
+   * ```typescript
+   * history.deleteNamed('before_boss_fight');
+   * ```
+   */
+  deleteNamed(name) {
+    return this.namedSnapshots.delete(name);
+  }
+  /**
+   * 检查命名快照是否存在
+   * 
+   * @param name - 快照名称
+   * @returns 是否存在指定名称的快照
+   * 
+   * @example
+   * ```typescript
+   * if (history.hasNamed('before_boss_fight')) {
+   *   console.log('可以恢复到Boss战前');
+   * }
+   * ```
+   */
+  hasNamed(name) {
+    return this.namedSnapshots.has(name);
+  }
+  /**
+   * 列出所有快照
+   * 
+   * ⚠️ 新功能：获取所有快照的信息列表
+   * 
+   * 返回所有快照（包括匿名和命名快照）的元数据。
+   * 不包含实际的状态数据，只包含快照信息。
+   * 
+   * @returns 快照信息数组，按时间倒序排列（最新的在前）
+   * 
+   * @example
+   * ```typescript
+   * const snapshots = history.listSnapshots();
+   * snapshots.forEach(snap => {
+   *   console.log(`${snap.name || '匿名'}: ${snap.description || '无描述'}`);
+   *   console.log(`  时间: ${new Date(snap.timestamp).toLocaleString()}`);
+   * });
+   * ```
+   */
+  listSnapshots() {
+    const allSnapshots = [];
+    this.snapshots.forEach((snap) => {
+      allSnapshots.push({
+        id: snap.id,
+        name: snap.name,
+        timestamp: snap.timestamp,
+        description: snap.description
+      });
+    });
+    this.namedSnapshots.forEach((snap) => {
+      allSnapshots.push({
+        id: snap.id,
+        name: snap.name,
+        timestamp: snap.timestamp,
+        description: snap.description
+      });
+    });
+    return allSnapshots.sort((a, b) => b.timestamp - a.timestamp);
+  }
+  /**
+   * 列出所有命名快照
+   * 
+   * 只返回命名快照的信息列表。
+   * 
+   * @returns 命名快照信息数组
+   * 
+   * @example
+   * ```typescript
+   * const namedSnaps = history.listNamedSnapshots();
+   * console.log(`共有 ${namedSnaps.length} 个命名快照`);
+   * ```
+   */
+  listNamedSnapshots() {
+    const result = [];
+    this.namedSnapshots.forEach((snap) => {
+      result.push({
+        id: snap.id,
+        name: snap.name,
+        timestamp: snap.timestamp,
+        description: snap.description
+      });
+    });
+    return result.sort((a, b) => b.timestamp - a.timestamp);
   }
   /**
    * 查看最近的快照但不移除
    * 
-   * 返回最新的快照但不从历史记录中删除它
-   * 用于预览上一个状态而不实际执行撤销操作
+   * 返回最新的匿名快照但不从历史记录中删除它。
+   * 用于预览上一个状态而不实际执行撤销操作。
    * 
    * @returns 最近的状态快照，如果历史为空则返回 undefined
    * 
@@ -386,26 +557,36 @@ var HistoryManager = class {
    * ```
    */
   peek() {
-    return this.snapshots[this.snapshots.length - 1];
+    const snapshot = this.snapshots[this.snapshots.length - 1];
+    return snapshot?.state;
   }
   /**
    * 清空所有历史记录
    * 
-   * 移除所有保存的快照，释放内存
-   * 通常在开始新游戏或重置时使用
+   * 移除所有保存的快照（包括匿名和命名快照），释放内存。
+   * 通常在开始新游戏或重置时使用。
+   * 
+   * @param includeNamed - 是否同时清空命名快照（默认为 false）
    * 
    * @example
    * ```typescript
-   * history.clear(); // 清空所有历史
+   * // 只清空匿名快照
+   * history.clear();
+   * 
+   * // 清空所有快照（包括命名快照）
+   * history.clear(true);
    * ```
    */
-  clear() {
+  clear(includeNamed = false) {
     this.snapshots = [];
+    if (includeNamed) {
+      this.namedSnapshots.clear();
+    }
   }
   /**
-   * 获取当前历史记录数量
+   * 获取当前匿名快照数量
    * 
-   * @returns 当前保存的快照数量
+   * @returns 当前保存的匿名快照数量
    * 
    * @example
    * ```typescript
@@ -418,6 +599,32 @@ var HistoryManager = class {
   get size() {
     return this.snapshots.length;
   }
+  /**
+   * 获取命名快照数量
+   * 
+   * @returns 当前保存的命名快照数量
+   * 
+   * @example
+   * ```typescript
+   * console.log(`命名快照数量: ${history.namedSize}`);
+   * ```
+   */
+  get namedSize() {
+    return this.namedSnapshots.size;
+  }
+  /**
+   * 获取总快照数量
+   * 
+   * @returns 所有快照的总数量（匿名 + 命名）
+   * 
+   * @example
+   * ```typescript
+   * console.log(`总快照数量: ${history.totalSize}`);
+   * ```
+   */
+  get totalSize() {
+    return this.snapshots.length + this.namedSnapshots.size;
+  }
 };
 
 // state/store.ts
@@ -595,19 +802,29 @@ var createGameEngineStore = (initialState, persistName = "generic-rpg-save") =>
         reset: () => set({ ...initialState, logs: [] }),
         // ========== 历史记录操作实现 ==========
         /**
-         * 实现：保存当前状态快照
+         * 实现：保存当前状态快照（匿名快照）
          * 
          * 保存除日志外的所有状态数据到历史管理器。
          * 日志通常不需要回退，因此被排除以节省内存。
          */
-        saveSnapshot: () => {
+        saveSnapshot: (description) => {
+          const currentState = get2();
+          history.push(currentState, description);
+        },
+        /**
+         * 实现：保存命名快照
+         * 
+         * 保存可以通过名称访问的快照。
+         * 命名快照不受数量限制，适用于重要的游戏节点。
+         */
+        saveNamedSnapshot: (name, description) => {
           const currentState = get2();
-          history.push(currentState);
+          history.pushNamed(currentState, name, description);
         },
         /**
          * 实现：撤销到上一个状态
          * 
-         * 从历史管理器中恢复上一个快照。
+         * 从历史管理器中恢复上一个匿名快照。
          * 恢复时保留当前的日志，并添加系统提示。
          * 
          * @returns 是否成功撤销
@@ -627,6 +844,56 @@ var createGameEngineStore = (initialState, persistName = "generic-rpg-save") =>
             return true;
           }
           return false;
+        },
+        /**
+         * 实现：恢复到命名快照
+         * 
+         * 通过名称恢复到指定的快照。
+         * 快照不会被删除，可以多次恢复。
+         * 
+         * @returns 是否成功恢复
+         */
+        restoreSnapshot: (name) => {
+          const saved = history.restoreNamed(name);
+          if (saved) {
+            set({
+              stats: saved.stats,
+              inventory: saved.inventory,
+              flags: saved.flags,
+              world: saved.world,
+              extra: saved.extra
+              // logs 保留当前的，不回退日志
+            });
+            get2().addLog(`\u5DF2\u6062\u590D\u5230\u5FEB\u7167\uFF1A${name}`, "info");
+            return true;
+          }
+          return false;
+        },
+        /**
+         * 实现：删除命名快照
+         * 
+         * 从历史记录中删除指定名称的快照。
+         * 
+         * @returns 是否成功删除
+         */
+        deleteSnapshot: (name) => {
+          return history.deleteNamed(name);
+        },
+        /**
+         * 实现：列出所有快照
+         * 
+         * 返回所有快照的元数据列表。
+         */
+        listSnapshots: () => {
+          return history.listSnapshots();
+        },
+        /**
+         * 实现：检查命名快照是否存在
+         * 
+         * @returns 是否存在指定名称的快照
+         */
+        hasSnapshot: (name) => {
+          return history.hasNamed(name);
         }
       }),
       {
@@ -657,7 +924,9 @@ var createGameEngineStore = (initialState, persistName = "generic-rpg-save") =>
 // systems/query.ts
 var QuerySystem = class {
   /**
-   * 检查是否满足所有需求条件
+   * 检查是否满足所有需求条件（带失败原因）
+   * 
+   * ⚠️ 增强版本：返回详细的检查结果，包括失败原因
    * 
    * 这是核心的条件检查方法，用于验证玩家是否满足执行某个动作的所有前置条件。
    * 内置字段使用 AND 逻辑组合，复杂逻辑使用 custom 函数实现。
@@ -667,59 +936,140 @@ var QuerySystem = class {
    * @template F - 标记键的联合类型
    * 
    * @param state - 当前游戏状态
-   * @param reqs - 需求定义（可选，未定义时返回true）
+   * @param reqs - 需求定义（可选，未定义时返回通过）
    * 
-   * @returns true表示满足所有条件，false表示至少有一个条件不满足
+   * @returns RequirementCheckResult 包含是否通过和失败原因
    * 
    * @example
    * ```typescript
-   * // 简单需求
-   * const simple = QuerySystem.checkRequirements(state, {
+   * // 检查需求并获取失败原因
+   * const result = QuerySystem.checkRequirementsWithReason(state, {
    *   hasItems: ['key'],
    *   stats: { strength: { min: 5 } }
    * });
    * 
-   * // 复杂逻辑使用 custom
-   * const complex = QuerySystem.checkRequirements(state, {
-   *   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;
-   *   }
-   * });
+   * if (!result.passed) {
+   *   console.log(result.reason); // 显示失败原因
+   * }
    * ```
    */
-  static checkRequirements(state, reqs) {
-    if (!reqs) return true;
+  static checkRequirementsWithReason(state, reqs) {
+    if (!reqs) return { passed: true };
     if (reqs.hasFlags && reqs.hasFlags.length > 0) {
-      if (!reqs.hasFlags.every((f) => state.flags[f])) return false;
+      const missingFlags = reqs.hasFlags.filter((f) => !state.flags[f]);
+      if (missingFlags.length > 0) {
+        return {
+          passed: false,
+          reason: `\u9700\u8981\u6EE1\u8DB3\u6761\u4EF6\uFF1A${missingFlags.join("\u3001")}`
+        };
+      }
     }
     if (reqs.noFlags && reqs.noFlags.length > 0) {
-      if (reqs.noFlags.some((f) => state.flags[f])) return false;
+      const conflictFlags = reqs.noFlags.filter((f) => state.flags[f]);
+      if (conflictFlags.length > 0) {
+        return {
+          passed: false,
+          reason: `\u4E0D\u80FD\u6EE1\u8DB3\u6761\u4EF6\uFF1A${conflictFlags.join("\u3001")}`
+        };
+      }
     }
     if (reqs.hasItems && reqs.hasItems.length > 0) {
-      if (!reqs.hasItems.every((i) => state.inventory.includes(i)))
-        return false;
+      const missingItems = reqs.hasItems.filter((i) => !state.inventory.includes(i));
+      if (missingItems.length > 0) {
+        return {
+          passed: false,
+          reason: `\u7F3A\u5C11\u5FC5\u9700\u7269\u54C1\uFF1A${missingItems.join("\u3001")}`
+        };
+      }
     }
     if (reqs.noItems && reqs.noItems.length > 0) {
-      if (reqs.noItems.some((i) => state.inventory.includes(i))) return false;
+      const conflictItems = reqs.noItems.filter((i) => state.inventory.includes(i));
+      if (conflictItems.length > 0) {
+        return {
+          passed: false,
+          reason: `\u4E0D\u80FD\u643A\u5E26\u7269\u54C1\uFF1A${conflictItems.join("\u3001")}`
+        };
+      }
     }
     if (reqs.stats) {
       for (const [key, condition] of Object.entries(reqs.stats)) {
         const currentVal = state.stats[key] || 0;
         const cond = condition;
         if (typeof cond === "number") {
-          if (currentVal < cond) return false;
+          if (currentVal < cond) {
+            return {
+              passed: false,
+              reason: `${key} \u4E0D\u8DB3\uFF08\u9700\u8981 ${cond}\uFF0C\u5F53\u524D ${currentVal}\uFF09`
+            };
+          }
         } else {
-          if (cond.min !== void 0 && currentVal < cond.min) return false;
-          if (cond.max !== void 0 && currentVal > cond.max) return false;
+          if (cond.min !== void 0 && currentVal < cond.min) {
+            return {
+              passed: false,
+              reason: `${key} \u8FC7\u4F4E\uFF08\u9700\u8981\u81F3\u5C11 ${cond.min}\uFF0C\u5F53\u524D ${currentVal}\uFF09`
+            };
+          }
+          if (cond.max !== void 0 && currentVal > cond.max) {
+            return {
+              passed: false,
+              reason: `${key} \u8FC7\u9AD8\uFF08\u9700\u8981\u6700\u591A ${cond.max}\uFF0C\u5F53\u524D ${currentVal}\uFF09`
+            };
+          }
         }
       }
     }
-    if (reqs.custom && !reqs.custom(state)) return false;
-    return true;
+    if (reqs.custom) {
+      const customResult = reqs.custom(state);
+      if (typeof customResult === "object") {
+        if (!customResult.passed) {
+          return customResult;
+        }
+      } else if (!customResult) {
+        return {
+          passed: false,
+          reason: "\u4E0D\u6EE1\u8DB3\u81EA\u5B9A\u4E49\u6761\u4EF6"
+        };
+      }
+    }
+    return { passed: true };
+  }
+  /**
+   * 检查是否满足所有需求条件（简化版本）
+   * 
+   * 这是向后兼容的简化版本，只返回 boolean。
+   * 如果需要失败原因，请使用 checkRequirementsWithReason。
+   * 
+   * @template S - 数值属性键的联合类型
+   * @template I - 物品ID的联合类型
+   * @template F - 标记键的联合类型
+   * 
+   * @param state - 当前游戏状态
+   * @param reqs - 需求定义（可选，未定义时返回true）
+   * 
+   * @returns true表示满足所有条件，false表示至少有一个条件不满足
+   * 
+   * @example
+   * ```typescript
+   * // 简单需求
+   * const simple = QuerySystem.checkRequirements(state, {
+   *   hasItems: ['key'],
+   *   stats: { strength: { min: 5 } }
+   * });
+   * 
+   * // 复杂逻辑使用 custom
+   * const complex = QuerySystem.checkRequirements(state, {
+   *   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;
+   *   }
+   * });
+   * ```
+   */
+  static checkRequirements(state, reqs) {
+    return this.checkRequirementsWithReason(state, reqs).passed;
   }
   /**
    * 检查是否有足够资源支付成本
@@ -816,8 +1166,12 @@ var FlowSystem = class {
    */
   static executeAction(store, action) {
     const state = store;
-    if (!QuerySystem.checkRequirements(state, action.requirements)) {
-      console.warn(`\u6761\u4EF6\u4E0D\u6EE1\u8DB3: ${action.id}`);
+    const reqCheck = QuerySystem.checkRequirementsWithReason(state, action.requirements);
+    if (!reqCheck.passed) {
+      console.warn(`\u6761\u4EF6\u4E0D\u6EE1\u8DB3: ${action.id}`, reqCheck.reason);
+      if (reqCheck.reason) {
+        store.addLog(reqCheck.reason, "warn");
+      }
       return false;
     }
     if (!QuerySystem.canAfford(state, action.costs)) {
@@ -833,21 +1187,88 @@ var FlowSystem = class {
     }
     const { effects } = action;
     if (effects) {
-      if (effects.statsChange) {
-        store.setStats(effects.statsChange);
-      }
-      effects.itemsAdd?.forEach((i) => store.addItem(i));
-      effects.itemsRemove?.forEach((i) => store.removeItem(i));
-      if (effects.flagsSet) {
-        Object.entries(effects.flagsSet).forEach(([f, v]) => {
-          store.setFlag(f, v);
-        });
-      }
-      if (effects.teleport) {
-        store.teleport(effects.teleport);
-      }
-      if (effects.triggerEvent) {
-        gameEvents.emit(EngineEvents.CUSTOM, { id: effects.triggerEvent });
+      const applyEffectDef = (effectDef) => {
+        if (effectDef.statsChange) {
+          const statsToChange = typeof effectDef.statsChange === "function" ? effectDef.statsChange(store) : effectDef.statsChange;
+          store.setStats(statsToChange);
+        }
+        effectDef.itemsAdd?.forEach((i) => store.addItem(i));
+        effectDef.itemsRemove?.forEach((i) => store.removeItem(i));
+        if (effectDef.flagsSet) {
+          const flagsToSet = typeof effectDef.flagsSet === "function" ? effectDef.flagsSet(store) : effectDef.flagsSet;
+          Object.entries(flagsToSet).forEach(([f, v]) => {
+            store.setFlag(f, v);
+          });
+        }
+        if (effectDef.flagsBatch) {
+          const batchOp = typeof effectDef.flagsBatch === "function" ? effectDef.flagsBatch(store) : effectDef.flagsBatch;
+          if (batchOp) {
+            if (batchOp.clear) {
+              const allFlags = Object.keys(store.flags);
+              let flagsToClear = [];
+              if (batchOp.clear instanceof RegExp) {
+                flagsToClear = allFlags.filter((f) => batchOp.clear instanceof RegExp && batchOp.clear.test(f));
+              } else if (typeof batchOp.clear === "string") {
+                flagsToClear = allFlags.filter((f) => f.startsWith(batchOp.clear));
+              } else if (Array.isArray(batchOp.clear)) {
+                flagsToClear = batchOp.clear;
+              }
+              flagsToClear.forEach((f) => {
+                store.setFlag(f, false);
+              });
+            }
+            if (batchOp.set) {
+              Object.entries(batchOp.set).forEach(([f, v]) => {
+                store.setFlag(f, v);
+              });
+            }
+          }
+        }
+        if (effectDef.teleport) {
+          store.teleport(effectDef.teleport);
+        }
+        if (effectDef.timeAdvance !== void 0) {
+          const daysToAdvance = typeof effectDef.timeAdvance === "function" ? effectDef.timeAdvance(store) : effectDef.timeAdvance;
+          if (daysToAdvance > 0) {
+            const previousDay = store.world.day;
+            store.advanceTime(daysToAdvance);
+            if (effectDef.onTimeAdvance) {
+              const actions = {
+                updateStat: store.updateStat,
+                setStats: store.setStats,
+                setExtra: store.setExtra,
+                addItem: store.addItem,
+                removeItem: store.removeItem,
+                setFlag: store.setFlag,
+                addLog: store.addLog,
+                showToast: store.showToast,
+                showModal: store.showModal,
+                advanceTime: store.advanceTime,
+                teleport: store.teleport,
+                reset: store.reset,
+                saveSnapshot: store.saveSnapshot,
+                undo: store.undo
+              };
+              for (let i = 1; i <= daysToAdvance; i++) {
+                const currentDay = previousDay + i;
+                const dayBefore = currentDay - 1;
+                const currentState = store;
+                effectDef.onTimeAdvance(currentDay, dayBefore, currentState, actions);
+              }
+            }
+          }
+        }
+        if (effectDef.triggerEvent) {
+          gameEvents.emit(EngineEvents.CUSTOM, { id: effectDef.triggerEvent });
+        }
+      };
+      applyEffectDef(effects);
+      if (effects.conditionalEffects) {
+        const currentState = store;
+        const conditionalEffect = effects.conditionalEffects(currentState);
+        if (conditionalEffect) {
+          applyEffectDef(conditionalEffect);
+        }
       }
       if (effects.custom) {
         const draft = { ...state.extra };
@@ -858,8 +1279,81 @@ var FlowSystem = class {
           store.setExtra(draft);
         }
       }
+      if (effects.customFull) {
+        const originalState = { ...state };
+        const currentState = store;
+        const draft = {
+          stats: { ...currentState.stats },
+          inventory: [...currentState.inventory],
+          flags: { ...currentState.flags },
+          world: { ...currentState.world },
+          extra: { ...currentState.extra }
+        };
+        effects.customFull(draft, originalState);
+        const statsChanges = {};
+        for (const key in draft.stats) {
+          const oldVal = currentState.stats[key] || 0;
+          const newVal = draft.stats[key];
+          const delta = newVal - oldVal;
+          if (delta !== 0) {
+            statsChanges[key] = delta;
+          }
+        }
+        if (Object.keys(statsChanges).length > 0) {
+          store.setStats(statsChanges);
+        }
+        const currentItems = new Set(currentState.inventory);
+        const newItems = new Set(draft.inventory);
+        currentState.inventory.forEach((item) => {
+          if (!newItems.has(item)) {
+            store.removeItem(item);
+          }
+        });
+        draft.inventory.forEach((item) => {
+          if (!currentItems.has(item)) {
+            store.addItem(item);
+          }
+        });
+        for (const key in draft.flags) {
+          const oldVal = currentState.flags[key];
+          const newVal = draft.flags[key];
+          if (oldVal !== newVal) {
+            store.setFlag(key, newVal);
+          }
+        }
+        if (draft.world.currentLocationId !== currentState.world.currentLocationId) {
+          store.teleport(draft.world.currentLocationId);
+        }
+        if (draft.world.day !== currentState.world.day) {
+          const dayDelta = draft.world.day - currentState.world.day;
+          store.advanceTime(dayDelta);
+        }
+        store.setExtra(draft.extra);
+      }
+    }
+    if (action.afterEffects) {
+      const originalState = { ...state };
+      const currentState = store;
+      const actions = {
+        updateStat: store.updateStat,
+        setStats: store.setStats,
+        setExtra: store.setExtra,
+        addItem: store.addItem,
+        removeItem: store.removeItem,
+        setFlag: store.setFlag,
+        addLog: store.addLog,
+        showToast: store.showToast,
+        showModal: store.showModal,
+        advanceTime: store.advanceTime,
+        teleport: store.teleport,
+        reset: store.reset,
+        saveSnapshot: store.saveSnapshot,
+        undo: store.undo
+      };
+      action.afterEffects(currentState, originalState, actions);
     }
-    const resultText = typeof action.resultText === "function" ? action.resultText(state) : action.resultText;
+    const finalState = store;
+    const resultText = typeof action.resultText === "function" ? action.resultText(finalState, state) : action.resultText;
     store.addLog(resultText, "result");
     gameEvents.emit(EngineEvents.ACTION_EXECUTED, { actionId: action.id });
     return true;