LockDoors API

LockDoors API - Hytale 扩展

LockDoors API 是一个强大的 Hytale 扩展，提供了一套完整的可定制方块交互系统。设计需要特定物品激活的门、秘密通道、宝箱和其他交互元素。非常适合冒险地图、地下城、密室逃脱和叙事驱动体验。

---

✨ 功能特性

🔑 高级锁系统

• 可定制的钥匙需求：配置哪个物品可以解锁每扇门
• 自动重锁能力：门在可配置的时间段后自动锁定
• 多状态转换：支持复杂的动画序列（锁定 → 开启 → 打开 → 关闭 → 锁定）
• 智能冷却系统：防止垃圾操作和物品复制漏洞

⏱️ 灵活的时间控制

• 解锁延迟：配置门打开前的等待时间
• 重锁计时器：设置门保持解锁状态的时间
• 动画时长：控制关闭动画的长度
• 独立计时：每个阶段可以有不同的时间设置

📝 丰富的通知系统

• 4 种消息类型：成功、已解锁、重锁和错误消息
• 完全可定制的文本：为每条消息配置主标题和副标题
• 视觉定制：选择主要/次要标题样式和可选图标
• 可调节时长：独立控制每条消息的显示时间

🔄 技术优势

• 旋转保持：门在所有状态变化中保持其朝向
• 防复制：健壮的系统可防止延迟期间的物品利用
• 线程安全调度：使用 Hytale 的调度器实现可靠的定时事件
• 空安全设计：全面的错误处理防止崩溃

🎨 无代码配置

• 从 Hytale 资产编辑器直观地配置所有内容
• 无需编程知识
• 基于模板的工作流程，快速设置
• 完全控制行为和外观

---

🎮 如何创建自定义锁门

1. 创建你的模组包

• 打开 Hytale 资产编辑器
• 创建一个新的资产包或打开现有资产包
• 使用描述性名称命名（例如，“DungeonDoors”或“SecretPassages”）

2. 使用门模板

• 在资产编辑器中找到 Template_Door 资产
• 右键点击并选择 复制 以创建你自己的门变体
• 将其重命名为有意义的名称（例如，“Ancient_Locked_Door”）

3. 自定义视觉模型

导航到 方块类型 > 渲染 并进行配置：

• CustomModel：选择你的 .blockymodel 文件
• CustomModelTexture：为你的模型分配纹理
• HitboxType：选择合适的碰撞（例如，Door、Door_Medium、Door_Large）

💡 提示：为锁定、开启、打开和关闭状态创建单独的模型，以实现流畅的动画。

4. 配置解锁交互

导航到：方块类型 > 交互 > 使用 > 交互 > 0

基本配置

字段	描述	示例	类型
Type	交互类（不要更改）	UnlockInteraction	字符串
RequiredItem	解锁此门的物品 ID	Ingredient_Charcoal	字符串
UnlockDelaySeconds	门打开前的秒数	2	整数
OpenStateName	解锁时的方块状态	OpenDoorIn	字符串

成功消息

字段	描述	示例
SuccessTitleMain	解锁时的主标题	"Ancient Door Unlocked!"
SuccessTitleSecondary	解锁时的副标题	"The passage reveals itself"

错误消息

字段	描述	示例
ErrorTitleMain	错误物品的主标题	"Wrong Key!"
ErrorTitleSecondary	错误物品的副标题	"This key doesn't fit"

自动重锁设置（可选）

字段	描述	示例	默认值
AutoRelock	启用自动重锁	true	false
RelockDelaySeconds	门关闭前的秒数	10	10
CloseStateName	关闭动画的方块状态	CloseDoorIn	"CloseDoorIn"
BlockedStateName	锁定时的方块状态	DoorBlocked	"DoorBlocked"
CloseAnimationSeconds	关闭动画的持续时间	1	1

重锁消息（可选）

字段	描述	示例
RelockTitleMain	重锁时的主标题	"Door Sealing!"
RelockTitleSecondary	重锁时的副标题	"The passage closes"

已解锁消息（可选）

字段	描述	示例
AlreadyUnlockedTitleMain	已打开时的主标题	"Already Open!"
AlreadyUnlockedTitleSecondary	已打开时的副标题	"The door is unlocked"

视觉设置

字段	描述	示例	默认值
IsMajorTitle	显示为突出标题	true	true
TitleIcon	可选图标标识符	"icon_key"	null

5. 重要的方块标志

⚠️ 关键设置 - 导航到 方块类型 > 标志：

• ✅ IsUsable：必须设置为 true（启用玩家交互）
• ✅ 验证所有状态方块 ID 在你的资产中存在

---

📋 配置示例

示例 1：简单的锁门

一扇永久解锁的基本门：

{
  "Type": "UnlockInteraction",
  "RequiredItem": "Item_GoldenKey",
  "UnlockDelaySeconds": 1,
  "OpenStateName": "DoorOpen",
  "SuccessTitleMain": "Door Unlocked!",
  "SuccessTitleSecondary": "The way is open",
  "ErrorTitleMain": "Locked!",
  "ErrorTitleSecondary": "You need a golden key",
  "AutoRelock": false
}

示例 2：定时安全门

一扇 10 秒后自动锁定的门：

{
  "Type": "UnlockInteraction",
  "RequiredItem": "Item_SecurityCard",
  "UnlockDelaySeconds": 2,
  "OpenStateName": "SecurityDoorOpen",
  "AutoRelock": true,
  "RelockDelaySeconds": 10,
  "CloseStateName": "SecurityDoorClosing",
  "BlockedStateName": "SecurityDoorLocked",
  "CloseAnimationSeconds": 2,
  "SuccessTitleMain": "Access Granted",
  "SuccessTitleSecondary": "Security door unlocking...",
  "RelockTitleMain": "Security Alert",
  "RelockTitleSecondary": "Door is locking!",
  "AlreadyUnlockedTitleMain": "Door Active",
  "AlreadyUnlockedTitleSecondary": "Security door is already open"
}

示例 3：谜题秘密通道

一扇带有主题消息的隐藏门：

{
  "Type": "UnlockInteraction",
  "RequiredItem": "Item_AncientMedallion",
  "UnlockDelaySeconds": 3,
  "OpenStateName": "SecretWallOpen",
  "AutoRelock": true,
  "RelockDelaySeconds": 15,
  "CloseStateName": "SecretWallClosing",
  "BlockedStateName": "SecretWallSealed",
  "CloseAnimationSeconds": 3,
  "SuccessTitleMain": "Ancient Magic Awakens",
  "SuccessTitleSecondary": "The wall begins to shift...",
  "RelockTitleMain": "The Magic Fades",
  "RelockTitleSecondary": "The passage seals itself",
  "AlreadyUnlockedTitleMain": "Still Active",
  "AlreadyUnlockedTitleSecondary": "The magic lingers",
  "ErrorTitleMain": "Nothing Happens",
  "ErrorTitleSecondary": "This item holds no power here",
  "IsMajorTitle": true
}

---

🔧 高级用法

状态生命周期

理解完整的门状态循环：

1. DoorBlocked（初始）：门被锁定，玩家无法通过
2. 玩家使用正确物品：物品被消耗
3. UnlockDelaySeconds 等待：解锁动画短暂暂停
4. OpenDoorIn：门打开，玩家可以通过
5. RelockDelaySeconds 等待（如果启用了 AutoRelock）：门保持打开状态
6. CloseDoorIn：播放关闭动画
7. CloseAnimationSeconds 等待：动画完成
8. DoorBlocked：门返回锁定状态

冷却系统

冷却防止：

• 解锁过程中物品的垃圾操作
• 多个玩家同时消耗物品
• 利用时间延迟

当启用 AutoRelock 时，冷却持续时间为：

总冷却时间 = UnlockDelaySeconds + RelockDelaySeconds + CloseAnimationSeconds

在此期间，尝试交互会显示“已解锁”消息。

创建自定义动画

为获得最佳效果：

1. 创建 4 个不同的方块模型：Locked、Opening、Open、Closing
2. 在你的 BlockType 中设置 4 个方块状态
3. 配置状态之间的平滑过渡
4. 将 UnlockDelaySeconds 和 CloseAnimationSeconds 与你的动画长度匹配

---

🐛 故障排除

门对交互无响应

解决方案：

• ✅ 验证在方块类型 > 标志中启用了 IsUsable: true
• ✅ 检查你使用的物品是否与 RequiredItem 中指定的完全一致
• ✅ 确保方块正确配置了交互
• ✅ 使用热栏中的正确物品进行测试

物品被消耗但门未打开

解决方案：

• ✅ 验证 OpenStateName 与现有的方块状态匹配
• ✅ 检查目标方块资产是否在你的包中存在
• ✅ 等待 UnlockDelaySeconds - 延迟是有意为之
• ✅ 检查控制台是否有错误消息

标题消息不显示

解决方案：

• ✅ 验证所有消息字段是否正确填写
• ✅ 检查 IsMajorTitle 设置是否正确
• ✅ 确保消息字符串不包含语法错误
• ✅ 先使用简化的消息进行测试

门打开时失去旋转

解决方案：

• 🎉 系统会自动处理此问题
• 如果旋转丢失，确保所有方块状态具有正确的旋转变体
• 将持续存在的问题作为 Bug 报告

已解锁消息立即显示

解决方案：

• ✅ 当启用 AutoRelock 时，这是预期行为
• 门处于活跃的解锁循环中
• 等待门完成其完整循环
• 如果等待时间过长，减小 RelockDelaySeconds

门不自动重锁

解决方案：

• ✅ 验证设置了 AutoRelock: true
• ✅ 检查 CloseStateName 和 BlockedStateName 是否存在
• ✅ 确保设置了 RelockDelaySeconds 和 CloseAnimationSeconds
• ✅ 验证重锁过程中控制台没有错误