mcpField
R
roblox-audio

roblox-audio

github.com/tabooharmony创意与媒体1382.1k 次安装2 周前更新
代码仓库

关于 roblox-audio

面向 Roblox 音频开发的技能指南，涵盖旧版 Sound 对象与模块化 AudioPlayer/Wire 系统，供实现播放、空间音效、混音和动态效果时参考。

主要功能

  1. 01旧版与模块化音频系统
  2. 022D 与 3D 音频连接
  3. 03SoundGroup 混音及音效
  4. 04音频预加载与单次音效
  5. 05客户端音效播放注意事项

适用场景

  1. 01为游戏添加背景音乐和音效
  2. 02配置空间音频及衰减范围
  3. 03设置音乐与音效的独立音量
  4. 04避免服务器播放延迟影响反馈

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/tabooharmony/roblox-brain --skill roblox-audio

安装后在 Claude Code 中输入/roblox-audio确认已加载。

附带文件references/full.md

详细介绍

Roblox Audio

何时加载

在实现音频播放、空间／3D 声音、背景音乐、音效、音频混音（SoundGroups）或动态效果时加载。涵盖旧版 Sound 对象和新版模块化 AudioPlayer/Wire 系统。

快速参考

两套系统：旧版（Sound/SoundGroup/SoundEffect）：更简单。新版模块化系统（AudioPlayer/AudioEmitter/Wire/AudioDeviceOutput）：新项目首选；语音聊天必需。

声音放置位置：作为 BasePart 子项 → 体积声源。Attachment/MeshPart → 点声源。SoundService/Workspace → 全局（背景音乐／UI）。

旧版设置：

local s = Instance.new("Sound")
s.SoundId = "rbxassetid://ID"; s.Looped = true; s.Volume = 0.25
s.RollOffMode = Enum.RollOffMode.InverseTapered
s.RollOffMinDistance = 10; s.RollOffMaxDistance = 100
s.Parent = SoundService; s:Play()

SoundGroups（混音器）：将 SoundGroup 嵌套在 Master 下，以便玩家分别调节音乐和音效的音量。bgMusic.SoundGroup = musicGroup。将效果（ReverbSoundEffect、EqualizerSoundEffect、CompressorSoundEffect 等）设为 Sound/SoundGroup 的父项。闪避：在音乐上使用 SideChain = sfxGroup 的 CompressorSoundEffect。

新版模块化系统：2D：AudioPlayer → Wire → AudioDeviceOutput。3D：AudioPlayer → Wire → AudioEmitter（位于 Part 上）。仅限 Studio／插件的 SoundService.DefaultListenerLocation 控制默认监听器；运行时控制需连接显式的 AudioListener。

一次性音效：

local function playSFX(parent, id)
    local s = Instance.new("Sound"); s.SoundId = id
    s.RollOffMode = Enum.RollOffMode.InverseTapered
    s.RollOffMinDistance = 10; s.RollOffMaxDistance = 80
    s.Parent = parent; s:Play()
    s.Ended:Once(function() s:Destroy() end)
end

预加载：ContentProvider:PreloadAsync({sound1, sound2})。客户端音效：FireClient → OnClientEvent 创建不可见 Part 并调用 playSFX。

注意事项：服务端声音存在延迟 → 在客户端播放反馈。默认 RollOffMaxDistance=10000 studs → 请显式设置。音量大于 1 会产生削波。快速重复播放 → 检查 IsPlaying。一次性音效结束后，务必调用 Destroy()。

详细示例、效果表和客户端模式请参阅 references/full.md。

评论

支持 Markdown