MSCAudioAPI

描述

MSC Audio API — 为模组开发者提供的库，为 My Summer Car 添加游戏从未有过的功能：完整的音乐和音效播放，并配备智能优先级系统。

游戏没有背景音乐。此模组让其他模组能够随处、以任意方式播放音乐和音效——让它们互不冲突，而是补充氛围：

玩家醒来时听到平静的背景音乐（优先级 0）。他走近车库，那里播放着音响（优先级 1）——背景音乐平滑地减弱，但不会关闭。离开车库后——音乐平滑地恢复。这一切自动发生，模组作者无需编写一行代码。

该库自行决定谁的声音更大，平滑处理淡入淡出，尊重游戏的声音设置，并且不允许模组未经许可压制其他模组的声音。

如果您是玩家——只有当其他模组需要它时才安装此模组（或者您想测试音频模组）。

安装

自动（推荐）： 通过 Mod Manager（Vortex/MO2）安装——压缩包具有标准结构。

手动：

1. 安装 MSCLoader 1.4.2 或更新版本（如果尚未安装）。
2. 从压缩包中将 Mods/ 文件夹复制到游戏根目录：...\steamapps\common\My Summer Car\
3. 最终应得到：
   • Mods/MSCAudioAPI.dll — 库本身（必需）；
   • Mods/References/MSCAudioAPI.dll — 用于编译模组的副本（必需）；
4. 启动游戏——模组列表中将出现 MSC Audio API。 该库支持 .mp3、.ogg、.wav 格式。

主要功能

面向玩家：

• 模组声音尊重游戏音量（MasterAudio 设置项）——游戏静音也会静音模组
• 无冲突：相同优先级的模组同时播放，更高优先级会柔和地覆盖较低优先级

面向模组开发者——每个音效只需几行代码：

// 背景音乐（2D，优先级 0，循环）
AudioStream music = MscAudio.Play("Assets/MyMod/music.mp3", 0, true);


// 车库里的音响（3D，优先级 1，30 米内可闻）
AudioStream radio = MscAudio.PlayAt("Assets/MyMod/radio.mp3", garagePos, 1, 30f, true);


// 跟随对象的声音（汽车、NPC、物品）
AudioStream engine = MscAudio.PlayFollow("Assets/MyMod/engine.wav", carTransform, 2, 15f, true);

• 3 种播放方式 - 2D（全游戏范围）、3D 定点、3D 绑定对象
• 优先级 −128…127 带平滑淡入淡出（速度可调）- 先进的声音覆盖系统
• Ignore 标志 - 声音播放于一切之上且不影响他人（物品、界面音效）
• 通道（AudioChannel）- 模组的私有命名空间：用单个滑块控制模组所有声音的总音量（带平滑动画），仅停止/暂停自己的声音 - 不影响其他模组
• 播放列表 — 顺序或随机（不重复上一首），适用于 2D/3D/移动声源，支持跳过和平滑停止
• 回调 OnFinished / OnFadedOut - 响应曲目结束和淡出完成
• 平滑停止 Stop(seconds) — 无爆音中断
• 格式：WAV（PCM 8/16/24，float32）、MP3（短文件——完整加载，长文件——流式解码：内存中仅有几秒音频，任意长度曲目）和 OGG（引擎解码器，在内存中保持压缩）
• 流精细调节：音量、优先级、循环、播放位置、速度（pitch）、运行时切换 2D↔3D、可闻半径
• 按名称查找 — 在代码任意位置控制声音，无需保存引用
• 诊断 — 将所有声音状态转储到控制台，以及混音器决策的 verbose 日志模式
• 完整的 XML 文档 — IntelliSense 在 Visual Studio 中直接提示每个签名

需求

• My Summer Car（已在 Steam 最新版本上测试）
• MSCLoader 1.4.2+
• 无需其他：用于 MP3 解码的 NAudio 已随游戏提供（副本包含在 Mods/References/ 中以防缺失）

兼容性：该库不替换游戏文件，不使用 Harmony，运行于 Unity 标准音频引擎之上。对新旧存档同样有效。

文档

面向模组开发者：

• API.md — 完整文档及示例（在压缩包中和本页 Articles 中）
• MSCAudioAPI.xml — 用于 IntelliSense 的 XML 文档：在您的 .csproj 中添加对 Mods/References/MSCAudioAPI.dll 的引用（带 <Private>False</Private>）——环境中将提示全部 40+ 个方法及其描述

您的模组快速入门：

using MSCAudioAPI;


// 模组加载时：
AudioChannel ch = MscAudio.GetChannel("ВашModID");  // 模组的私有通道
ch.Play("Assets/ВашMod/music.mp3", 0, true);


// 之后任意位置：
ch.SetVolume(0.5f, 2f);   // 模组所有声音的平滑音量
ch.StopAll();             // 仅停止自己的声音