附件系统 API

用于将零件附加到对象上的框架 我的夏日汽车 和 我的冬季汽车.

汽车、拖拉机、拖车、家具、自定义改装，零件装在哪里由你决定。API 负责处理安装触发、螺栓、扳手工具、零件依赖关系、重量转移，以及在碰撞中会断裂的可选连接件。

现在还包括选择加入支持 原厂MWC轮毂和火花塞.


面向玩家 - 安装说明

如果另一个模组引导你来到这里，你只需要做这些：

• 下载并解压 API。
• 放置 附件系统.dll 在你 模组/参考 文件夹。
• 如果还没有 References 文件夹，请创建它。
  

模组/
└── 参考文献/
    └── AttachmentSystem.dll

这是其他模组的前置依赖。 仅安装它并不会向游戏中添加任何独立部件。

v0.1.3 更新内容

• 原生MWC轮毂与火花塞插槽 - 可选择安装的组件，用于将原厂车轮和火花塞直接安装到自定义车辆和发动机上。
• 螺栓遮蔽 - 隐藏或遮挡其他部件下的螺栓（例如油底壳遮盖曲轴螺栓）。
• 质量传递 - 非连接部件现在可以在安装时直接将重量添加到车身上。
• 菜单免疫 - 游戏暂停或控制台打开时，弩箭和扳机不再交互或滚动。
• 性能 - 帧缓存的射线检测零内存分配，避免大量活跃螺栓时掉帧。
  

致模组制作者——功能说明

• 使用字符串 ID 将部件附加到挂载点。
• 添加螺栓，可配置扳手尺寸、紧固程度和自定义拧动动画。
• 可选支持原版MWC车轮和火花塞。
• 安装前需要先满足前置零件要求。
• 当另一个部件挡住时，阻止安装/拆卸。
• 隐藏或遮挡被其他已安装部件覆盖的螺栓。
• 将部件质量转移到父级刚体上。
• 在碰撞中会脱落的可选固定关节。
• 完整的 UnityEvents 事件钩子与 C# 回调。
• 用于快速设置触发器ID的Unity编辑器工具。
  

1. 项目设置

Unity - 资源/插件
添加 附件系统.dll 以及你的游戏引用（PlayMaker.dll, MSCLoader.dll等）。

Unity - 资源/编辑器
将这些脚本放入Editor文件夹：

• 附件部件编辑器.cs - 将拖放触发框添加到检查器中。
• SnapTriggerIdAutomator.cs - 添加“工具 > 附件系统”菜单。
  

Visual Studio / 集成开发环境
添加引用至 附件系统.dll，然后添加：

使用AttachmentSystem。

2. 核心组件

附件部件
装在你想要附着的位置。

螺栓
用于固定该部件的每个螺栓。

捕捉触发编号
放置在标记挂载点的触发器碰撞体上。

3. 创建挂载点

• 在您的车辆/物体上创建一个游戏对象，作为部件吸附的位置。
• 添加碰撞体并检查 是触发器.
• 添加 瞬发触发器ID.
• 给它一个唯一的ID，比如 我的模组_交流发电机_挂载.
• 将完全相同的 ID 字符串添加到你的部件 触发ID 数组。
  

ID 区分大小写，且必须完全匹配。 始终为你的模组使用唯一前缀，以免与其他模组冲突。

要同时设置多个触发器，请在Unity中选中它们并点击：
工具 > 附件系统 > 自动为选中项添加 SnapTriggerId
（它将使用每个GameObject的名称来命名这些ID）。

您也可以将触发器游戏对象直接拖入 将触发器拖到此处以自动填充ID 附件部件检查器中的方框。

4. 组装零件与螺栓

• 添加 附件部件 到你的部分。
• 将你的触发 ID 添加到 触发ID.
• 添加 螺栓 为每个螺栓对象添加组件。
• 设置每个弩箭的 扳手尺寸 和 最大紧度.
• 将螺栓分配到零件的 螺栓 数组（或留空以自动检测子螺栓）。
  

示例层级：

载具
└── 坐骑
    └── 我的模组_自定义部件_坐骑
        ├── 盒型碰撞体（是否触发器 = 真）
        └── SnapTriggerId（id = "MyMod_CustomPart_Mount"）

自定义部件
├── 附件部件
│ triggerIds = ["MyMod_CustomPart_Mount"]
│ bolts = [Bolt_1, Bolt_2]
├── 螺栓_1
│ 螺栓（尺寸 = 1.3，最大拧紧度 = 8）
└── 螺栓_2
    螺栓（尺寸 = 1.3，最大紧固度 = 8）

扳手尺寸使用游戏单位：

0.5 = 5 毫米 1.0 = 10 毫米
0.6 = 6 毫米 1.1 = 11 毫米
0.7 = 7 毫米 1.2 = 12 毫米
0.8 = 8 毫米 1.3 = 13 毫米
                  1.4 = 14 毫米
                  1.5 = 15 毫米
0.55 = 火花塞套筒
0.65 = 螺丝刀
1.55 = 轮胎扳手

螺栓特性：

• 可使用棘轮 - 如果螺栓位置狭窄，棘轮扳手无法放入，请将此设为 false。
• 自定义高亮材质 - 使用你自己的悬停发光材质，而不是默认材质。
• 位置步进 / 旋转步进 - 调整每滚动一步时枪机模型转动的距离和幅度。
  

5. 高级设置：蒙版与质量传递

螺栓遮蔽（覆盖螺栓）
如果安装此部件会遮盖另一个部件上的螺栓（例如油底壳遮盖曲轴螺栓）：

• 将覆盖的螺栓添加到 隐藏螺栓.
• 设置 停用遮罩游戏对象 为 true 则完全隐藏它们，为 false 则仅禁用其碰撞体，同时保持模型可见。
  

传质
如果你没有使用关节（useJoint = false），启用 转移质量至父级.
安装该部件后，其刚体质量会直接加到父级载具上。移除时，该质量会被扣除，部件恢复其原始物理属性。

6. 可选断裂关节

启用 使用关节 如果你希望在碰撞中部件会实际断裂脱落。

• 自动计算破坏力 - 接头强度与螺栓的紧固程度成正比。
• 最大断裂力 - 所有螺栓完全拧紧时折断所需的冲击力。
• 破坏力 - 完全松弛时的基线冲击力。
• 坚不可摧紧度 - 完全不可破坏时的紧密值。设为 -1 如果它在严重碰撞中应该始终可破坏的话。
  

7. 原厂MWC轮毂与火花塞

想让你的自定义车辆或拖车使用原版MWC部件吗？API包含专用的插槽组件，可为你处理所有原版FSM、螺栓同步和磨损网格。

香草车轮（车轮附件槽）
允许用4个螺栓安装原厂MWC车轮，并检查轮辋/轮胎状态和千斤顶支撑情况。

WheelAttachmentSlot slot = mount.gameObject.AddComponent<WheelAttachmentSlot>();
slot.trigger = mount.GetComponent<Collider>();
插槽.枢轴 = 挂载点；
slot.wheel = nativeWheelComponent; // 用于检查车轮是否离开地面
slot.Installed += wheel => { /* 已安装车轮 */ };
slot.Removed += wheel => { /* 车轮已移除 */ };
slot.ValidateConfiguration();

// 加载你的车辆存档时：
slot.TryRestore(wheelObject, savedBoltValues); // int[4] 数组

原厂火花塞（火花塞附件槽）
可使用0.55扳手 socket 安装原厂 MWC 火花塞

SparkPlugAttachmentSlot slot = mount.gameObject.AddComponent<SparkPlugAttachmentSlot>();
slot.trigger = mount.GetComponent<Collider>();
slot.pivot = mount;
slot.canAccess = () => !wiresAttached; // 如果点火线已连接，则阻止扳手操作/移除
slot.Installed += plug => { /* 已安装Plug */ };
slot.Removed += plug => { /* 插头已移除 */ };
slot.ValidateConfiguration();

// 当加载你的载具存档时：
槽位.尝试恢复(插头对象, 保存的紧密度);

8. 自定义音效

你可以分配自定义 音频片段 直接在检视面板中或通过脚本访问资源：

• 自定义组装片段 / 自定义拆卸片段 开启 配件.
• 自定义螺丝夹 开启 螺栓.
• 启用 禁用声音 如果你想静音默认音效并自行处理音频。
  

9. 保存与加载

你的模组需要自行负责保存其数据。 该 API 会公开所有状态，以便你可以将它们写入模组的存档文件。

在……期间 保存:

• 附加到 - 槽位索引（-1 表示分离）。
• 每支弩箭的 紧绷感.
• 如果部件已分离，则显示其世界位置和旋转。
  

在……期间 加载时:

• 生成或定位你的部件和安装点。
• 如果attachedTo >= 0，则调用 强制附加(index).
• 恢复每个螺栓的 紧度.
• 如果已分离，则恢复其世界位置和旋转。
  

强制附着 瞬间将部件卡入到位，不播放组装音效，也不触发重复的附加事件。

10. 事件与回调

Unity事件（检视面板）

• 附加时事件
• 分离事件
• 完全拧紧时触发
• 完全松开事件
• 休息事件
  

C# 回调

myPart.onAttach += index => { /* 挂载逻辑 */ };
myPart.onDetach += index => { /* 分离逻辑 */ };
myPart.onBreak += force => { /* 关节断裂 */ };

// 返回 false 以阻止安装或卸载：
myPart.canAttach = () => isEngineCool;
我的部件.可分离 = () => 电缆已断开;

// 有条件地显示/隐藏螺栓（例如在检查盖下方）：
myPart.canShowBolts = () => isCoverOpen;

// 自定义移除命中碰撞体与距离：
myPart.interactionCollider = myHandleCollider;
myPart.interactionDistance = 1.5f;

故障排除

这个零件无法卡入到位
检查该碰撞体是否具有 是触发器 启用后，触发器 ID 字符串逐字符匹配，且所需部件均已附加。

未找到 SnapTrigger
请确保场景中的挂载游戏对象处于激活状态，并且其 捕捉触发编号 组件在部件查找它之前已经运行了Awake()。

螺栓不可见
当部件被拆下时，螺栓会自动隐藏。一旦部件卡入安装座，它们就会重新显示。

螺栓无法用棘轮转动
检查是否 可使用棘轮 扳手已启用，并确认棘轮方向开关（是的，因为人们不检查这个）

连接处太容易断裂
检查你的 破坏力, 最大断裂力，以及零件质量。重型零件需要更高的断裂力值才能在颠簸中保持连接。

编辑器脚本导致构建错误
保留 附件部件编辑器.cs 和 SnapTriggerIdAutomator.cs 在 编辑器 Unity 中的文件夹。它们不得被编译到你的运行时游戏 DLL 中。