第 18 章：平台、Player 控制与 Animator

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

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

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

• Packt：Beginning C++ Game Programming, Third Edition：在“第 18 章：平台、Player 控制与 Animator”中，核对 2024 年第三版、C++20、SFML、四个项目、21 个正式教学章节及章节次序；不把商品页当作正文全文。
• PacktPublishing：第三版官方代码仓库：在“第 18 章：平台、Player 控制与 Animator”中，核对 Timber、Pong、ZombieShooter、Run 四个项目的公开代码与资源组织；代码许可证不等于原书正文授权。
• SFML 2.6 官方教程：在“第 18 章：平台、Player 控制与 Animator”中，核对本书使用的 SFML 2.6 系列 Window、Graphics、View、VertexArray、Shader 与 Audio API 语义。

正式概念与运行状态合同

平台地形（platforms）

这个正式目录节点落在 平台物理 边界：地形边界、接触和玩家 Transform。在本页中，它参与“把平台几何、玩家控制、Animator 帧选择与物理状态分离，使动画表现跟随已提交动作”。验收时保存输入意图、物理速度、接地标志、动画状态、累计时间、帧索引和碰撞体，不能只凭最终画面判断。

玩家控制（player controls）

这个正式目录节点落在 控制状态 边界：左右、跳跃、速度和接地条件。在本页中，它参与“把平台几何、玩家控制、Animator 帧选择与物理状态分离，使动画表现跟随已提交动作”。验收时保存控制输入先形成意图，物理决定实际运动，Animator 根据已提交状态选帧；动画不能反向决定碰撞位置，不能只凭最终画面判断。

animator 类（animator class）

这个正式目录节点落在 动画表现 边界：Animator、状态切换、帧时间与 sprite sheet。在本页中，它参与“把平台几何、玩家控制、Animator 帧选择与物理状态分离，使动画表现跟随已提交动作”。验收时保存输入意图、物理速度、接地标志、动画状态、累计时间、帧索引和碰撞体，不能只凭最终画面判断。

玩家动画（player animations）

这个正式目录节点落在 平台物理 边界：地形边界、接触和玩家 Transform。在本页中，它参与“把平台几何、玩家控制、Animator 帧选择与物理状态分离，使动画表现跟随已提交动作”。验收时保存控制输入先形成意图，物理决定实际运动，Animator 根据已提交状态选帧；动画不能反向决定碰撞位置，不能只凭最终画面判断。

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

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

先预测“地面奔跑”会怎样穿过 平台物理 → 控制状态 → 动画表现，再切换场景和正式概念。每次操作都必须能回到同一初始状态。

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

依次执行 采样控制 → 计算物理 → 提交接触 → 选择动画 → 绘制当前帧。每一步只选中一个阶段，并持续检查“控制输入先形成意图，物理决定实际运动，Animator 根据已提交状态选帧；动画不能反向决定碰撞位置”。

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

注入“按渲染帧数推进动画并用 sprite 帧宽修改碰撞体，造成帧率相关速度和碰撞抖动”，定位第一项不一致；撤销后用完全相同的“空中释放方向”重放。只有中间状态和最终输出一起恢复才算修复。

易错边界与工程取舍

从“随机平台为何可能让游戏无解”开始

Run! 的

不能只随机 x、y。若间隙超过 Player 的水平可达距离，程序仍能运行但关卡必死。生成器必须把物理参数转成约束，再在约束内加入变化。

是生成契约。先预测：提高重力但不改平台间距，哪一类平台组合会首先变得不可达？

从跳跃物理推导生成边界

使用与 PlayerUpdate 相同的配置来源。平地近似下，总腾空时间约为起跳上升和下落之和，最大水平距离还要乘安全系数，为输入延迟和边缘落脚留余量。

struct Reachability {
    float maximumGap;
    float maximumRise;
    float minimumWidth;
};
 
Reachability deriveReachability(const PlayerConfig& player)
{
    const float flight{2.0F * player.jumpSpeed / player.gravity};
    return {
        player.runSpeed * flight * 0.75F,
        player.jumpSpeed * player.jumpSpeed /
            (2.0F * player.gravity) * 0.65F,
        player.colliderWidth * 1.5F,
    };
}

配置必须验证 gravity 为正。生成后再用离散模拟跑一次候选轨迹，能发现连续公式没有覆盖的固定步长误差。

平台提交与回收

由生成器追加，Factory 构造完整 GameObject，世界统一加入对象容器与碰撞索引。任何资源失败都不发布半平台。

void PlatformGenerator::ensureAhead(const Camera& camera,
                                    CommandBuffer& commands)
{
    while (lastRight_ < camera.visibleBounds().left + lookAhead_) {
        PlatformSpec next{planNext(lastRight_, lastHeight_)};
        validateReachable(next);
        commands.push_back(SpawnPlatform{next});
        lastRight_ = next.left + next.width;
        lastHeight_ = next.top;
    }
}

不能刚离屏就删除，因为雷达或短暂回看仍可能需要它。若使用对象池，复用前重置 Transform、碰撞状态、外观、旧 id 关联和事件标记；池化不应改变玩法语义。

玩家控制从设备状态变成意图

官方 player controls 不应散落在 Player、窗口循环和 Animator。InputMapper 读取设备，输出第 16 章的 PlayerIntent。

PlayerIntent InputMapper::sample(const InputState& input) const
{
    float axis{input.right - input.left};
    axis = std::clamp(axis, -1.0F, 1.0F);
    return {
        axis,
        input.pressed(Action::Jump),
    };
}

与“当前按住”分开。键位重映射只改 InputMapper；回放记录意图，不记录平台相关键码。

运动积分与落地解算

先保存上一帧脚底，计算候选位置，再查询可能接触的平台。落地要求上一帧脚底不低于平台顶面、当前帧跨过顶面、水平范围重叠且竖直速度向下。

if (velocity.y >= 0.0F &&
    previousBottom <= platform.top &&
    candidateBottom >= platform.top &&
    overlapsHorizontally(playerBounds, platform.bounds)) {
    transform.position.y = platform.top - colliderHeight;
    velocity.y = 0.0F;
    if (!grounded)
        events.push_back(PlayerLanded{ownerId, platform.id});
    grounded = true;
}

不能由动画帧或按键设置。离开平台边缘后，若没有支撑接触则转为空中；状态边沿驱动声音与动画。

Animator 类管理时间，不决定玩法

Animator 不读取键盘，也不修改 grounded。它接收 Player 已提交的动画状态，输出 texture rect。

资源加载时验证帧非空、时长为正且矩形落在纹理范围内。

struct AnimationFrame {
    sf::IntRect textureRect;
    float duration;
};
 
struct AnimationClip {
    std::vector<AnimationFrame> frames;
    bool looping{};
};

不同帧可有不同持续时间。Graphics 只读取 Animator 当前矩形，不在 draw 中推进时间。

正确跨越多帧

若一帧 dt 大于单帧时长，必须用循环跨过多个 animation frames，而不是只前进一次。

void Animator::update(float dt)
{
    remaining_ += std::max(0.0F, dt);
    while (remaining_ >= currentFrame().duration) {
        remaining_ -= currentFrame().duration;
        if (frameIndex_ + 1 < clip_->frames.size()) {
            ++frameIndex_;
        } else if (clip_->looping) {
            frameIndex_ = 0;
        } else {
            remaining_ = 0.0F;
            finishOnce();
            break;
        }
    }
}

不能每帧重复发送。极端 dt 应有最大循环次数保护，资源验证则保证 duration 不为零。

玩家动画状态机

玩家动画由玩法状态派生：grounded 且水平速度明显为零选 Idle；grounded 且移动选 Run；空中向上选 Jump；空中向下选 Fall；PlayerLanded 可触发一次 Land。

目标状态与当前状态相同就不重置，否则 Run 每帧都会回到首帧。进入一次性 Land 时重置；完成后回到 Idle 或 Run。面向方向只翻转 Graphics，不复制另一套动画资源。

三条链路的提交顺序

先采样意图；生成相机前方平台候选；更新 Player 候选运动；用已提交平台集合解算接触；集中提交移动、生成和回收；从最终速度与 grounded 派生动画状态；更新 Animator；最后生成 RenderSnapshot。这样新平台不会在碰撞查询中以半构造状态出现，动画也不会领先玩法。

测试与故障诊断

固定 PlayerConfig 生成上万段，断言尺寸合法、id 唯一、相邻平台通过离散轨迹验证。记录失败 seed，确保可复现。控制测试覆盖按住 jump 只产生一个边沿、空中跳跃被拒绝、离开边缘 grounded 清除、高速下落不穿透。

动画测试用可控 dt：恰好一帧时长前进一次，跨三帧时正确保留余量，循环片段回绕，非循环片段只发送一次完成事件。若角色“滑行但播放 Idle”，同时记录 PlayerIntent、最终 velocity、grounded、动画状态和 clip 名，沿提交顺序找第一处不一致。

调参与可复现性

平台难度、Player 手感和动画节奏必须能分别调整，但共享事实不能分叉。PlayerConfig 保存 runSpeed、jumpSpeed、gravity 和 collider；PlatformGenerator 从这份配置派生可达边界，不复制一组“看起来相同”的常量。AnimationConfig 保存各片段与帧时长，只消费最终速度和 grounded，不反向改变物理。这样修改跳跃高度时，生成器会重新计算合法间隙，而 Animator 只改变何时选择 Jump/Fall，不会悄悄延长腾空时间。

调试快照应包含随机 seed、固定步编号、当前与上一 Transform、速度、支撑平台 id、PlayerIntent、待提交命令、最终事件、动画状态和 frameIndex。发现一次穿透或不可达组合后，把该快照保存成回归用例；仅记录屏幕视频不足以还原随机平台和帧时间。重放时使用固定时间步与同一配置版本，逐步比较命令和事件序列，第一处差异就是调查起点。

输入手感还需要明确容错协议。可以加入短暂的“土狼时间”，允许 Player 刚离开边缘后的少量时间内跳跃；也可加入输入缓冲，让落地前稍早按下 jump 在落地后触发。但这两个窗口必须属于 Player 规则，并用逻辑时间推进，不能由 Animator 帧或真实墙钟决定。测试精确覆盖窗口内外边界，确保暂停时窗口不消耗、重启时全部清零。

碰撞容差也应使用命名配置。过大的 epsilon 会让 Player 悬浮或隔空落地，过小则在浮点误差下抖动。记录接触法线、穿透深度和修正量，断言修正后脚底接近平台顶面且速度不再向下。连续多帧站立时保持同一支撑 id；平台回收前必须确认 Player 不再依赖它，否则先销毁平台会把 grounded 留在无主状态。

最后做组合验收：使用固定 seed 连续跑数分钟，随机打乱非语义相关的对象存储顺序，比较 Player 轨迹、平台 id 序列和动画状态序列。三者应完全一致；渲染帧率可以变化，但逻辑结果不能变化。只有这种可复现闭环，才说明平台、控制和动画真正通过明确协议协作。

小结

• 平台先按 Player 物理推导可达区域，再随机生成、验证和安全提交
• 玩家控制把设备输入变为意图，落地由上一帧到当前帧的顶部跨越确认
• Animator 类只推进动画时间，玩家动画状态来自已提交玩法状态
• animation frames 允许独立时长，跨帧循环必须保留累计余量
• 平台、控制和动画按固定行动帧协议协作，测试结果可由 seed 与意图复现