• 游戏开发

导读

本文深入解析 OpenSC2K（基于 Rust 与 Godot 的 SimCity 2000 开源重制版）的原生音乐合成体系：核心合成器全部由 Rust cratesc2k_audio承担，桥接 crateopensc2k_audio以 GDExtension 形式向 Godot 暴露FluidMidiSynth类，而 FluidSynth 则在运行时按需加载、绝不静态链接。读完本文，你将掌握从标准 MIDI 文件解析、事件驱动的音序器（Sequencer）渲染、多线程缓冲策略，到 SoundFont 选择与回退、构建命令、测试方法与 LGPL 合规设计的完整链路，可直接用于理解或复用这套"引擎无关音频核心 + 桥接层"的架构。

分层架构：核心 crate 与桥接 crate

原生音频遵循项目整体的"核心（core）/ 桥接（bridge）"分层规则（参见 native-workspace.md）：

• 核心 cratesc2k_audio，位于 native/core/audio。它包含定时 MIDI 事件、音序器、FluidSynth 运行时加载器与安全的合成器封装，没有任何依赖、没有任何 Godot/引擎类型，因此cargo test可以直接运行，未来的其他前端也能复用。
• 桥接 crateopensc2k_audio，位于 native/audio。它编译为一个 GDExtension 库（crate-type = ["cdylib"]），把 Godot 值转换为核心类型，并持有 Godot 类FluidMidiSynth（见 native/audio/Cargo.toml，依赖godot 0.5.5，启用api-4-7与experimental-threads）。
• GDScript 播放器MidiSynthPlayer，位于 game/src/audio/midi_synth_player.gd。它负责音乐线程、流缓冲与曲目状态，每次填充都调用FluidMidiSynth.render。

FluidSynth 本体（LGPL-2.1-or-later）始终作为独立共享库在运行时加载，OpenSC2K 自己的代码保持 MIT 许可。

源码布局：五个关键单元

原文档将核心 crate 划分为以下单元，对应 native/core/audio/src 下的实际文件：

midi.rs：事件种类协议

GDScript 与 Rust 之间通过扁平数组交换事件。midi.rs定义了 8 种事件代码常量：OTHER=0、NOTE_ON=1、NOTE_OFF=2、PROGRAM_CHANGE=3、CONTROL_CHANGE=4、PITCH_BEND=5、CHANNEL_PRESSURE=6、KEY_PRESSURE=7（见 native/core/audio/src/midi.rs）。

FluidMidiSynth.start接收两个平行数组：times（每个事件的秒级时间）与fields（每个事件 4 个整数：kind, channel, a, b，即FIELDS_PER_EVENT = 4）。events_from_fields会校验fields.len() == times.len() * 4，否则返回None。a/b的含义随事件种类变化：音符事件为音高与力度、Program Change 为程序号、CC 为控制器号与数值、弯音/通道压力为数值。

sequencer：事件精度的渲染引擎

Sequencer（native/core/audio/src/sequencer/mod.rs）通过一个MidiOutputtrait 与合成器解耦，trait 只有 5 个方法：send、reset、release_notes、render、active_voices。这样同一个音序器既能驱动 FluidSynth，也能被测试用假合成器驱动。

关键行为（均有源码常量与逻辑印证）：

• 每次渲染都在事件时间切分：block_length计算到下一个事件边界（或曲目终点）为止的帧数，因此输出与请求块大小无关，事件精确落在自己的采样点上。
• seek：Sequencer::seek会从曲首重放到目标位置，期间重放 program、controller、pitch-bend 与 pressure，但不重放音符，从而不产生旧音符的回响。
• 循环：曲目到达终点且开启循环时，release_notes()释放所有音符并回到第 0 帧。
• 释放尾音：MAX_TAIL_SECONDS = 2.0秒；TAIL_BLOCK_FRAMES = 256帧的小块渲染让尾音在最后一声消失后尽快结束，且结束帧与请求大小无关（tail_is_over只在整块边界检查静音或上限）。

fluidsynth：全部 FFI 的集中地

native/core/audio/src/fluidsynth/是唯一调用 FluidSynth 的代码，内部再分四层：

• platform.rs：运行时打开共享库。Unix 用dlopen/dlsym/dladdr，Windows 用LoadLibraryExW/GetProcAddress/GetModuleHandleExW；own_library_path通过dladdr/GetModuleHandleExW找到音频扩展自身所在目录，FluidSynth 从同目录按完整路径打开。
• api.rs：手写的 C 函数表，共 23 个函数（fluid_version、new_fluid_settings、fluid_synth_sfload、fluid_synth_noteon、fluid_synth_write_float等），声明遵循公开 API 文档，不复制任何 FluidSynth 头文件或源码。加载时校验fluid_version主版本必须为 2（SUPPORTED_MAJOR_VERSION）。进程级单例用OnceLock保存，首次调用后固定结果，库缺失不会被反复重试。
• synth.rs：安全的FluidSynth拥有者，实现了MidiOutput。创建时通过 settings API 设置：synth.sample-rate（44.1 kHz）、synth.polyphony=256、synth.midi-channels=16、synth.cpu-cores=1（不开 FluidSynth 工作线程）、synth.threadsafe-api=0（单线程独占）、synth.lock-memory=0、synth.limiter.active=1与synth.limiter.output-limit=0.891（即 -1 dBFS，为同总线上音效留出余量）。SoundFont 加载走fluid_is_soundfont→fluid_synth_sfload，失败时通过log.rs取回该线程最近一条 FluidSynth 错误。
• log.rs：安装fluid_set_log_function，只保留每个线程最近一条 panic/error/warning 消息，供失败调用自解释。

数据流：从 MIDI 文件到扬声器

完整链路如下（对应 docs/fluidsynth.md 的架构图）：

SOUNDS/<track>.MID 或音乐包 MIDI 文件 | StandardMidiFile 解析（主线程） v 事件数组：时间 + 每个事件的 kind/channel/a/b | MidiSynthPlayer 交给音乐线程 v FluidMidiSynth（Rust GDExtension, native/audio） | Sequencer 在每个采样点发送事件 | FluidSynth 以 fluid_synth_write_float 渲染浮点 PCM v AudioStreamGenerator 环形缓冲（1 秒） | Godot 音频线程读取 v AudioStreamPlayer -> Master bus -> 输出设备

具体环节：

1. MIDI 解析：game/src/audio/standard_midi_file.gd 的StandardMidiFile委托桥接层的NativeMidiFile（native/audio/src/midi_file.rs）调用核心的smf::parse（native/core/audio/src/smf.rs），解析 format 0/1 文件，得到带秒级时间、按播放顺序排序的 channel 事件与速度变化。项目刻意保留了自己的解析器而非使用 FluidSynth 自带的 MIDI 播放器，因为曲目结束、间隙与洗牌规则都依赖该解析器，且更换合成器时同一事件流可以无缝切换。
2. 事件装配：MidiSynthPlayer.event_arrays把StandardMidiFile的事件按EVENT_KINDS映射表转换为times/fields两个数组；fluid_synth调用engine.start(...)，若带起始秒再调用engine.seek(start_seconds)。
3. 渲染：音乐线程按 ≤1024 帧的块填充 1 秒环形缓冲（BUFFER_LENGTH_SECONDS = 1.0、PREFILL_SECONDS = 0.20、MAX_FRAMES_PER_FILL = 1024、IDLE_POLL_MSEC = 10，见 game/src/audio/midi_synth_player.gd）。缓冲满时线程等待 10 ms，而不是空转。
4. 输出：FluidMidiSynth.render以 44,100 Hz 立体声 float 帧返回PackedVector2Array，写入AudioStreamGenerator，再由 Godot 重采样到设备速率。音乐因此走 Godot 正常管线：音量设置、暂停、失焦静音、Master bus 全部生效；FluidSynth 不打开任何音频驱动。

FluidMidiSynth的完整公开方法（native/audio/src/fluid_midi_synth.rs）包括：library_error/library_version/library_path（诊断）、probe_library（不使用的预检）、load_soundfont、has_soundfont、start、render、is_complete、position_seconds/duration_seconds、seek、set_looping、set_gain（默认增益DEFAULT_GAIN = 0.35，密集的原版曲目在该电平下达到满刻度，再由 FluidSynth 限制器压到 -1 dBFS 以下）、active_voices。

线程模型：谁在什么时候碰合成器

线程划分是整个设计的关键（源码注释在 native/core/audio/src/fluidsynth/mod.rs 顶部有完整说明）：

• WorkerThreadPool 任务创建FluidMidiSynth并加载 SoundFont（整文件读取，SF3 还要解码）。macOS 系统音色约 10 ms 载入；15 MB 的 SF3 约 1.5 s、占用约 144 MB 内存。
• 主线程随后把已加载的合成器连同每首曲目交给音乐线程，之后不再调用它。MidiSynthPlayer每次_start_playback通过_pending_engine交接，并用_generation计数防止旧曲目覆盖新状态。
• 音乐线程是render的唯一调用者，负责推帧；Godot 音频线程只读环形缓冲，从不调用 FluidSynth，其上也没有文件访问、SoundFont 加载或大分配。
• FluidSynth 进程级采样缓存由 Rust 互斥锁LIFECYCLE保护，创建/加载/销毁合成器时加锁，渲染从不加锁；synth.threadsafe-api=0与synth.cpu-cores=1保证单线程独占且无额外工作线程。
• 音序器的渲染缓冲增长到最大请求后复用（render_block中的left/rightVec）。

构建与检查命令

原文档给出的命令可直接执行：

python3 tools/build_native.py # 构建并安装所有原生库，同时构建 FluidSynth

随后在native/目录下运行 Rust 检查：

cargo fmt cargo fmt --check cargo clippy --all-targets --all-features -- -D warnings cargo test --release

tools/build_native.py会构建桥接库并复制到game/bin/，且会设置OPENSC2K_REQUIRE_FLUIDSYNTH使音频测试在无库环境下也按严格模式执行；CI 同样设置该变量。tools/validate_project.sh在 Godot 检查之前完成同样的构建与单元测试。

FluidSynth 本身的构建

tools/build_fluidsynth.py（tools/build_fluidsynth.py）先由build_native.py触发。要点：

• 固定版本FLUIDSYNTH_VERSION = '2.6.1'，逐一下载 libogg 1.3.6、libvorbis 1.3.7、FLAC 1.5.0、Opus 1.5.2、libsndfile 1.2.2 及 FluidSynth 的子模块源码归档，逐一校验 SHA-256。
• CMake 以FETCHCONTENT_FULLY_DISCONNECTED运行，构建过程不联网下载脚本未固定的任何东西。
• libogg/libvorbis/libFLAC/Opus/libsndfile 编译为静态库打入 FluidSynth 共享库；FluidSynth 自身的所有音频/MIDI/shell/网络/LADSPA/OpenMP 选项全部关闭（-Denable-alsa=OFF、-Denable-pulseaudio=OFF、-Denable-portaudio=OFF等一长串）。
• 脚本会拒绝依赖操作系统外部共享库的产物；脚本内容变更（recipe_hash）会触发整库重建。
• Windows 使用 Visual Studio generator（平台跟随 Python 架构 x64/ARM64）与静态 C 运行时，DLL 无需 VC++ 可再发行组件；macOS 产出 macOS 11+ 的 universal（arm64 + x86_64）库并做 ad-hoc 签名；Linux 静态链接 C++ 运行时，仅依赖 glibc。
• 开发者也可使用系统 FluidSynth 2：macOS 加载器额外尝试/opt/homebrew/lib、/usr/local/lib，Linux 走系统搜索路径；设OPENSC2K_FLUIDSYNTH环境变量可强制只使用指定路径的库。

运行时库加载顺序与打包布局

api.rs::library_candidates的候选顺序：环境变量覆盖 → 音频扩展自身目录 → 系统搜索路径 → 开发目录。open_first逐个尝试，错误信息会列出每次失败原因。Windows 上LoadLibraryExW使用LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR | LOAD_LIBRARY_SEARCH_DEFAULT_DIRS，从不搜索当前目录与 PATH；macOS/Linux 因按完整路径打开，无需@rpath/RPATH/$ORIGIN处理。game/opensc2k_audio.gdextension的[dependencies]段让 Godot 导出时把 FluidSynth 与扩展放在同一目录：

若扩展旁没有该库，加载器退回系统搜索路径与开发目录；全部失败时游戏在设置与音乐提示中显示原因，不播放 MIDI 音乐，但录制原声带仍可播放。

SoundFont 选择与回退

Settings > Audio > Music SoundFont列表写偏好audio/music_soundfont（实现见 game/src/audio/sound_font_catalog.gd）：

系统音色集就地读取、从不复制：

• macOS：/System/Library/Components/CoreAudio.component/Contents/Resources/gs_instruments.dls（macOS MIDI 合成器的 Roland GS 集）；
• Windows：%SystemRoot%\System32\drivers\gm.dls（Microsoft GS Wavetable Synth 的 Roland GS 集）；
• Linux/BSD：依次尝试/usr/share/sounds/sf2/default-GM.sf2、/usr/share/sounds/sf3/default-GM.sf3、/usr/share/soundfonts/default.sf2、发行版 FluidR3 GM 文件，最后是可执行文件旁的FluidR3Mono_GM.sf3（仅 Linux 包包含，菜单标签为Bundled SoundFont (FluidR3 Mono)）。

SoundFontCatalog.candidates给出尝试列表：自定义音色失败（缺失/不支持/损坏）时回退到系统音色集；若仍无音色可载或 FluidSynth 缺失，则无 MIDI 音乐：等待中的曲目立即以track_finished结束，之后曲目持续失败直到选择改变。状态消息会点名每次失败。播放中切换音色会从当前曲目位置继续播放新音色。首次 MIDI 播放时才加载 SoundFont（而非启动时），首曲等待加载完成。

测试矩阵

• Rust 单元测试（cargo test --release，在native/audio）：覆盖音序器；在有库时覆盖 FluidSynth——有效/无效/截断/缺失的 SoundFont、音色切换、program、鼓通道、力度、弯音、延音、音量、表情、声像、增益与库缺失。无库时这些测试带提示通过，除非设置了OPENSC2K_REQUIRE_FLUIDSYNTH。
• 测试用 17 KB 的game/tests/fixtures/soundfonts/opensc2k_test_gm.sf2，由 native/core/audio/src/fluidsynth/test_soundfont.rs 生成，无第三方内容；设OPENSC2K_UPDATE_FIXTURES=1可重新写出。
• Godot 集成测试game/tests/fluidsynth_music_test.gd：库与音色错误、MIDI 解析、渲染、循环、seek、回退顺序、保存的偏好、延迟启动、运行中切换与曲目结束。

许可合规：MIT 程序如何安全使用 LGPL 库

FluidSynth 是独立的 LGPL-2.1-or-later 库，OpenSC2K 通过以下设计满足 LGPL 第 6 节"用户可更换库"的要求（详见 docs/fluidsynth.md 的 "LGPL considerations"）：

• 独立、可替换：从不静态链接或构建期链接，运行时打开、只调用公开 API；同名或OPENSC2K_FLUIDSYNTH指定的任何兼容 FluidSynth 2 构建都可替换（6b）。
• 不复制代码：FFI 声明按 API 文档手写，OpenSC2K 保持 MIT（第 5 节）。
• 源码未改动：FluidSynth 与其内部库均从固定、未改动的上游归档构建，无任何补丁。
• 对应源码：每次发布附带OpenSC2K-<version>-fluidsynth-source.zip，包含所有源码归档、构建脚本与 SHA-256 清单；tools/build_fluidsynth.py --source-bundle <folder>可生成本地副本（第 4、6 节）。
• 通知：LGPL 文本、FluidSynth 版权与作者等信息在包内及游戏内（About > Licenses，文本位于 game/assets/licenses/fluidsynth）。

此外，项目不用官方 FluidSynth Windows 二进制，因其sndfile.dll内还含 mpg123 与 LAME（LGPL），无法精确给出对应源码版本；固定源码构建让各平台对应源码一致。

已知限制（当前仓库事实）

• Windows 构建只在 CI（windows-2025）上验证，未在本地测试。
• macOS 包为 ad-hoc 签名；公证还需要同一身份签名 FluidSynth。
• SF3 音色加载时解码，大型自定义音色可占用数百 MB 内存；synth.dynamic-sample-loading可降低占用，但会在音乐线程上做文件读取，故保持关闭。
• 首曲加载音色：大型 SF3 会让首曲延迟数秒；录制原声带不受影响。
• Linux 系统若无任何 SoundFont 包，在玩家手动选择自定义音色前无法播放 MIDI 音乐。

• 游戏开发