配置 FMOD 播放组件
中文 | English
在仓库根目录运行以下命令,用本机 Unity MCP 回放本页示例。 命令也会重拍两种语言的配图。
python Docs/Manual/manual/tools/tutorials.py run fmod-play-component --capture
点击展开 MCP 操作点击收起 MCP 操作
准备教学样例。${变量} 由配方提供。
{
"variables": {
"asset": "${fixture}/Tutorial_Fmod.prefab"
},
"calls": [
{
"tool": "invoke",
"arguments": {
"path": "static:UnityEditor.AssetDatabase/CreateFolder",
"args": [
"${fixtureParent}",
"${folder}"
]
},
"expect": {
"regex": "\\(String\\) [a-f0-9]{32}"
}
}
]
}
本文说明 FmodPlayComponent:一个挂载到 GameObject 后随启用播放 FMOD 事件的 MonoBehaviour。
1. 组件挂载
在需要发声的 GameObject 上添加 FmodPlayComponent。本例把组件保存在独立的 Tutorial_Fmod.prefab 中,便于复用;实际使用时将该物体放到需要发声的位置。
点击展开 MCP 操作点击收起 MCP 操作
[
{
"tool": "prefab_edit",
"arguments": {
"json": {
"path": "${asset}",
"mode": "create",
"component": "ShanghaiWindy.Core.FmodPlayComponent"
}
},
"expect": {
"equals": {
"ok": true
}
}
}
]
2. 事件选择
eventReference 是私有 [SerializeField] 的 EventReference 结构,不是可拖放的 ScriptableObject。请在检视面板的事件选择器中挑选真实事件,例如 event:/aircraft/engines/engine01/engine01_cockpit。

点击展开 MCP 操作点击收起 MCP 操作
[
{
"tool": "list",
"arguments": {
"path": "static:FMODUnity.EventManager/Events",
"fields": "Path,Guid/Data1,Guid/Data2,Guid/Data3,Guid/Data4",
"search": "event:/aircraft/engines/engine01/engine01_cockpit",
"count": 5
},
"expect": {
"regex": "\\n\\d+\\tevent:/aircraft/engines/engine01/engine01_cockpit\\t(-?\\d+)\\t(-?\\d+)\\t(-?\\d+)\\t(-?\\d+)"
},
"capture": {
"Data1": {
"regex": "\\n\\d+\\tevent:/aircraft/engines/engine01/engine01_cockpit\\t(-?\\d+)\\t(-?\\d+)\\t(-?\\d+)\\t(-?\\d+)",
"group": 1,
"as": "int"
},
"Data2": {
"regex": "\\n\\d+\\tevent:/aircraft/engines/engine01/engine01_cockpit\\t(-?\\d+)\\t(-?\\d+)\\t(-?\\d+)\\t(-?\\d+)",
"group": 2,
"as": "int"
},
"Data3": {
"regex": "\\n\\d+\\tevent:/aircraft/engines/engine01/engine01_cockpit\\t(-?\\d+)\\t(-?\\d+)\\t(-?\\d+)\\t(-?\\d+)",
"group": 3,
"as": "int"
},
"Data4": {
"regex": "\\n\\d+\\tevent:/aircraft/engines/engine01/engine01_cockpit\\t(-?\\d+)\\t(-?\\d+)\\t(-?\\d+)\\t(-?\\d+)",
"group": 4,
"as": "int"
}
}
},
{
"tool": "invoke",
"arguments": {
"path": "static:FMODUnity.EventManager/EventFromPath",
"args": [
"event:/aircraft/engines/engine01/engine01_cockpit"
]
},
"expect": {
"contains": "parameter:/engine01_cockpit/zoom"
}
},
{
"tool": "prefab_edit",
"arguments": {
"json": {
"path": "${asset}",
"mode": "update",
"component": "ShanghaiWindy.Core.FmodPlayComponent",
"values": {
"eventReference": {
"Path": "event:/aircraft/engines/engine01/engine01_cockpit",
"Guid": {
"Data1": "${Data1}",
"Data2": "${Data2}",
"Data3": "${Data3}",
"Data4": "${Data4}"
}
}
}
}
},
"expect": {
"equals": {
"ok": true
}
}
}
]
3. 参数数组
展开 playParams 并添加一个元素,填写 key = zoom、value = 0.5。PlayParm 的两个字段分别为 string 和 float,组件在播放前逐个调用 setParameterByName。本配方会先查询当前事件缓存,确认示例事件存在并定义了 zoom;换用其他事件时,应填写该事件实际拥有的参数名。
每个要修改的参数各加一项。音效包需要加载时,组件会异步等待。实例准备好后,组件会在播放前写入各项参数。
点击展开 MCP 操作点击收起 MCP 操作
[
{
"tool": "prefab_edit",
"arguments": {
"json": {
"path": "${asset}",
"mode": "update",
"component": "ShanghaiWindy.Core.FmodPlayComponent",
"values": {
"playParams": [
{
"key": "zoom",
"value": 0.5
}
]
}
}
},
"expect": {
"equals": {
"ok": true
}
}
},
{
"tool": "inspect",
"arguments": {
"path": "asset:${asset}/GetComponent(ShanghaiWindy.Core.FmodPlayComponent)/playParams/0/key"
},
"expect": {
"contains": "zoom"
}
}
]
4. 生命周期与距离
勾选 isCustomSoundMaxDistance,显示 customSoundMaxDistance 后填入 75;关闭覆盖时该字段隐藏。默认覆盖关闭、距离为 50。这里限制的是启用时是否开始播放,不是持续更新的声音衰减范围。
OnEnable 调用 Play。若此时相机距离超过上限,方法直接返回,靠近后不会自动重播;事件为空、音效池未准备好或音效包加载失败时也不会开始播放。禁用或销毁会取消尚未完成的等待:isStopEventOnDisable = true 时归还已有实例到池;设为 false 时走 ReleaseEvent 路径,不能据此保证声音立即停止。本例保持 true。
旧截图中的独立自动播放开关已移除。当前版本在对象启用时尝试播放。

点击展开 MCP 操作点击收起 MCP 操作
[
{
"tool": "prefab_edit",
"arguments": {
"json": {
"path": "${asset}",
"mode": "update",
"component": "ShanghaiWindy.Core.FmodPlayComponent",
"values": {
"isStopEventOnDisable": true,
"isCustomSoundMaxDistance": true,
"customSoundMaxDistance": 75
}
}
},
"expect": {
"equals": {
"ok": true
}
}
},
{
"tool": "inspect",
"arguments": {
"path": "asset:${asset}/GetComponent(ShanghaiWindy.Core.FmodPlayComponent)/customSoundMaxDistance"
},
"expect": {
"contains": "75"
}
}
]
配方验证了 prefab、事件引用和参数读回;实际音频输出、音效包加载和游戏内距离行为仍需运行时验证。