命令交互

命令交互

在任何交互链中运行命令：武器触发、消耗品、按钮、方块。

命令交互（Command Interactions）增加了一种自定义交互类型，即 RunCommand，你可以在本地 Hytale 交互链接受步骤的任何位置内联编写它。武器挥击在幸运一击时触发命令，消耗品在食用时授予额外物品，自定义方块在按下时运行受权限控制的传送：只要它是用 Hytale 自身物品和能力所使用的相同交互链构建的，你就可以在其中加入命令。零依赖，一个 jar 包。

v1.0.0。首次发布。RunCommand 交互类型：服务器或玩家权限执行、每玩家冷却时间、几率触发、权限门控以及完整的占位符替换（{player}、{target}、位置、世界、手持物品）。

源码与完整文档： github.com/arfemia/hytale-command-interactions - 示例包（即插即用）： InteractionCommandsExamples.zip


---

---

功能

• 运行命令的武器触发。 在任何武器的挥击/命中链（原生或你自己的）中添加 RunCommand 步骤，通过 Chance 和 Cooldown 进行控制，使一次攻击可以触发消息、奖励或任何命令能做的其他事情。
• 运行命令的消耗品。 将 RunCommand 步骤链接到食物或药水的食用效果中，与 ApplyEffect 等原生步骤一起，使食用时也可以授予物品、宣布奖励或触发服务器端的其他操作。
• 运行命令的按钮和方块。 编写自定义可用物品或方块引用的独立 RootInteraction，将命令置于 Permission 节点之后，并以玩家的身份运行，以便其自身权限决定结果。
• 服务器或玩家权限，由你选择。 RunAs: "Server" 以完整控制台权限运行（默认）；RunAs: "Player" 以交互玩家本人的身份运行，使游戏自身的权限检查叠加生效。
• 内置占位符。 {player}、{uuid}、{x}/{y}/{z}、{world}、{target}、{targetUuid}、{item}，在触发时替换。带有无法解析占位符（如没有目标时的 {target}）的命令会被单独跳过，绝不会破坏列表的其余部分。
• 绝不破坏链。 冷却中、几率未命中或权限不足是静默跳过，而非失败：该步骤不执行任何操作，其周围的一切（武器挥击、物品消耗）完全正常进行。
• 零依赖。 无需配套模组、库 jar 包或内容包。它不附带任何资源或语言文件；它是一种纯粹的引擎添加，你可以根据它在你自己的包中编写内容。

安装

1. 将 InteractionCommands-<version>.jar 放入服务器（服务端）的 Mods/ 文件夹。
2. 需要 Update 5 范围内的 Hytale 服务器（>=0.5.0-pre.0 <0.6.0）。
3. 无其他依赖。重启服务器即可完成；RunCommand 现在可以在你自己的资源包（其 manifest.json 中需要 "IncludesAssetPack": true，就像编写任何原生内容的包一样）中使用。

工作示例

所有三个示例都位于你自己的资源包中；InteractionCommands 本身不提供任何内容。

尝试示例包

想在不先编写 JSON 的情况下看到 RunCommand 触发吗？下载 InteractionCommandsExamples.zip（源码在仓库的 examples/ 文件夹中），这是下面三个工作示例的参考实现。

1. 将模组 jar 包放入 Mods/，然后将 InteractionCommandsExamples.zip 放在其旁边。重启服务器。
2. 执行 /give Example_Command_Blade --quantity=1、/give Example_Command_Potion --quantity=1、/give Example_Command_Meal --quantity=1。
3. 挥动剑刃（每次命中 25% 几率，5 秒冷却时间）可获得免费的熟野肉。喝下药水可在其原生体力增益之外获得四个火把。吃掉餐食可获得免费的命令药水，直接进入药水示例。

文件放置位置

Hytale 资源的 id 就是其文件路径键，但该键仅为 文件名（PascalCase，无扩展名）；文件所在目录只是一种整洁性约定，而非其标识的一部分（Hytale 的 AssetStore 从 path.getFileName() 派生键，忽略路径的其余部分）。文件命名决定了它是新资源还是对现有资源的覆盖；只有文件名必须匹配。物品位于 Server/Item/Items/**（覆盖原生物品只需该物品本身的确切文件名，在 Items/** 下的任何位置均可；镜像原版的子目录是一种惯例，而非要求）；RootInteraction 位于 Server/Item/RootInteractions/**；显示文本键从你自己包的 Server/Languages/<bcp47>/<filename>.lang 文件中解析（Hytale 的 I18nModule 将语言文件的名称作为键前缀，例如 mypack.lang 中的裸键 items.MyItem.name 解析为 mypack.items.MyItem.name；未编写的键只显示原始键）。

一个授予额外物品的消耗品

文件：Server/Item/Items/MyPack_LuckyMeal.json。

{
  "TranslationProperties": {
    "Name": "mypack.items.MyPack_LuckyMeal.name",
    "Description": "mypack.items.MyPack_LuckyMeal.description"
  },
  "Parent": "Template_Food",
  "InteractionVars": {
    "Effect": {
      "Interactions": [
        { "Type": "ApplyEffect", "EffectId": "Food_Instant_Heal_T1" },
        {
          "Type": "RunCommand",
          "Commands": ["give {player} Food_Wildmeat_Cooked --quantity=2"],
          "RunAs": "Server"
        }
      ]
    }
  }
}

两个 TranslationProperties 键需要在 Server/Languages/en-US/mypack.lang 中有对应的行（items.MyPack_LuckyMeal.name = Lucky Meal，外加 .description 行），否则物品会显示原始键作为其名称。（注意：Hytale 的 /give 只识别命名的 --quantity=N 形式；位置参数数量只会给予一件物品。）

通过包覆盖在原生武器上添加武器触发

原生覆盖以原版物品本身的文件名打包文件，并在顶层使用 "Parent": "super"（引擎自身的“继承下面加载此键的任何内容”的值），从而继承所有内容，只有你编写的字段会被替换。

文件：Server/Item/Items/Weapon/Longsword/Weapon_Longsword_Crude.json（重要的是原版物品的确切文件名，而非目录；任何其他文件名会创建独立的新物品，而不影响原生武器）。

重述调优后的变量，不要只是添加。 InteractionVars 的键会被你的覆盖整体替换，绝不会与原版物品对该键的调优条目进行深度合并。Crude 自身的 Longsword_Swing_Left_Damage 变量已在未调优的基础交互（Physical: 8、Type: "Absolute"、RandomPercentageModifier: 0.15，与基础的 Physical: 5 相比）之上调优了 DamageCalculator/DamageEffects，因此仅编写裸 {"Parent": "Longsword_Swing_Left_Damage"} 加上新步骤的覆盖会静默地将剑的伤害还原为未调优的 Physical 5。请逐字重述 Crude 自身的调优字段，与示例包中的做法完全一致（examples/InteractionCommandsExamples/Server/Item/Items/Example_Command_Blade.json）：

{
  "Parent": "super",
  "InteractionVars": {
    "Longsword_Swing_Left_Damage": {
      "Interactions": [
        {
          "Parent": "Longsword_Swing_Left_Damage",
          "DamageCalculator": {
            "Type": "Absolute",
            "BaseDamage": { "Physical": 8 },
            "RandomPercentageModifier": 0.15
          },
          "DamageEffects": {
            "WorldSoundEventId": "SFX_Longsword_Special_Impact"
          }
        },
        {
          "Type": "RunCommand",
          "Commands": ["say {target} was struck by a cursed blade!"],
          "RunAs": "Server",
          "Chance": 0.2,
          "Cooldown": 8
        }
      ]
    }
  }
}

每次命中 20% 几率，每玩家 8 秒冷却时间，基于 Crude 自身的调优伤害（Physical 8，如上重述）。针对怪物（无玩家目标）时，{target} 无法解析，因此该命令被静默跳过；玩家目标会收到消息。（想要一个全新物品而不是覆盖原生物品？使用不同的文件名，并将 "Parent" 设为 "Weapon_Longsword_Crude" 而不是 "super"。）

自定义方块的权限控制命令

文件：Server/Item/RootInteractions/MyPack_Arena_Warp.json（如下）加上一个引用它的可放置方块，例如 Server/Item/Items/MyPack_Arena_Beacon.json，带有 BlockType.Flags.IsUsable: true 和 BlockType.Interactions.Use: "MyPack_Arena_Warp"（未被引用的 RootInteraction 永远不会触发）。自定义物品自身的顶层 "Interactions": {"Use": ...} 可以被解码，但没有原版先例，也没有确认的客户端分发路径；每个原生 Use 都挂在方块的 BlockType.Interactions.Use 上，因此请以 MMOSkillBountyPack 内容包中经游戏验证的 MMO_Bounty_Board.json 方块为模型（一个使用原版模型/纹理的墙面海报形方块，Flags.IsUsable: true，其 Use 指向 RootInteraction）。

{
  "Interactions": [
    {
      "Type": "RunCommand",
      "Commands": ["warp arena"],
      "RunAs": "Player",
      "Permission": "mypack.arena.enter"
    }
  ]
}

放置信标并按下 F 键会以玩家本人的身份运行 /warp arena，仅当玩家持有 mypack.arena.enter 权限时；否则是静默跳过。未设置的权限节点默认为拒绝；服务器 OP/管理员状态本身不满足此门控，必须显式授予该节点。

故障排除

你的 RunCommand 步骤触发时没有任何反应？每次门控未命中都是有意的静默跳过（无聊天消息、无错误），按此顺序检查：(1) 触发实体上没有玩家，(2) 玩家未持有 Permission（未设置的节点默认为拒绝；服务器 OP/管理员状态本身不满足），(3) Chance 掷骰未命中，(4) 每个命令都有未解析的占位符（最常见的是无目标实体时的 {target}，或无位置时的 {x}/{y}/{z}），(5) 该玩家在该步骤上的 Cooldown 仍在生效，(6) 列表中的更早命令抛出了真正的错误，这会中止本次触发列表的其余部分（记录为 warn；仅仅是未知命令不会中止）。Commands 中的命令总是严格按你编写的顺序分发，一个在前一个完成后才启动。将服务器日志级别提高到 FINE 可看到未解析占位符的跳过记录。请注意，RunAs: "Server"（默认）将所有命令输出和错误发送到服务器控制台，绝不发给玩家；如果需要玩家可见的反馈，请使用 RunAs: "Player"。完整详情：模组仓库中 README.md 的故障排除部分。

完整的逐字段模式参考、门控语义和占位符表：README.md（位于模组仓库中）。

版本

版本	说明
1.0.0	首次发布。RunCommand 交互类型：Commands/RunAs/Cooldown/Chance/Permission，完整的占位符替换，静默跳过门控语义，未解析占位符的逐命令跳过。零依赖。

---

InteractionCommands 与 Hypixel Studios 或 Hytale 无关。根据 MIT 许可授权；参见 LICENSE。