第 1 章：搭建 SFML 并启动 Timber!!!

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

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

在“第 1 章：搭建 SFML 并启动 Timber!!!”中，第三版示例使用 SFML 2.6.1 时代 API。本页保留与本章有关的 2.6 系列合同；SFML 3 的事件、角度、时长和构造接口差异不会被静默回填。升级工具链时必须单独记录本章迁移补丁，不能把版本不匹配误判为“配置 sfml（setting up sfml）”概念错误。

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

正式概念与运行状态合同

配置 sfml（setting up sfml）

这个正式目录节点落在 构建与资源 边界：编译器、SFML 二进制、运行库和资源路径。在本页中，它参与“从匹配架构的 C++20/SFML 构建开始，完成事件轮询、更新、clear-draw-display 与资源加载闭环”。验收时保存编译与链接命令、动态库架构、当前工作目录、loadFromFile 返回值和逐帧调用日志，不能只凭最终画面判断。

timber 项目规划（planning timber）

这个正式目录节点落在 实时状态 边界：窗口事件、时间步与游戏对象更新。在本页中，它参与“从匹配架构的 C++20/SFML 构建开始，完成事件轮询、更新、clear-draw-display 与资源加载闭环”。验收时保存窗口仍打开时每帧先处理事件，再更新状态，并且只按 clear、draw、display 顺序提交一次画面，不能只凭最终画面判断。

sfml 窗口（opening a window using sfml）

这个正式目录节点落在 可见提交 边界：clear、draw、display 的帧边界。在本页中，它参与“从匹配架构的 C++20/SFML 构建开始，完成事件轮询、更新、clear-draw-display 与资源加载闭环”。验收时保存编译与链接命令、动态库架构、当前工作目录、loadFromFile 返回值和逐帧调用日志，不能只凭最终画面判断。

游戏循环（the game loop）

这个正式目录节点落在 构建与资源 边界：编译器、SFML 二进制、运行库和资源路径。在本页中，它参与“从匹配架构的 C++20/SFML 构建开始，完成事件轮询、更新、clear-draw-display 与资源加载闭环”。验收时保存窗口仍打开时每帧先处理事件，再更新状态，并且只按 clear、draw、display 顺序提交一次画面，不能只凭最终画面判断。

错误处理（handling errors）

这个正式目录节点落在 实时状态 边界：窗口事件、时间步与游戏对象更新。在本页中，它参与“从匹配架构的 C++20/SFML 构建开始，完成事件轮询、更新、clear-draw-display 与资源加载闭环”。验收时保存编译与链接命令、动态库架构、当前工作目录、loadFromFile 返回值和逐帧调用日志，不能只凭最终画面判断。

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

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

先预测“干净启动 Timber”会怎样穿过 构建与资源 → 实时状态 → 可见提交，再切换场景和正式概念。每次操作都必须能回到同一初始状态。

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

依次执行 配置目标 → 创建窗口 → 轮询事件 → 更新并绘制 → 提交帧。每一步只选中一个阶段，并持续检查“窗口仍打开时每帧先处理事件，再更新状态，并且只按 clear、draw、display 顺序提交一次画面”。

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

注入“忽略纹理加载失败或运行目录变化，让空精灵进入绘制阶段”，定位第一项不一致；撤销后用完全相同的“资源路径失效”重放。只有中间状态和最终输出一起恢复才算修复。

易错边界与工程取舍

从“能打开窗口”而不是“IDE 没有红线”开始

Beginning C++ Game Programming 第 3 版用四个逐步变复杂的游戏学习 C++20 和 SFML，第一个项目是 Timber!!!。第 1 章的完成标准不是记住 API 名，而是建立一条可重复的证据链：源码按目标语言标准编译、链接到匹配架构的库、运行时能找到资源、窗口能处理事件并持续呈现背景。

把 OpenGL 上下文、操作系统窗口和常用二维资源封装成 C++ 对象。第三版以 Visual Studio 2022 为主要环境，但核心约束不依赖 IDE：编译器架构、Debug/Release 配置、SFML 二进制和运行库必须一致。

配置 SFML：头文件、库和运行时是三道门

“能包含头文件”只证明编译阶段找到声明。链接阶段还要找到 sfml-graphics、sfml-window、sfml-system 的对应库；动态链接时，启动阶段还要能找到相同版本与架构的动态库。混用 32/64 位、Debug/Release 或不同编译器 ABI，都会在不同阶段失败。

在 Visual Studio 2022 中，应让项目平台与下载的 SFML 包一致，分别配置包含目录、库目录和依赖项；Debug 配置使用匹配的调试库。跨平台项目可用 CMake 表达同一依赖关系，关键是把配置写进可复现文件，而不是只存在某台机器的 IDE 面板。

cmake_minimum_required(VERSION 3.20)
project(timber LANGUAGES CXX)
 
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)
 
find_package(SFML 2.6 COMPONENTS graphics window system REQUIRED)
 
add_executable(timber src/main.cpp)
target_link_libraries(timber PRIVATE sfml-graphics sfml-window sfml-system)

这个示例锁定 SFML 2.6 风格 API，与书中代码代际相符。若项目升级到 SFML 3，应同时按其迁移文档调整包名和事件 API，不能只替换二进制。依赖版本是源码契约的一部分。

资源目录：相对路径由运行目录解释

书中项目把背景、字体和音效放在资源目录。loadFromFile("assets/graphics/background.png") 的相对路径从进程当前工作目录解释，不是从 .cpp 文件位置解释。IDE、测试工具和直接双击可执行文件可能给出不同工作目录，因此构建应把资源复制到约定位置，启动日志应报告实际路径上下文。

add_custom_command(TARGET timber POST_BUILD
  COMMAND ${CMAKE_COMMAND} -E copy_directory
          "${CMAKE_SOURCE_DIR}/assets"
          "$<TARGET_FILE_DIR:timber>/assets")

发布包要把可执行文件、匹配动态库与资源一起视为产物。资源加载失败不应继续进入主循环并画一个白色占位：它会把根因延迟成“画面怎么没出来”。初始化阶段一旦缺少必需背景，应输出资源路径并返回非零状态。

规划 Timber：把本章交付范围锁小

遵循垂直切片：本章只要求打开窗口、处理关闭、绘制静态背景。第 2 章再让云和蜜蜂移动并学习变量、运算符与分支；第 3 章加入字符串、时间、输入和 HUD；第 4 章加入循环、数组、枚举和函数；第 5 章才完成碰撞、音效与结束条件。

这种范围划分让每章只有一组新增假设。若第一章就加入 delta time、复杂状态机与碰撞，窗口或资源出错时很难定位。先取得稳定的第一帧，再迭代机制。

需求可以写成四条可验收结果：窗口标题正确；关闭按钮能结束进程；背景完整覆盖预期视口；资源加载失败时不进入循环。每条都能通过运行或故障注入验证。

屏幕坐标与内部坐标

适合表达像素尺寸和鼠标位置。

表达玩家、树木和碰撞区域在世界中的位置。第一章默认视图让两者看起来接近，但后续摄像机、缩放、分辨率适配会打破一一对应。

输入也要选择空间。sf::Mouse::getPosition(window) 给窗口像素坐标；世界命中测试通常要用 window.mapPixelToCoords 映射到当前视图。把 HUD 放在固定屏幕层、把实体放在世界层，可避免相机移动时分数文本跟着漂移。

纹理像素、精灵局部坐标、世界变换和窗口像素是四层概念。调试位置时打印“值属于哪个空间”，比只打印两个数字更有意义。

创建窗口与最小入口

在主函数作用域内创建，使它比循环和绘制操作活得更久。窗口尺寸不应在业务代码各处重复；本章用常量集中初始视口。

#include <SFML/Graphics.hpp>
#include <cstdlib>
 
int main()
{
    constexpr unsigned windowWidth = 1280;
    constexpr unsigned windowHeight = 720;
 
    sf::RenderWindow window(
        sf::VideoMode(windowWidth, windowHeight),
        "Timber!!!",
        sf::Style::Titlebar | sf::Style::Close);
 
    if (!window.isOpen())
        return EXIT_FAILURE;
 
    while (window.isOpen()) {
        window.clear(sf::Color::Black);
        window.display();
    }
    return EXIT_SUCCESS;
}

这段还不能正常关闭，因为它没有处理事件，只用于证明构造和呈现链。若循环占满 CPU，可在开发阶段启用垂直同步或帧率上限，但二者只用于节流，不替代正确的时间步进；计时属于后续章节。

游戏循环：先耗尽事件再绘制

使程序从“一次执行完”变为持续响应。第一章世界状态只有窗口与背景，仍应保留清晰阶段；后续机制可以插入更新阶段，而不用重写窗口生命周期。

与实时输入不同。关闭、文本输入和单次按下适合事件；角色持续移动更适合每帧查询键盘状态。只处理一条事件会让队列在快速拖动或按键时积压。

while (window.isOpen()) {
    sf::Event event;
    while (window.pollEvent(event)) {
        if (event.type == sf::Event::Closed)
            window.close();
        if (event.type == sf::Event::KeyPressed &&
            event.key.code == sf::Keyboard::Escape)
            window.close();
    }
 
    if (!window.isOpen())
        break;
 
    window.clear(sf::Color::Black);
    window.display();
}

事件处理后再次检查窗口状态，避免关闭后仍提交一帧。SFML 3 使用新的事件接口形式，本页代码面向第三版配套的 SFML 2.6 代际；升级依赖时要整体迁移并重新验证。

加载背景：纹理拥有资源，精灵只引用

负责资源。

只是借用纹理。把局部纹理绑定给返回的精灵会留下悬空关联，常表现为白块、错误图像或未定义结果。

#include <SFML/Graphics.hpp>
#include <cstdlib>
#include <iostream>
 
int main()
{
    sf::RenderWindow window(sf::VideoMode(1280, 720), "Timber!!!");
    sf::Texture backgroundTexture;
 
    if (!backgroundTexture.loadFromFile("assets/graphics/background.png")) {
        std::cerr << "failed to load assets/graphics/background.png\n";
        return EXIT_FAILURE;
    }
 
    sf::Sprite backgroundSprite;
    backgroundSprite.setTexture(backgroundTexture);
    backgroundSprite.setPosition(0.0F, 0.0F);
 
    while (window.isOpen()) {
        sf::Event event;
        while (window.pollEvent(event))
            if (event.type == sf::Event::Closed)
                window.close();
 
        if (!window.isOpen())
            break;
        window.clear();
        window.draw(backgroundSprite);
        window.display();
    }
    return EXIT_SUCCESS;
}

纹理先声明，精灵后声明；离开作用域时精灵先销毁，纹理后销毁，借用关系始终有效。背景尺寸若与窗口不同，应由设计决定裁切、缩放还是 letterbox，不能无条件拉伸并把宽高比失真当成功。

clear、draw、display 是一帧事务

的顺序不能随意交换。clear 移除上一帧残留，draw 将背景和对象提交到当前后缓冲，display 呈现完成帧。漏掉 clear 会留下拖影，漏掉 display 会看不到新绘制，多个 display 会把一帧拆成不一致呈现。

绘制顺序决定二维覆盖关系：背景先画，角色和树枝后画，HUD 最后画。第一章只有背景，也应从正确层次开始。背景纹理本身不会自动适配窗口变化；若允许 resize，应处理 Resized 事件并更新视图策略。

呈现成功不证明游戏逻辑正确，但它是环境验证的最小闭环。用截图或像素检查确认不是纯黑帧，再进入下一章的动画。

错误处理：初始化失败不进入循环

不能只有一行“failed”。至少要说哪个资源、哪一步、当前约定路径；日志目标也要在无窗口环境可见。必需背景加载失败应返回 EXIT_FAILURE，可选音效在后续章节可以选择禁用并继续，但策略必须显式。

运行期错误与关闭请求不同：关闭是正常生命周期，资源损坏是失败。退出码让脚本和测试区分两者。异常不是唯一方案；SFML 加载 API 通常通过布尔值报告失败，调用者要立即检查。

故障注入最直接：临时改错资源名，程序应打印准确路径、返回非零且不进入循环；恢复路径后应显示背景并可通过关闭按钮退出。只有成功路径和失败路径都符合预期，第 1 章才完成。

先预测：函数内创建 sf::Texture texture，把绑定它的 sf::Sprite 按值返回，调用者绘制会怎样？精灵不拥有纹理，函数返回时纹理销毁，精灵留下失效关联；应让纹理由更长生命周期对象拥有。

小结

• SFML 环境要同时验证编译、链接、动态加载和资源路径，IDE 无红线不是完成证据
• 第 1 章 Timber 只交付窗口、事件循环和静态背景，后续章节再逐层加入动画与机制
• 屏幕坐标、视图坐标、世界内部坐标和纹理局部坐标分层，输入命中要经过正确映射
• 每帧先耗尽窗口事件，再按 clear-draw-display 构造并呈现完整画面
• sf::Texture 拥有图形资源，sf::Sprite 借用纹理；声明和销毁顺序必须覆盖绘制期
• 必需资源加载失败时携带路径上下文退出，不能带着无效状态进入主循环