交互对象框架

交互对象框架

一个适用于星露谷物语 1.6 的框架，允许内容包和 C# 模组为任何大型可制造物品或家具附加交互菜单。当玩家与已注册的物体互动时，会打开一个带有你所定义选项的问题对话框。每个选项都可以通过条件和价格进行限制，并能执行诸如给予物品、施加增益、播放声音或运行任何原版触发动作等效果。

此模组本身不执行任何操作。它是其他模组的依赖项。

创建物体本身、其精灵图和数据，需要使用标准工具 Content Patcher 完成。本框架只负责交互层，即点击物体时发生的行为。

需求

• 星露谷物语 1.6 或更高版本
• SMAPI 4.0.0 或更高版本

面向玩家

安装 SMAPI，然后将此模组解压到你的 Mods 文件夹中，同时安装任何依赖它的模组。无需进行任何配置。

面向内容包作者

创建一个内容包，其清单文件（manifest）需指向本框架，并在其旁边放置一个 interactions.json 文件。

manifest.json:

{
  "Name": "你的内容包名称",
  "Author": "你",
  "Version": "1.0.0",
  "Description": "...",
  "UniqueID": "you.yourPack",
  "MinimumApiVersion": "4.0.0",
  "ContentPackFor": { "UniqueID": "tomokisan.interactiveObjectsFramework" }
}

interactions.json 将限定物品 ID 映射到交互定义：

{
  "(BC)you.YourObject": {
    "Question": "你想做什么？",
    "Options": [
      {
        "Id": "buy",
        "Label": "购买一个神秘盒子（500金）",
        "Cost": { "Money": 500 },
        "Cooldown": "day",
        "Effects": [
          { "Type": "GiveItem", "ItemId": "(O)MysteryBox", "Count": 1 },
          { "Type": "Message", "Text": "感谢您的购买。" }
        ]
      }
    ]
  }
}

交互（Interaction）

交互以及每个子菜单都有以下字段：

• Question：显示在菜单顶部的提示文本。可选。
• Options：选项列表。
• Menus：一组命名的子菜单，选项可以通过 GoTo 打开。仅在顶层读取。

选项（Option）

• Id：简短标识符，在其菜单内必须唯一。用于冷却追踪和 GoTo。
• Label：选项显示的文本。
• Condition：游戏状态查询。如果不匹配，则选项被锁定。可选。
• Cost：以金钱和/或物品表示的价格。在选择选项前检查，成功时消耗。可选。
• Cooldown：每个放置的物体可重复选择此选项的频率。可选值为 "always"（默认）、"day"、"season"、"ever"，或天数数字如 "3"。可选。
• OncePerDay：将 Cooldown 设置为 "day" 的简写形式。可选。
• HideWhenLocked：如果为 true，锁定期间选项将被隐藏，而非显示为灰色。可选，默认 false。
• LockedMessage：当选中锁定选项时显示的文本。覆盖自动生成的原因说明。可选。
• GoTo：在任何效果运行后打开一个子菜单。使用 Menus 中的名称，或使用 "root" 返回主菜单。可选。
• Effects：选中选项时要运行的效果列表。

价格（Cost）

"Cost": { "Money": 100, "Items": [ { "ItemId": "(O)72", "Count": 1 } ] }

如果玩家无法支付，选项将被锁定并显示要求。成功后金钱和物品将自动扣除。

效果（Effects）

• GiveItem（ItemId, Count, Quality）：给予玩家物品。
• TakeItem（ItemId, Count）：移除玩家物品。
• GiveMoney（Amount）：增加金钱。
• TakeMoney（Amount）：扣除金钱，最低为零。
• ApplyBuff（Id）：按 ID 应用增益效果。
• RandomItem（Items, Weights, Count, Quality）：从 Items 中随机给予一件物品。Weights 可选，长度必须与 Items 一致。
• PlaySound（Sound）：播放声音提示。
• Message（Text）：显示一条消息。
• RunAction（Action）：运行一条原版触发动作字符串，可访问完整的动作词汇表，如 AddItem、AddMail 或 AddMoney。

每个效果也可带有 Condition（游戏状态查询），如果条件不匹配则跳过该效果。

文本与翻译

任何文本字段，包括 Question、Label、Message 和 LockedMessage，均支持：

• 纯文本。
• 可令牌化字符串，例如 "[LocalizedText Strings\path]".
• 来自你自身内容包的翻译键，写成 "{{i18n:your.key}}" 的形式。框架会从你的内容包的 i18n 文件夹中读取该键，因此你可以像 SMAPI 模组那样发布 default.json、fr.json 等文件。

条件（Conditions）

Condition 字段使用游戏状态查询（GameStateQuery）。完整列表请参阅星露谷物语 Wiki 页面“Modding:Game state queries”。例如，"PLAYER_CURRENT_MONEY Current 100" 在当前玩家拥有至少 100 金时为真。

注意事项

• 冷却时间存储在物体自身的存档数据中，按玩家分别记录。每个放置的物体追踪自己的冷却时间，它能在保存和加载后保留，并可在多人游戏中正常工作。破坏并更换物体将重置其冷却时间，因为游戏会重新创建物品而不带有存储的数据。
• 为已有原版交互的物体（如椅子）注册交互将覆盖原有行为。建议使用没有原版交互的新物体。

面向 C# 模组

将 IInteractiveObjectsApi 接口复制到你的项目中，然后在游戏启动后请求 API：

var api = this.Helper.ModRegistry.GetApi<IInteractiveObjectsApi>("tomokisan.interactiveObjectsFramework");
api.RegisterInteractionFromJson("(BC)you.YourObject", interactionJson);

JSON 字符串使用与 interactions.json 相同的架构，用于单个交互。API 注册不支持翻译键解析，因此请使用纯文本或可令牌化字符串。

示例

此模组附带一个完整示例，即许愿井（Wishing Well），作为单独的可选下载提供。一个内容包（Content Patcher 包）添加大型可制造物品。另一个内容包（为本框架制作）附加交互。它展示了金钱成本、物品成本、按天和按季冷却、子菜单以及翻译功能。

我的模组： Arcade framework：一个依赖框架，可让你将自己的小游戏挂接到街机柜上，带有共享的票证钱包、高分记录和奖品兑换处。提供 C# API，并附带一个包含三款可玩游戏的工作示例。可选支持 Generic Mod Config Menu。本身不执行任何操作。 This week in Pelican Town：打开电视，让本地新闻主播根据你自己的事迹实时生成并回顾你在山谷中的一周。可与其他电视模组兼容。 Interactive objects framework：一个模组框架，允许内容包和 C# 模组为任何大型可制造物品或家具附加交互菜单，支持条件、成本、冷却和效果。需要 Content Patcher 来创建物体。 SWAPI - Stardew Valley Web API：让你的游戏向自定义网络服务器发送事件。 highRollerSlots：为老虎机增加更高下注额的可能性。 geodeCrusherPlus：为晶球破碎机增加破碎任何晶球的能力，包括神秘盒、古物宝藏和金色椰子。 TV Shopping channel：添加一个电视购物频道。 Prize Machine Custom Prizes：让你轻松完全自定义奖品机的奖品列表。 Better Statue Of Blessings：允许你每天从祝福雕像获得一次祝福，而非每天只能获得一次。 Custom Blessings Framework：允许模组开发者轻松地为祝福雕像添加祝福。 Custom Wake Up Time：让你配置每天的醒来时间。 Anti Tool Exhaustion：防止你因意外使用工具而变得筋疲力尽。