第 20 章：火球与声音空间化

第三版来源、工具链与版本边界

“第 20 章：火球与声音空间化”对齐 Packt 2024 年第三版的对应章节范围，并以官方公开代码仓库和 SFML 官方文档核对本页可公开验证的工程事实。本页是独立中文重写，不复现原书正文，也不把商品页、目录或代码仓库冒充完整原版。

在“第 20 章：火球与声音空间化”中，第三版示例使用 SFML 2.6.1 时代 API。本页保留与本章有关的 2.6 系列合同；SFML 3 的事件、角度、时长和构造接口差异不会被静默回填。升级工具链时必须单独记录本章迁移补丁，不能把版本不匹配误判为“声音空间化（spatialization）”概念错误。

• Packt：Beginning C++ Game Programming, Third Edition：在“第 20 章：火球与声音空间化”中，核对 2024 年第三版、C++20、SFML、四个项目、21 个正式教学章节及章节次序；不把商品页当作正文全文。
• PacktPublishing：第三版官方代码仓库：在“第 20 章：火球与声音空间化”中，核对 Timber、Pong、ZombieShooter、Run 四个项目的公开代码与资源组织；代码许可证不等于原书正文授权。
• SFML 2.6 官方教程：在“第 20 章：火球与声音空间化”中，核对本书使用的 SFML 2.6 系列 Window、Graphics、View、VertexArray、Shader 与 Audio API 语义。
• SFML 2.6：Sounds and music 官方教程：在“第 20 章：火球与声音空间化”中，核对 SoundBuffer 生命周期、Sound/Music 区别、listener 与声音空间化边界。

正式概念与运行状态合同

声音空间化（spatialization）

这个正式目录节点落在 世界事件 边界：Fireball 生成、运动、碰撞与生命周期。在本页中，它参与“让 Fireball 事件通过 SoundEngine 设置声源位置，并由 SFML listener、距离和衰减产生可解释的空间听感”。验收时保存Fireball 世界坐标、listener position/direction、minDistance、attenuation、SoundBuffer 地址和播放状态，不能只凭最终画面判断。

sfml 音频（sfml audio）

这个正式目录节点落在 音频空间 边界：listener、声源位置、距离和衰减。在本页中，它参与“让 Fireball 事件通过 SoundEngine 设置声源位置，并由 SFML listener、距离和衰减产生可解释的空间听感”。验收时保存声源和 listener 使用同一世界坐标系，SoundBuffer 生命周期覆盖播放，HUD 音效不被错误空间化，不能只凭最终画面判断。

声音引擎（soundengine）

这个正式目录节点落在 非空间界面 边界：HUD 类、菜单提示与固定反馈。在本页中，它参与“让 Fireball 事件通过 SoundEngine 设置声源位置，并由 SFML listener、距离和衰减产生可解释的空间听感”。验收时保存Fireball 世界坐标、listener position/direction、minDistance、attenuation、SoundBuffer 地址和播放状态，不能只凭最终画面判断。

火球（fireballs）

这个正式目录节点落在 世界事件 边界：Fireball 生成、运动、碰撞与生命周期。在本页中，它参与“让 Fireball 事件通过 SoundEngine 设置声源位置，并由 SFML listener、距离和衰减产生可解释的空间听感”。验收时保存声源和 listener 使用同一世界坐标系，SoundBuffer 生命周期覆盖播放，HUD 音效不被错误空间化，不能只凭最终画面判断。

hud 类（hud class）

这个正式目录节点落在 音频空间 边界：listener、声源位置、距离和衰减。在本页中，它参与“让 Fireball 事件通过 SoundEngine 设置声源位置，并由 SFML listener、距离和衰减产生可解释的空间听感”。验收时保存Fireball 世界坐标、listener position/direction、minDistance、attenuation、SoundBuffer 地址和播放状态，不能只凭最终画面判断。

先预测，再操作三个本页实验

实验一：从源码到可见结果

先预测“火球接近玩家”会怎样穿过 世界事件 → 音频空间 → 非空间界面，再切换场景和正式概念。每次操作都必须能回到同一初始状态。

实验二：逐步执行状态轨迹

依次执行 生成火球 → 提交世界位置 → 设置 listener → 播放声源 → 检查衰减。每一步只选中一个阶段，并持续检查“声源和 listener 使用同一世界坐标系，SoundBuffer 生命周期覆盖播放，HUD 音效不被错误空间化”。

实验三：单一故障与同输入恢复

注入“把屏幕像素位置直接当世界声源位置，相机移动时听感漂移但火球逻辑位置未变”，定位第一项不一致；撤销后用完全相同的“HUD 提示音”重放。只有中间状态和最终输出一起恢复才算修复。

易错边界与工程取舍

从“看得见的距离为何听起来不对”开始

火球一边移动一边发声，是连接玩法事实、世界坐标和音频表现的理想对象。若画面用像素、SFML 音频却直接把数百像素当声学单位，火球离 Player 一小段屏幕距离就可能几乎听不见。

先必须是正确的玩法对象，之后才能成为可靠声源。

不应改变命中结果；音频失败也不能回滚伤害。

施放是请求，生成是提交结果

Player 规则验证当前阶段、是否存活、冷却、费用和朝向。按住键不能每帧生成；请求失败不进入冷却。

void PlayerUpdate::tryCast(const CastIntent& intent, UpdateContext& context)
{
    if (!intent.pressed || !state_.alive || state_.fireballCooldown > 0.0F)
        return;
 
    context.commands.push_back(SpawnFireball{
        ownerId_, muzzlePosition(), facing_, config_.fireballSpeed});
    state_.fireballCooldown = config_.fireballCooldown;
}

只在 Playing 递减，Paused 冻结；重启恢复初始值。是否在生成失败时回滚冷却要写成明确协议，推荐先验证资源再接受施放。

Factory 构造完整 Projectile

组装 ProjectileUpdate、FireballGraphics、碰撞体和身份。出生位置应位于 Player 碰撞体外，避免首帧撞到施放者。

std::unique_ptr<GameObject> FireballFactory::create(const SpawnFireball& request)
{
    const FireballConfig& config{catalog_.fireball()};
    validate(config);
    return std::make_unique<GameObject>(
        ids_.next(),
        Transform{request.position},
        std::make_unique<ProjectileUpdate>(
            request.owner, request.direction * request.speed,
            config.damage, config.lifeSeconds),
        std::make_unique<FireballGraphics>(textures_.get(config.texture)));
}

是稳定 GameObjectId，不保存 Player 裸指针。

高速投射物需要扫掠碰撞

火球每帧移动距离可能超过目标宽度，只看终点 AABB 会穿透。宽相阶段先查询运动包围盒附近对象，窄相阶段计算最早命中时间。

const sf::FloatRect sweptBounds{unionBounds(previousBounds, candidateBounds)};
for (GameObjectId target : world.queryDamageable(sweptBounds)) {
    if (target == ownerId_)
        continue;
    if (const auto hit = sweep(previousBounds, velocity_ * dt,
                               world.collider(target));
        hit && hit->time < earliest.time) {
        earliest = {*hit, target};
    }
}

提交 DamageCommand、FireballHit 事件和 DestroyCommand。三个结果来自同一命中事实，不能让图形或声音再次判断碰撞。

寿命、边界与一次退役

同时设置世界边界，防止飞出关卡的对象永久存在。

由 ProjectileUpdate 私有保存；标记后不再产生伤害或音效。世界提交器对重复 DestroyCommand 也应幂等。

SFML 音频的 Listener 与声源

使用 sf::Listener::setPosition 设置。二维世界可映射到音频 x/y 平面，并给 z 固定值；所有声源必须使用相同约定。

sf::Vector3f AudioSpace::toAudio(sf::Vector2f world) const
{
    return {world.x * unitsPerPixel_, world.y * unitsPerPixel_, 0.0F};
}
 
void SoundEngine::setListener(sf::Vector2f playerPosition)
{
    sf::Listener::setPosition(audioSpace_.toAudio(playerPosition));
}

例如 100 像素映射为 1 音频单位。比例改动后 minimum distance 也要按同一单位审查。

近距与衰减参数

通过 setMinDistance 设置；

通过 setAttenuation 设置。两者应按试听和可重复距离样例调整，不使用任意默认值。

void SoundEngine::playSpatial(SoundId id, sf::Vector2f worldPosition)
{
    Voice& voice{acquireVoice(priorityOf(id))};
    voice.sound.setBuffer(buffers_.at(id));
    voice.sound.setRelativeToListener(false);
    voice.sound.setPosition(audioSpace_.toAudio(worldPosition));
    voice.sound.setMinDistance(cues_.at(id).minimumDistance);
    voice.sound.setAttenuation(cues_.at(id).attenuation);
    voice.sound.play();
}

菜单确认、HUD 提示等非世界声音应 setRelativeToListener(true)，避免 Listener 移动改变 UI 音量。

SoundEngine 消费带位置的事实

SoundEngine 从 FireballSpawned 播放施放声，从 FireballHit 播放命中声。事件位置来自规则提交点，不读取已销毁火球。

近处命中通常高于远处循环环境声。抢占停止旧 voice 后必须重新设置 Buffer、位置、relative、minDistance、attenuation 和音量，防止复用残留配置。

HUD class 只投影生命与冷却

生命变化和冷却就绪都来自提交后的 snapshot。

void Hud::update(const PlayerSnapshot& player)
{
    healthText_.setString("HP " + std::to_string(player.health));
    const float ratio{player.fireballCooldownTotal > 0.0F
        ? std::clamp(1.0F - player.fireballCooldownRemaining /
                     player.fireballCooldownTotal, 0.0F, 1.0F)
        : 1.0F};
    cooldownBar_.setSize({cooldownWidth_ * ratio, cooldownHeight_});
    cooldownText_.setString(ratio >= 1.0F ? "READY" : "CHARGING");
}

HUD 不因看到 READY 就重置冷却，也不消费伤害。PlayerHurt 事件可以触发短暂闪烁，但最终数字始终以 snapshot 为准。

一帧中的事实顺序

先采样 CastIntent；Player 验证并追加生成命令；现有火球扫掠运动并追加命中结果；世界提交生成、伤害和销毁；生成带最终位置的事件与 PlayerSnapshot；Listener 更新到提交后的 Player 坐标；SoundEngine 消费事件；HUD 投影快照；最后渲染。

先预测：把火球放在 Listener 左、右、近、远四个固定位置，关闭混响和其他声音。正确结果应是左右方向对称、近处音量稳定、远处平滑减弱；若 100 像素就几乎静音，应先检查音频坐标比例，而不是盲目提高总音量。

验收与回归测试

• 按住施放键只生成一次火球；冷却期间请求被拒绝且不重复重置计时。
• 高速火球跨越窄目标时仍找到最早命中，只产生一组伤害、FireballHit 和销毁。
• 命中、TTL 与越界同帧满足时只退役一次；销毁后事件不读取对象地址。
• Listener 与四个固定声源使用统一 AudioSpace，验证左右、近距和衰减单调性。
• voice 池复用后所有空间属性被重设；UI 声音保持 relative，不随 Player 移动。
• HUD 在伤害、冷却、暂停和重启后显示提交值，READY 边界不会抖动。

坐标与生命周期诊断

听到方向错误时，先记录同一逻辑帧的 Player 世界坐标、Listener 音频坐标、火球事件世界坐标、voice 音频坐标和转换比例。Listener 必须来自提交后的 PlayerSnapshot，而不是平滑相机中心；相机带前视或抖动时，用相机做 Listener 会让声音舞台相对 Player 漂移。声源也不能使用屏幕坐标，否则 main view 移动会让静止世界声源听起来跟着移动。

若命中画面正确但没有声音，沿事实链检查 FireballHit 是否在销毁前保存位置，世界提交是否发布事件，SoundEngine 是否取得可用 voice，以及 Buffer 是否仍存活。事件必须携带值类型位置，不能只携带即将销毁的 GameObjectId 再延迟查询。若同一次命中播放两声，比较事件序号，确认 ProjectileUpdate 的退役标记与世界提交器的幂等销毁同时生效。

voice 复用故障可用“空间声、UI 声、空间声”的序列复现。第二个声音设置 relative 后，第三个空间声音必须显式恢复 relative=false，并覆盖位置、近距、衰减、音量、音高和循环标志。测试不依赖人耳：读取 voice 配置快照并逐字段断言，再用固定左右位置做集成试听。

最后核对玩法与表现的失败隔离。声音资源缺失时记录降级并保持伤害结果；HUD 字体加载失败时仍允许火球规则运行；Factory 无法构造火球时不进入冷却或按既定协议回滚。把这些失败注入测试加入回归集，才能证明三条链路共享事实但不共享故障。

小结

• 火球由施放请求开始，经规则验证、Factory 构造、扫掠碰撞和一次退役闭环
• 声音空间化使用统一 AudioSpace、Listener、minimum distance 和 attenuation
• SoundEngine 消费带世界位置的事实，不读取可能已销毁的火球对象
• 空间 voice 池复用时完整重置属性，关键近处声音拥有更高优先级
• HUD class 只投影 PlayerSnapshot，不能反向修改生命或冷却