[DDraceNetwork](https://ddnet.org/) 是一款开源免费的多人合作平台跳跃游戏（其前身是 Teeworlds 的一个叫 DDRace 的模组），上限高游戏性强，是一个非常独特的合作游戏。本项目依赖众多好心的程序员进行维护，作为一个基本成熟稳定的 C++ 游戏项目，我们可以从这个项目中学习到很多开发相关的知识，甚至如果你有什么改进，也可以为原代码仓库提出 Issue 贡献 PR。



![image.png](https://vanblog.zerolacqua.top/static/img/681c4541ebc324951c184c717c6f7d0e.image.webp)



## 项目说明

### 项目环境配置

#### 基本配置

Fork 仓库后克隆代码

```bash
git clone --recursive git@github.com:YourUserName/ddnet.git
```

安装依赖

```bash
sudo apt install build-essential cargo cmake git glslang-tools google-mock libavcodec-extra libavdevice-dev libavfilter-dev libavformat-dev libavutil-dev libcurl4-openssl-dev libfreetype6-dev libglew-dev libnotify-dev libogg-dev libopus-dev libopusfile-dev libpng-dev libsdl2-dev libsqlite3-dev libssl-dev libvulkan-dev libwavpack-dev libx264-dev python3 rustc spirv-tools
```

构建项目

```bash
cmake -Bbuild
cmake --build build
```

如果构建的客户端无法连接服务端，有一种可能是你的 TUN 模式没关。


#### 代码格式化脚本

代码格式化检查，运行 `scripts/fix_style.py` 脚本。由于 Ubuntu 24.04 已经找不到 clang-format-10 的安装包，我们需要自行编译或通过其他途径安装：

- 使用 pip 安装（官方推荐）

 > A lot of the style offenses can be fixed automatically by running the fix script ./scripts/fix_style.py
 > 
 > We use clang-format 10. If your package manager no longer provides this version, you can download it from https://pypi.org/project/clang-format/10.0.1.1/.

 由于执行检查脚本使用的是 python，我们可以通过 pip 安装。如果是用 conda 安装的，在执行 python 脚本时指定 python 环境，就可以顺利运行检查。
 
 ```bash
 pip install clang-format==10.0.1.1
 ```

- 直接下载二进制文件

 https://aur.archlinux.org/packages/clang-format-static-bin
 
 下载后将二进制文件移动到 `/usr/local/bin` 目录下并重命令为 `clang-format-10`

 ```bash
 sudo mv /path/to/clang-format-10_linux-amd64 /usr/local/bin/
 cd /usr/local/bin/
 sudo chmod +x clang-format-10_linux-amd64
 sudo mv clang-format-10_linux-amd64 clang-format-10
 ```

- 通过源码编译（未尝试）

 ```bash
 git clone https://github.com/llvm/llvm-project.git
 cd llvm-project
 git checkout llvmorg-10.0.1

 mkdir build
 cd build
 cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS=clang ../llvm
 make -j$(nproc)
 sudo make install
 ```
 
 编译过程中可能出现部分报错：
 - `std:numeric_limits` 不是 `std` 成员。在相关文件中包含 `#include <limits>` 即可
 - `uintptr_t` 未声明，在相关文件中包含 `#include <cstdint>` 即可


#### 运行单元测试

按项目自述文件操作

```bash
sudo apt install libgtest-dev
cd /usr/src/gtest
sudo cmake CMakeLists.txt
sudo make

# copy or symlink libgtest.a and libgtest_main.a to your /usr/lib folder
sudo cp lib/*.a /usr/lib
```

在我运行时，还需要安装 gmock

```bash
sudo apt install libgmock-dev
```

#### 使用 AddressSanitizer + UndefinedBehaviourSanitizer

> 这个博主配了但试不出来有什么东西，估计是没配置好吧

- 安装 Clang

 ```bash
 sudo apt install clang
 ```


- 编译命令

 ```
 CC=clang CXX=clang++ CXXFLAGS="-fsanitize=address,undefined -fsanitize-recover=address,undefined -fno-omit-frame-pointer" CFLAGS="-fsanitize=address,undefined -fsanitize-recover=address,undefined -fno-omit-frame-pointer" cmake -DCMAKE_BUILD_TYPE=Debug .
 make
 ```

- 运行命令

 ```bash
 UBSAN_OPTIONS=suppressions=./ubsan.supp:log_path=./SAN:print_stacktrace=1:halt_on_errors=0 ASAN_OPTIONS=log_path=./SAN:print_stacktrace=1:check_initialization_order=1:detect_leaks=1:halt_on_errors=0 LSAN_OPTIONS=suppressions=./lsan.supp ./DDNet
 ```

- 结果检查

 运行后，检查生成的 `SAN.*` 文件以查看详细的问题报告。ASan + UBSan 能够发现比 Memcheck 更多的问题，尤其是在内存错误和未定义行为方面。


:::info{title="相关信息"}
参见：https://github.com/ddnet/ddnet/tree/master
:::

#### 使用 VSCode 工作区

> 这个工作区配置挺折腾，中间没配好我真的非常沮丧……

在调试过程中，我发现一旦客户端代码命中断点，就会导致鼠标被游戏捕获无法释放的问题。在 dc 中询问后，Jupstar 大佬给我了一个解决方案。


:::warning{title="注意"}
修改桌面环境之后我的系统会经常报错，虽然不影响使用，但修改之前请考虑！
:::

- 按 `other/vscode/README.md` 的说明，下载相应的二进制文件和安装相应的包（其中 `clang-format` 可按前文所述安装）

 ```
 sudo apt install clangd clang-tidy lldb rustup mold ninja-build xdotool
 ```
- 按照自述文件先按 `Ctrl+Shift+P` 输入 `Scan for kits` 扫描工具箱，再按 `Ctrl+Shift+P` 并选择 `Select a kit`,然后选 `[DDNet]` 开头的工具。

- 如果 cmake 生成时出现 rustup 相关报错，请执行命令：
 ```bash
 rustup default stable
 ```
- 查看一下当前显示是什么桌面环境，如果使用的不是 X11 的桌面环境，需要修改设置

 查看桌面环境：
 ```bash
 echo $XDG_SESSION_TYPE
 ```

 修改设置：
 ```bash
 sudo vim /etc/gdm3/custom.conf
 ```

 把该文件中这一行的注释状态解除：
 ```diff
 - # WaylandEnable=false
 + WaylandEnable=false
 ```
 然后重启即可切换。

- vscode 调试时需要从“运行与调试”中进入，**不要**点击 vscode 底部的 Cmake 调试按钮，否则走的不是工作区中定义的调试配置。



:::info{title="相关信息"}
参见：https://github.com/ddnet/ddnet/blob/master/other/vscode/README.md
:::



### 项目结构

- `src/base` 目录

 由于DDNet是一个跨平台游戏，需要一个抽象层来简化开发，因此该目录包含许多有用的函数来处理这一问题。



- `src/engine` 目录

 游戏引擎所在位置，它处理大多数与玩法无关的东西，比如图形、声音、网络等。



- `src/game` 目录

 所有玩法的代码所在位置，分为客户端和服务器。



 - 服务器端
 
 - 这个游戏使用自己的面向对象的实体分级系统，所有其他实体源于主类 `CEntity`，位于 `src/game/server/entity.h` 目录。

 - 游戏世界在 `src/game/server/gameworld.h` 路径下，管理这些实体。

 - 一些重要实体有：

 - `CCharacter`：代表一个活着的 Tee, 当一个 Tee 生成时会被实例化，当它死亡时会被删除。
 - `CPlayer`：包含了其他没有关联 Tee 的信息（昵称、国籍等）。有关玩家在死亡之间的信息，请参阅此项。


 - 客户端
 
 客户端由许多组件构成，都是在 `src/game/client/component.h` 中定义的继承 `CComponent` 的类：这些组件通过实现视觉方法来提供功能，例如 `OnInit`，`OnMessage` 等等。



 - 网络
 
 网络协议几乎由 python 脚本生成并输出 c++ 代码，例如说，`datasrc/network.py` 定义了所有网络包。

:::info{title="相关信息"}
参见：https://wiki.ddnet.org/wiki/Development/zh

文档：https://codedoc.ddnet.org/
:::

### 贡献代码指南

- 贡献前的准备

 在编写代码前，建议先开一个 issue 讨论想法，确保贡献符合 DDNet 项目的理念。常见的被拒绝贡献包括：
 - 影响游戏玩法的 dummy 扩展
 - 破坏向后兼容性的改动（如网络协议、文件格式或游戏玩法）。

- 编程语言

 DDNet 主要使用 C++，少量使用 Rust，Python 用于代码生成和工具，CMake 用于构建。平台特定代码可能使用 Java（Android）或 Objective-C++（macOS），但不接受其他语言的代码。

- 代码风格

 命名规则：变量、方法和类名使用大驼峰命名法（如 `MaxLength`），避免单字母变量名。

 匈牙利命名法：继承自 Teeworlds，使用前缀如 `m_`（类成员）、`g_`（全局变量）、`p`（指针）等。

 现代 C++ 实践：优先使用 `nullptr`、`true`/`false`，避免 `goto`、默认参数和方法重载。

 代码格式化：使用 clang-format 10 自动格式化代码。

- 最佳实践

 避免在 `if` 语句中赋值：明确分离变量赋值和条件判断。

 Getter 方法命名：避免使用 Get 前缀（如 `MyVariable()` 优于 `GetMyVariable()`）。

 类成员初始化：在声明时直接初始化类成员变量。

 文件命名：使用小写字母和下划线分隔（如 `foo_bar.cpp`）。

- 提交消息
 
 提交消息应描述对玩家/用户的影响，而非技术细节，以便直接用于变更日志。

:::info{title="相关信息"}
参见：https://github.com/ddnet/ddnet/blob/master/CONTRIBUTING.md
:::

## 开始贡献

### Good first issue

*goog first issue* 的作用是什么？

- 一般是开源仓库中比较简单的 issue，可能几行代码就能解决，甚至让人有一种捡漏的感觉，一般会由项目维护者选择简单易上手的、无关痛痒的问题，不亲自处理而是留待潜在的贡献者处理，可以吸纳新人参与到项目贡献中。
- 对于没有什么提交经验的人，面对一个复杂的项目，这种简单的 issue 可以帮助参与者建立对流程的基本认识。对贡献者来说，自己提交的 pr 能被合并是非常有成就感的，尤其是首先提交 pr 的贡献者，看到自己的修改被合并还是很高兴的。

比如我找的这个 issue：https://github.com/ddnet/ddnet/issues/9583 是个很简单的工作，只需要把描述文本修改一下就行。


另外，[这个网站](https://goodfirstissue.dev/)可以帮助你查看流行开源项目中可能的 *goog first issue*。

### PR 常用技巧

- 在 PR 中提及要解决的 issue，一般可以用 `fix#xxxx` 或 `close#xxxx`，这样 github 会自动渲染出链接的 issue 并会提示 PR 将关闭这个 issue
- 想要验证其他人还未被合并的 PR？

 在你已经 Fork 了自己的仓库，并且克隆到本地的基础上，先要添加 ddnet 官方的上游仓库：
 
 ```bash
 git remote add upstream git@github.com:ddnet/ddnet.git
 ```
 
 然后，根据你要拉取的 PR 编号进行拉取，比如我想拉取 ＃9786 PR，我就从 `upstream` 拉取 `pull/9786/head`，然后把这个本地分支命名为 `keb-pr`:
 
 ```bash
 git fetch upstream pull/9786/head:keb-pr
 ```
- 在 issue 中插入视频，直接拖入即可 ｀.mp4｀ 最佳，可直接渲染出播放窗口
- 在 issue 中引用特定提交的代码。在 github 某个提交的代码浏览的界面里，点选行号（按住 shift 可以选择范围），点击菜单选择 `Copy permalink` 即可，以下链接会被 github 渲染成相应区域的代码块：

 > https://github.com/ddnet/ddnet/blob/0aff2c75322a99a218fc6a8d659e8e77d62928e4/src/test/editor.cpp#L5-L8

## 其他的话

### 调整心态

参与代码贡献是一件令人振奋的事情，但中间也会遇到一些会让你感到受挫的事情，你需要以平常心看待它们。

- 项目维护者对你的 PR 的 review 可能比较严格

 一般是因为你的提交存在一些问题，或者不规范的地方，如要求你压缩你的提交，修改提交信息等。正视它们，这些直率的建议也能让你进步的更快。
 
- 社区的评价不一定都是中听的

 社区对你的贡献的评价也可能让你不舒服，尽管他们看起来并没有恶意。比如我贡献一个提交，想获取 dev 身份组时，会有人用 “commit: readme typo fix” 来打趣我（而且这种开源贡献笑话还挺常见的，时不时就会出现一次）。
 
 面对这种情况，还是要调整好心态，如果想要做长期的贡献还是从简单的 issue 开始的。跟进时间长了自然会做出有价值的提交。而且即使是简单的拼写修复提交，仓库的维护人员也一直欢迎和接纳，不要太受社区人员的影响。同时也需要自己提升心理承受能力。

- 开源社区终究也是社区，你并不突出

 社区总有光彩夺目的人，你需要降低期待做好无人理睬的准备。在 Manim 幼儿园的时候就已经有这种无力感了，更别说外国社区，英语蹩脚没有熟人更会让你觉得自己是被无视了。DDNet 社区里虽然有几位国人版主和贡献者，但也都根本没有接触过，颇有一种孤军奋战的感觉。
 
### 大胆去问
 
在 github 上找了个几个月前的 issue，里面提到了了一个小 BUG，我的开发就从地图编辑器开始了。

随着慢慢深入源码，我可以发现代码中其实有很多可以改进的地方，不知不觉已经提了五个 PR 了。在这个过程中，可能会有自己的 PR 或者 issue 没有被仓库协作者看到的情况。你可以大胆地在 DC 群里去请求 review。当然遇到了编程相关的问题，也可以去问问 DC 里的人，如果有了解相关的代码的人，是会给予你帮助的。即使他们可能没有负责这部分的代码，他们也可以为你提供一些有价值的建议。

另外，这次有了五个 PR 之后，我也是鼓起勇气去 @ 了管理员，最后也是如愿以偿地得到了开发者的 role，所以还是得要大胆一点，只要你不犯大病礼貌一点，不会有什么惩罚的。

DDNet 项目贡献杂记

星月湖的华为的软挑大赛总算告一段落了，跌跌撞撞走进复赛已经是出乎意料的结果了（只是可惜了我校内赛的蓝牙耳机，被抢了呜呜）。





## 赛题
这次比赛赛题以“智慧港口”为主题，考查选手在机器人和船只寻路调度的算法。刚开始感觉这个题目和 Screeps 有一点像，但是实际上寻路避障算法都得自己路的，区别还是不少的。


个人认为的若干关键点如下：

- 程序交互

	每帧信息由输入和输出传递，选手程序需要在有限的时间里进行运算，并输出结果。由于跳帧情况的存在，需要尽量保证选手程序每一帧都接收到判题题数据，保证数据同步。
- 计算逻辑：
	
	因为每帧计算限时，可能涉及多线程编程
- 寻路

	寻路算法是这次比赛的关键，寻路用 A* 足够了。船只的寻路是一个比较麻烦的点（船只有体积，且船只的移动不是四方向的），但可以通过一些方式把船只的寻路变为和机器人类似的寻路。
- 避障

	分为机器人之间的避障（初赛），和船只之间的寻路避障（复赛）。机器人的移动是可逆的（即前进可以后退，往右走可以再往左，走回到原位），可以使用一些朴素的避障方法，避障后再原路返回之前的寻路路径上。而船只移动是不可逆的（只有转向和前进的移动），船只避障之后无法简单地回到原位，这就给船避障带来了很大挑战（直至比赛结束我们都没有一个比较满意的方案）。
- 调度策略

	船只和机器人分布在地图的各处，如何把货物尽量多且快得运输到目标点，就是一个非常重要的问题。在复赛阶段，由于增加了机器人（两种）和船只的购买机制，因此怎么搭配各种

可能优化思路有：

- 利用初始化时间

	5000ms 能够做很多事情。比如用洪泛法计算所有点到某个点的路径长度等等（宝贵的打表时间）。
- 优化机器人取货的目标
	
	减少总寻路的长度和总的货物拾取价值。在复赛机器人可以拾取两个货物，对路径优化合并，提出了更高的要求。
- 船只避障

	不再使用那种朴素的避障再返回路径节点的方式，而是尝试进行新的寻路或者局部的寻路，减少船只从避障后恢复的路径长度。
- 炼丹
	
	试各种参数；碰运气，刷随机种子；针对地图进行特化调参。

更多具体的算法讨论，可以参考 [insomniac 的文章](https://xuqi.space/post/15)。

## 学习到了什么东西

这个比赛中我不只收获了赛区二等奖（本来能有一个三等奖就不错了），更重要的是在这个过程中逼着自己学习了新的东西。

- code review
	
 其实平常自己一个人写代码，很少用 PR 功能，也很少去做代码审查。这次比赛算是好好接触了一下这部分流程。（虽然最后代码也没在用 git 管理了，代码也是直接看了x）
- 分支版本控制

 其实是又把 Learn Git Branching 刷了一遍，试了试有源和目标参数的 pull 命令。不过实际上，比赛中版本控制也是做得虎头蛇尾。
- UML 类图
	
 以前听过也看过类图，不过并不是很清楚它具体的规范，这次的初赛索性就试了试，学习了一下绘制的语法，可参考 [mermaid 类图](https://mermaid.js.org/syntax/classDiagram.html)





```mermaid
classDiagram

class Macro_Statics_Method {
 MAP_SIZE = 200
 ROBOT_NUM = 10
 BOAT_NUM = 5
 BERTH_NUM = 10
 TOTAL_FRAME = 15000
 TIME_PER_FRAME = 15
 FRAME_BUFFER_SIZE = 100
 BOAT_CAPACITY
 void output(RobotCommand type, int id=-1, arg=-1)
 void output(BoatCommand type, int id=-1, arg=-1)
 void ok()
 bool checkOk()
}

class World {
+init()
+Map map
+Map origin_map
+Robot robots[ROBOT_NUM]
+Boat boats[BOAT_NUM]
+Berth berths[BERTH_NUM]
+int berth_val[utils::BERTH_NUM]
}

class Map {
+char data[][]
+bool isAccess(int x, int y)
+void modify(int x, int y, TileType type)
}

class Goods {
int x
int y
int deadTime
int val
int come_robot_id
}

class Robot {
int x
int y
int hasGoods
int status
int mbx
int mby
int go_goods_id
}

class Boat {
int capacity
int num
int pos
int status
}

class Berth {
int x
int y
int speed
int time
int come_boat_id = -1
}

class FrameGoods {
int x
int y
int val
}

class FrameRobot {
int hasGoods
int x
int y
int status
}

class FrameBoat {
int status
int targetBerthID
}

class FrameData {
+int frameId
+int frameMoney
+FrameGoods frameGoods[K]
+FrameRobot frameRobots[ROBOT_NUM]
+FrameBoat frameBoats[BOAT_NUM]
}

class FrameBuffer {
+FrameData frameData[]
+int head
+int tail
+bool Read()
+int size() const
+const FrameData &GetLatestFrame()
}

class Controller {
+World &world
+Goods[] &allgoods
+const FrameBuffer frameBuffer
+pathFinder
+Path robotPaths[ROBOT_NUM]
+void UpdateWorld(const FrameData& frameData, vector<Goods>& allGoods)
+void RobotWork()
+void BoatWork(int frame_id)
+void FindBerthAndGo(int id)
+vector<int> CalcBerthPos(int bx, int by, int rx, int ry)
}

class PathFinder {
+World world&
+Path findPath(int sx, int sy, int ex, int ey)
}

World --> Map
World --> Robot
World --> Boat
World --> Berth
FrameData --> FrameGoods
FrameData --> FrameRobot
FrameData --> FrameBoat
Controller --> World
Controller --> Goods
Controller --> PathFinder
PathFinder --> World

```





- 寻路算法

	这次比赛也是把寻路算法稍微系统地过了一遍，对 A* 算法有了更深刻的理解了。当然还有群体寻路、跳点寻路等等。
- 标准错误流

	以前没怎么接触过错误流，这次比赛因为输入输出流被用作传递参数，所以就被迫了解了点这个东西。
- 打日志的重要性

	这个比赛中，代码调试的困难很大，无法实时进行调试（在用判题器的情况下）。通过错误流打印出来的日志对定位错误起到了很大的作用，让我对认真打日志的重要性有了更深刻的认识。

- 协作中不可避免的问题

	在接近一周的比赛中，暴露了很多关于协作的问题：
	
	1. 没有固定的共同工作的时间与场所（除了通宵的那三个晚上我们在一起写代码），缺乏沟通。

	2. 各写各的代码，虽然对赛题有了更深刻的认识，但浪费了不少的时间。同时也出现了工作重复的问题。

	3. 版本管理慢慢荒废。比赛后期基本就是传压缩包。

- 原子变量与锁

	这部分主要是因为队友写的控制代码中需要用到多线程，所以就必须得接触一些。
- wsl 与双系统

	wsl 折腾了没用，在队友的压力和帮助下也是试着在实验室和自己的电脑上装了双系统。比赛结束之后实验室的双系统又折腾了一下卸载掉了，自己电脑上的留着打算用来学习。
- mingw 的计时有问题

	sleep_for 无法准确阻塞主线程，参见：[C/C++中如何稳定地每隔5ms执行某个函数？ - 知乎 (zhihu.com)](https://www.zhihu.com/question/536739862)

- 标准库的使用

	- 容器

		- `std::priority_queue`
		- `std::map`
			
			- 正确地通过索引访问元素
			- 类实例作为 `key` 时正确定义 `operator<`	
		- `std::optional`
		- `std::set`
	- 函数
	
		- `std::greater`
		- `std::less`
	- 算法
		
		- `std::iota`
		- `all_of`
		- `any_of`
		- `none_of`
		- `find_if`

## 有什么感想

比赛强迫自己学了很多新东西，这是平时独立自学所达不到的效果，有时候还是得多逼自己一下。熬夜也是熬出了新的记录。

比赛的队友很给力，被全程带飞哈哈哈哈。一个队友基础特牢，由他负责代码的框架；另一个队友行动力特别强，虽然代码不太规范，但他想到的方法能很快地实现。而我的话，虽然想到一个主意但却又经常拖着写半天写不出来，只好多负责<del>写写</del>改改 bug。这次比赛也让我看到了自身能力实在是有限，再不努把力，真的没有人要了，不希望自己成为一个啥都会一点，但啥都拿不出手的人。

华为软件精英挑战赛感想

记录一下我磕磕绊绊的 Nonebot2 qq 机器人搭建过程。(多半弃坑了，因为 qq 被风控了）



## 使用效果

![图1](https://cdn.zerolacqua.top/images/blogs/QQ机器人搭建体验/1.png)

## 参考链接

### 零基础搭建搭建

- [基于Nonebot2搭建QQ机器人实战篇（一） - 掘金 (juejin.cn)](https://juejin.cn/post/7177022630204014653)
- [Well404的妙妙屋](http://blog.well404.top/categories/NoneBot2%E7%B3%BB%E5%88%97%E6%95%99%E7%A8%8B/)
- [官方文档](https://v2.nonebot.dev/)

## 使用插件

### 商店插件

- [nonebot_plugin_analysis_bilibili](https://github.com/mengshouer/nonebot_plugin_analysis_bilibili)
- [nonebot-plugin-heweather](https://github.com/kexue-z/nonebot-plugin-heweather)
 
 报错解决：[windows平台启动nonebot-plugin-htmlrender 报错 NotImplementedError · Issue #25 · kexue-z/nonebot-plugin-htmlrender (github.com)](https://github.com/kexue-z/nonebot-plugin-htmlrender/issues/25)
- [nonebot-plugin-petpet](https://github.com/noneplugin/nonebot-plugin-petpet)
- [nonebot-plugin-blacklist](https://github.com/tkgs0/nonebot-plugin-blacklist)
- [nonebot-plugin-help](https://github.com/XZhouQD/nonebot-plugin-help)

### 自编插件

- test_derpy_plugin

 获取小马图片。参考了[官方文档](https://v2.nonebot.dev/docs/tutorial/plugin/example)和 [nonebot-plugin-blacklist](https://github.com/tkgs0/nonebot-plugin-blacklist)，使用 requests 和呆站 API 获取图片数据。


## 一些问题

### 常见问题

可在[Well404的妙妙屋](http://blog.well404.top/2022/02/02/nonebot/%E3%80%90NoneBot2%E3%80%91%E7%AC%AC%E4%B8%80%E7%AB%A0%EF%BC%9A%E5%AE%89%E8%A3%85%E5%B9%B6%E9%85%8D%E7%BD%AE%E4%BD%A0%E7%9A%84%E6%9C%BA%E5%99%A8%E4%BA%BA%E5%8F%8A%E5%B8%B8%E8%A7%81%E6%8A%A5%E9%94%99%E7%9A%84%E8%A7%A3%E5%86%B3%E6%96%B9%E6%B3%95/)中找到大部分常见报错，以下是我的一些白痴问题。

### 代码问题

- 机器人搭好了怎么连接 qq？

 还要用 `go-cqhttp` 作为 qq 客户端

- 怎么通过 `url` 发送图片消息？

 - 使用 `MessageSegment`

 - 注意要导入适配器的 `MessageSegment` 

 - 参见：[Discussions · nonebot/discussions (github.com)](https://github.com/nonebot/discussions/discussions/)

 - 例如：

 ``` python
 from nonebot.adapters.onebot.v11 import Message, MessageSegment
 ```

- 实例化 `MessageSegment` 时无法使用图片（版本相关）

 - 参见：[[Bug]: 使用图文时 警告: 图片上传失败: image type error: application/octet-stream · Issue #1660 · Mrs4s/go-cqhttp (github.com)](https://github.com/Mrs4s/go-cqhttp/issues/1660)

 - 代码应为

 ``` python
 MessageSegment(type='image', data={'file':img_url})
 # 本应该是下面这样的写法的
 MessageSegment(type='image', data={'img':img_url})
 ```

 还有其他的方法

 ``` python
 MessageSegment.image(img_url)
 ```

- 怎么接收图片为参数？

 ```python
 # 获取包含图像的消息段列表
 get("image")
 # 获取图像 url 
 messagesegment.data.get("url", "")
 ```

- 获取呆站图像 url （具体应用场景，与 bot 无关）

 - 呆站 API：[API - Derpibooru (trixiebooru.org)API - Derpibooru (trixiebooru.org)](https://trixiebooru.org/pages/api)

 - 注意 `Get` 与 `Post`

- 权限问题示例
 ```python
 from nonebot.adapters.onebot.v11 import (
 Bot,
 Message,
 Event,
 GroupMessageEvent,
 GROUP_ADMIN,
 GROUP_OWNER
 )
 # @xxx.handle()
 async def perssion_test(bot: Bot, event: GroupMessageEvent):
 if await SUPERUSER(bot, event):
 await xxx.send("识别到超级用户权限")
 elif await GROUP_ADMIN(bot, event):
 await xxx.send("识别到管理员权限")
 elif await GROUP_OWNER(bot, event):
 await xxx.send("识别到群主权限")
 else:
 # await xxx.finish("您没有权限（无慈悲）")
 await xxx.send("识别到普通权限")
 ```

 

### 服务器上部署（CentOS 7.6）

- `go-cqhttp` 无法执行

 在 [Releases · Mrs4s/go-cqhttp (github.com)](https://github.com/Mrs4s/go-cqhttp/releases) 中选择合适的程序

- playwright 失败的解决方法

 [[Question] Support for CentOS · Issue #5780 · microsoft/playwright (github.com)](https://github.com/microsoft/playwright/issues/5780#issuecomment-968091413)

- 下载 chrome 与 chromeDriver 

 ```bash
 yum install https://dl.google.com/linux/direct/google-chrome-stable_current_x86_64.rpm
 ```

 [ChromeDriver - WebDriver for Chrome (chromium.org)](https://chromedriver.chromium.org/home)

- Tmux 后台运行机器人

 [Tmux 使用教程 - 阮一峰的网络日志 (ruanyifeng.com)](https://www.ruanyifeng.com/blog/2019/10/tmux.html)

- 查看进程信息

 ```bash
 ps -elf
 ```

- 关闭进程

 ```bash
 killall -u username
 # 或者
 pgrep -u ttlsa | xargs kill -9
 ```

- 安装字体

QQ 机器人搭建体验

啊，我真的懒得写了。明明应该好好学 `Python` 的，怎么学起 `Lua` 了……

其实，我是看到别人用 `Lua` 和 `LÖVE` 框架做了俄罗斯方块，自己也想做一个，才研究了一下 `Lua` （明明 `Python` 也可以做啊）。




## 配置

### Lua

`Lua` 在[官网](https://www.lua.org/)上下载即可，然后配置环境变量，将包含 `Lua` 的文件夹路径加入环境变量中。之后就可以在命令行执行：

```shell
lua54
```

显示相关信息，则说明 `Lua` 配置成功。要注意的是，下载的版本不同，执行的命令可能也不同，我的版本是 `lua-5.4.2` 。这一问题在后面配置 VSCode 时还会遇到。

### LÖVE

`LÖVE` 在[这里](https://love2d.org/)下载，配置环境变量。将包含 `LÖVE` 的文件夹路径加入环境变量中。之后在命令行执行：

```shell
love
```

会启动默认的 `LÖVE` 程序。

### VSCode

没错，我还是想用 VSCode ，所以就需要配置一下了。

VSCode 需要使用相应的拓展。我使用的是 `Code Runner` 和 `Love2D Support` ，在配置拓展时，需要对 `Code Runner` 的默认配置进行修改，并设置 `love.exe` 的路径（我也不知道为什么还要再设一次路径，明明有环境变量了）。

```json
"code-runner.executorMap": {
	"lua": "lua54",
},
"pixelbyte.love2d.path": "xxx\\love-11.4-win64\\love.exe",
```

 `Code Runner` 是用来跑 `Lua` 的， `Love2D Support` 是跑 `LÖVE` 的。在 `Love2D Support` 拓展的设置中，可以设置开启 `LÖVE` 的控制台，这样就能看见 `print()`的输出了（{% del 草 %}）。

### 测试

测试 `Lua` 的情况。

```lua
print("hello world!")
print("你好，世界！")
```

如果中文输出出现乱码，很有可能因为使用的终端是 `cmd` ，有两种方法解决该问题。第一种方法是将使用的终端改为 `powershell`；第二种方法则是将 `cmd` 的编码改为 `UTF-8` 。

```json
"terminal.integrated.defaultProfile.windows": "PowerShell",
"terminal.integrated.shellArgs.windows": ["/K chcp 65001 >nul"],
```

测试 `LÖVE` 的情况。

```lua
-- 初始化矩形的一些默认值
function love.load()
 x, y, w, h = 20, 20, 60, 20
end

-- 每一帧增加矩形的尺寸
function love.update(dt)
 w = w + 1
 h = h + 1
end

-- 绘制有颜色的矩形
function love.draw()
 love.graphics.setColor(0, 100, 100)
 love.graphics.rectangle("fill", x, y, w, h)
end
```

按住 `Alt` + `L`，应当会有 `LÖVE` 程序启动，绘制一个不断变大的青色矩形。当然，拓展的这个快捷键可以在设置中进行修改。

## 编写游戏

### 基础

#### 配置文件

在游戏目录中的 `conf.lua` 文件夹，会在 `LÖVE` 模块加载前运行，可以使用该文件重写 `love.conf` 函数。

 `love.conf` 函数有一个参数，该参数是一个包含所有默认值的 `table` 类型参数。通过 `love.conf` 函数，可以修改默认值，关闭不需要的模块：

```lua
function love.conf(t)
	-- 修改默认值
 t.window.width = 1024
 t.window.height = 768
 
 -- 关闭不需要的模块
 t.modules.joystick = false
 t.modules.physics = false
end
```

以下是 `11.3` 和 `11.4` 的全部默认值：

```lua
function love.conf(t)
 t.identity = nil -- The name of the save directory (string)
 t.appendidentity = false -- Search files in source directory before save directory (boolean)
 t.version = "11.3" -- The LÖVE version this game was made for (string)
 t.console = false -- Attach a console (boolean, Windows only)
 t.accelerometerjoystick = true -- Enable the accelerometer on iOS and Android by exposing it as a Joystick (boolean)
 t.externalstorage = false -- True to save files (and read from the save directory) in external storage on Android (boolean) 
 t.gammacorrect = false -- Enable gamma-correct rendering, when supported by the system (boolean)

 t.audio.mic = false -- Request and use microphone capabilities in Android (boolean)
 t.audio.mixwithsystem = true -- Keep background music playing when opening LOVE (boolean, iOS and Android only)

 t.window.title = "Untitled" -- The window title (string)
 t.window.icon = nil -- Filepath to an image to use as the window's icon (string)
 t.window.width = 800 -- The window width (number)
 t.window.height = 600 -- The window height (number)
 t.window.borderless = false -- Remove all border visuals from the window (boolean)
 t.window.resizable = false -- Let the window be user-resizable (boolean)
 t.window.minwidth = 1 -- Minimum window width if the window is resizable (number)
 t.window.minheight = 1 -- Minimum window height if the window is resizable (number)
 t.window.fullscreen = false -- Enable fullscreen (boolean)
 t.window.fullscreentype = "desktop" -- Choose between "desktop" fullscreen or "exclusive" fullscreen mode (string)
 t.window.vsync = 1 -- Vertical sync mode (number)
 t.window.msaa = 0 -- The number of samples to use with multi-sampled antialiasing (number)
 t.window.depth = nil -- The number of bits per sample in the depth buffer
 t.window.stencil = nil -- The number of bits per sample in the stencil buffer
 t.window.display = 1 -- Index of the monitor to show the window in (number)
 t.window.highdpi = false -- Enable high-dpi mode for the window on a Retina display (boolean)
 t.window.usedpiscale = true -- Enable automatic DPI scaling when highdpi is set to true as well (boolean)
 t.window.x = nil -- The x-coordinate of the window's position in the specified display (number)
 t.window.y = nil -- The y-coordinate of the window's position in the specified display (number)

 t.modules.audio = true -- Enable the audio module (boolean)
 t.modules.data = true -- Enable the data module (boolean)
 t.modules.event = true -- Enable the event module (boolean)
 t.modules.font = true -- Enable the font module (boolean)
 t.modules.graphics = true -- Enable the graphics module (boolean)
 t.modules.image = true -- Enable the image module (boolean)
 t.modules.joystick = true -- Enable the joystick module (boolean)
 t.modules.keyboard = true -- Enable the keyboard module (boolean)
 t.modules.math = true -- Enable the math module (boolean)
 t.modules.mouse = true -- Enable the mouse module (boolean)
 t.modules.physics = true -- Enable the physics module (boolean)
 t.modules.sound = true -- Enable the sound module (boolean)
 t.modules.system = true -- Enable the system module (boolean)
 t.modules.thread = true -- Enable the thread module (boolean)
 t.modules.timer = true -- Enable the timer module (boolean), Disabling it will result 0 delta time in love.update
 t.modules.touch = true -- Enable the touch module (boolean)
 t.modules.video = true -- Enable the video module (boolean)
 t.modules.window = true -- Enable the window module (boolean)
end
```

各配置详细的作用请参考：[Config Files - LOVE (love2d.org)](https://love2d.org/wiki/Config_Files)

#### 运行

`love.run()`是运行的主函数，它包含了运行时的主循环，不同版本的默认值不同。

```lua
-- The default function for 11.0, used if you don't supply your own.
function love.run()
	if love.load then love.load(love.arg.parseGameArguments(arg), arg) end

	-- We don't want the first frame's dt to include time taken by love.load.
	if love.timer then love.timer.step() end

	local dt = 0

	-- Main loop time.
	return function()
		-- Process events.
		if love.event then
			love.event.pump()
			for name, a,b,c,d,e,f in love.event.poll() do
				if name == "quit" then
					if not love.quit or not love.quit() then
						return a or 0
					end
				end
				love.handlers[name](a,b,c,d,e,f)
			end
		end

		-- Update dt, as we'll be passing it to update
		if love.timer then dt = love.timer.step() end

		-- Call update and draw
		if love.update then love.update(dt) end -- will pass 0 if love.timer is disabled

		if love.graphics and love.graphics.isActive() then
			love.graphics.origin()
			love.graphics.clear(love.graphics.getBackgroundColor())

			if love.draw then love.draw() end

			love.graphics.present()
		end

		if love.timer then love.timer.sleep(0.001) end
	end
end
```

可以参见 [love.run - LOVE (love2d.org)](https://love2d.org/wiki/love.run)

### 任务目标

做一款现代俄罗斯方块，具有以下特点：

- 配色：每个方块的颜色有要求
- 延迟锁定：方块接触到地面后，不会立刻锁定
- 旋转系统：根据踢墙表，存在踢墙情况
- 出块系统：使用 `7-Bag` 而不是纯随机的出块方式

在写代码时，学习参考了 MrZ 大佬的代码 [tetris-in-100-lines](https://github.com/MrZ626/tetris-in-100-lines)

### 实现

以下是我的代码，还没写完（小声）：[Tetris](https://github.com/ZerolAcqua/Tetris)

#### 场地参考

场地的话，计划使用 10×40 的场地，其中正常游戏只使用 10×20，剩下 10×20 用于存储顶出显示场地的方块。通过建立一个以场地为参考的坐标描述，我们可以描述方块的位置信息，并将游戏逻辑与绘图的逻辑分开。

实现起来，主要是通过一个二维数组记录 10*40 场地的情况。其中，每格不同的数值代表不同的方块。目前，`0` 代表无方块，`1~7` 代表七种方块。这样，以后既可以拓展格子的类型，又可以绘制彩色的场地。

从数据结构的角度，先消除在线性表靠后数据，再消除在线性表靠前的数据，操作要更方便一些。因此，消行的顺序就很关键。

#### 方块表达

方块，以及方块与其他要素的交互是最麻烦的一部分。

方块表达时，采用以下的方式。

![各方块的边界框](https://tetris.wiki/images/3/3d/SRS-pieces.png)

方块的边界框是包含四个方向形状的外接矩形。除了 `I` 和 `O` 的边界框是 4×4 和 2×2 以外，其他方块的边界框是 3×3 ，若要确定每个 `mino` 的位置，需要知道此刻边界框的位置和方块的朝向。在我们这次的编写中，我们通过边界框左上角的场地坐标，确定方块的位置。此外，在方块新生成的时候， `I` 和 `O` 是居中的，而其他方块是偏左的，它们的边界框左上角坐标也不相同。这些生成时的初始坐标，记录在一个表中。

```lua
-- 方块活动框左上角坐标 (x,y)
local initPos={
	{4,22},		-- I
	{4,22},		-- J
	{4,22},		-- L
	{5,22},		-- O
	{4,22},		-- S
	{4,22},		-- Z
	{4,22}		-- T
}
```

为了表示各个方向下的方块形状，也采用了表结构存储，在已知方块类型和方块朝向后，就能立刻获取其形状。

```lua
-- 记录的各方向的方块形状(从下往上)：1-原位(0) 2-顺时针位(R) 3-180度位(2) 4-逆时针位(L)
local blocks={
	-- I
	{
		{{0,0,0,0},{0,0,0,0},{1,1,1,1},{0,0,0,0}},		--I1
		{{0,0,1,0},{0,0,1,0},{0,0,1,0},{0,0,1,0}},		--I2
		{{0,0,0,0},{1,1,1,1},{0,0,0,0},{0,0,0,0}},		--I3
		{{0,1,0,0},{0,1,0,0},{0,1,0,0},{0,1,0,0}}		--I4
	},	
	-- J
	{
		{{0,0,0},{1,1,1},{1,0,0}},						--J1
		{{0,1,0},{0,1,0},{0,1,1}},						--J2
		{{0,0,1},{1,1,1},{0,0,0}},						--J3
		{{1,1,0},{0,1,0},{0,1,0}}						--J4
	},		
	-- L
	{
		{{0,0,0},{1,1,1},{0,0,1}},						--L1
		{{0,1,1},{0,1,0},{0,1,0}},						--L2
		{{1,0,0},{1,1,1},{0,0,0}},						--L3
		{{0,1,0},{0,1,0},{1,1,0}}						--L4
	},
	-- O	
	{
		{{1,1},{1,1}},									--O1
		{{1,1},{1,1}},									--O2
		{{1,1},{1,1}},									--O3
		{{1,1},{1,1}}									--O4
	},
	-- S
	{
		{{0,0,0},{1,1,0},{0,1,1}},						--S1
		{{0,0,1},{0,1,1},{0,1,0}},						--S2
		{{1,1,0},{0,1,1},{0,0,0}},						--S3
		{{0,1,0},{1,1,0},{1,0,0}}						--S4
	},		
	-- Z
	{
		{{0,0,0},{0,1,1},{1,1,0}},						--Z1
		{{0,1,0},{0,1,1},{0,0,1}},						--Z2
		{{0,1,1},{1,1,0},{0,0,0}},						--Z3
		{{1,0,0},{1,1,0},{0,1,0}}						--Z4
	},
	-- T
	{
		{{0,0,0},{1,1,1},{0,1,0}},						--T1
		{{0,1,0},{0,1,1},{0,1,0}},						--T2
		{{0,1,0},{1,1,1},{0,0,0}},						--T3
		{{0,1,0},{1,1,0},{0,1,0}}						--T4
	}
}
```

在后面的实现中，还使用了不少的表，比如行状态表、列状态表、颜色表、踢墙表等等。

#### 方块碰撞

这点是最复杂的地方，而且牵扯到踢墙的概念。

由于每个方块的边界框{% emp 并不与某一方向时方块的最小外接矩形重合 %}，方块与场地边界的碰撞检测就稍显麻烦。不对边界框中完全没有 `mino` 的行或列进行特殊处理的话，就可能造成（场地下边界或场地左右边界）数组越界或是方块悬空的状况。因此，根据方块的形状表，我计算了对应的行状态与列状态表（遇事不决就打表）。在此基础上，可以实现一个判断方块是否超出场地，与场地内方块重叠的函数。通过该函数，我们可以做到判断方块是否落地（落地了就要计时，准备延迟锁定了）。通过该函数，我们可以判断踢墙的结果是否可行。

踢墙的概念这里不再多说。有踢墙表之后，只需要按顺序进行平移的尝试，成功则采用，不成功则方块不能旋转。

#### 延迟锁定

目前我只做了延迟锁定，其表现为：

- 非落地状态下，不进行延迟锁定计时。
- 落地状态下，移动或旋转后变为非落地状态后，不进行延迟锁定计时。
- 落地状态下不会立即锁定，而是保留一段继续操作的时间。
- 不进行移动或旋转，在设定的时间（锁定延迟）过后，方块锁定。
- 落地状态下无法移动（左右卡住），或无法旋转（踢墙表检测全部失败）时，视作未进行操作。注意 `O` 的旋转虽然看起来没有变化，但它是确确实实成功旋转了的，所以会刷新锁定延迟。

同时，需要注意，为了避免无限刷新锁定延迟的情况，应该增加一个操作次数限制：

- 非落地状态下，不计入操作次数限制。
- 落地状态下，一次移动或旋转后，计一次操作次数。
- 落地状态下无法移动（左右卡住），或无法旋转（踢墙表检测全部失败）时，视作未进行操作，不计入操作次数限制。注意 `O` 的旋转虽然看起来没有变化，但它是确确实实成功旋转了的，所以会计一次操作次数。
- 当操作次数用尽后，移动和旋转将不再刷新锁定延迟。

今天（2022.8.23）我实现操作次数的时候，发现还有一个问题：

- 如果操作次数用尽后，踢墙产生的偏移不能向上。

 这个规定的意义在于，避免玩家通过踢墙将方块“抬高”，然后方块下落，刷新延迟锁定，导致无限操作而不锁定的问题。

#### 出块序列

实际上就是一个队列，当队列短于设定的数量时。按选定的随机生成器，生成一段新序列加到队尾。

如果是 `bag` 出块，则保证要添加的新序列中每种方块各出现一次

#### 暂存

暂存的实现思路很简单，就是记录下暂存的方块 id 和暂存的操作次数限制而已。但是在这个过程中，我意识到关于暂存计数、锁延计数的重置时机问题。

根据游戏逻辑，在暂存之后，更换的方块会重新从场地顶部开始下落，并且方块的锁延计数会重置。暂存计数就是为了避免玩家通过无限的暂存，重置锁延计数的情况。所以暂存之后，锁延计数会重置，暂存计数 `-1`。而暂存计数重置的时机，应当是一个方块成功锁定后，这是毫无疑问的。

可是，锁延计数是什么时候重置呢？在没有暂存功能的情况下，锁延计数在方块成功锁定后，或者新生成方块时重置都是没有问题的。但是引入了暂存功能后，暂存方块会导致方块的锁延计数重置。因此，如果将锁延计数在方块成功锁定后重置，会导致暂存后新方块的锁延计数未重置。所以锁延计数应当在生成方块时更新。

换个角度想想，暂存后的方块，本质就是新生成了一个方块，这和方块锁定后新生成方块的原理应当一致。而锁延计数会在方块锁定后和暂存后重置，因此在生成方块时重置锁延计数能很好地解决这两种情况。

此外，在暂存中无方块和暂存中有方块时，对序列的处理有一定的区别。前者是将当前块暂存，从序列中新取一块作为当前块；后者是将当前块与暂存块交换。

### 发布

#### 创建 .love 文件

将游戏文件变为 `.exe` 文件的步骤比较简单：

- 将游戏文件加入 `.zip` 压缩文件中
- 将后缀更改为`.love`

此文件就可以通过以下方式运行：

```shell
love xxx.love
```

#### 针对 windows 平台构建

- 将 `love.exe` 与 `.zip` 文件合并为一个 `.exe` 文件
- 将 `.dll` 文件、许可 `license.txt` 和 合并得到的 `.exe` 文件放在同一个目录下，即可运行游戏

#### 网页发布

推荐使用 [Davidobot/love.js](https://github.com/Davidobot/love.js)，该作者目前还保持着更新，适用于 `11.4` 版本

通过以下方式安装：

```shell
npm i love.js
```

或

```shell
npm -g i love.js
```

然后构建兼容版本：

```shell
love.js game.love game -c
```

如果命令无法正常执行（比如说，打开了 `love.js` 文件），则可以使用以下命令：

```shell
love.js.cmd game.love game -c
```

即可完成构建。该命令会在当前目录生成一个文件夹：

```shell
Tetris
│ game.data
│ game.js
│ index.html
│ love.js
│ love.wasm
│
└─theme
 bg.png
 love.css
```

其中，`game.data` 和 `game.js` 是游戏的生成文件， `index.html` 就是生成的网页，而 `theme` 目录下的文件是页面的美化相关的文件。`love.js` 和 `love.wasm` 是 `love` 框架对应的文件。

:::info{title="相关信息"}
游戏基本上完成了，剩下的东西主要是美化辅助和提升操作手感的方面（阴影和 DAS ），大概率不会更新了……想体验戳[这里](https://vanblog.zerolacqua.top/c/tetris)
:::

各种发布方式（包括网页发布）具体可以请参考：[Game Distribution - LOVE (love2d.org)](https://love2d.org/wiki/Game_Distribution)

Lua 学习记录

虽然我已经大三了，但是面对夏令营随时可能犯病的编程要求，我还是要准备一下文件读取的。毕竟文件读写还是挺重要的，而编程题目里的文件格式乱七八糟的，不清楚是否允许使用 C++ 的读写方式，所以做一做总结吧。





## 打开关闭文件

### C 语言风格

使用 C 标准库 `stdio.h`

```c
FILE *fopen(const char *filename, const char *mode);
```

| 模式 | 描述 |
| ---- | ------------------------------------------------------------ |
| r | 打开一个已有的文本文件，允许读取文件。 |
| w | 打开一个文本文件，允许写入文件。如果文件不存在，则会创建一个新文件。在这里，您的程序会从文件的开头写入内容。如果文件存在，则该会被截断为零长度，重新写入。 |
| a | 打开一个文本文件，以追加模式写入文件。如果文件不存在，则会创建一个新文件。在这里，您的程序会在已有的文件内容中追加内容。 |
| r+ | 打开一个文本文件，允许读写文件。 |
| w+ | 打开一个文本文件，允许读写文件。如果文件已存在，则文件会被截断为零长度，如果文件不存在，则会创建一个新文件。 |
| a+ | 打开一个文本文件，允许读写文件。如果文件不存在，则会创建一个新文件。读取会从文件的开头开始，写入则只能是追加模式。 |

如果处理的是二进制文件，则需使用下面的访问模式来取代上面的访问模式：

```
"rb", "wb", "ab", "rb+", "r+b", "wb+", "w+b", "ab+", "a+b"
```

如果需要关闭文件，使用 `fclose()` 函数：

```c
 int fclose(FILE *fp);
```

如果成功关闭文件，`fclose()` 函数返回零，如果关闭文件时发生错误，函数返回 `EOF`。这个函数实际上，会清空缓冲区中的数据，关闭文件，并释放用于该文件的所有内存。`EOF` 是一个定义在头文件 `stdio.h` 中的常量。

C 标准库提供了各种函数来按字符或者以固定长度字符串的形式读写文件。

### C++ 风格

使用 C++ 标准库 `fstream`，它定义了三个新的数据类型：

| 数据类型 | 描述 |
| -------- | ------------------------------------------------------------ |
| ofstream | 该数据类型表示输出文件流，用于创建文件并向文件写入信息。 |
| ifstream | 该数据类型表示输入文件流，用于从文件读取信息。 |
| fstream | 该数据类型通常表示文件流，且同时具有 `ofstream` 和 `ifstream` 两种功能，这意味着它可以创建文件，向文件写入信息，从文件读取信息。 |

要在 C++ 中进行文件处理，必须在 C++ 源代码文件中包含头文件 `<iostream>` 和 `<fstream>`。

同样的，利用 `open()` 函数打开文件。

```c++
void open(const char *filename, ios::openmode mode);
```

在这里，`open()` 成员函数的第一参数指定要打开的文件的名称和位置，第二个参数定义文件被打开的模式。

| 模式标志 | 描述 |
| :--------- | :----------------------------------------------------------- |
| ios::app | 追加模式。所有写入都追加到文件末尾。 |
| ios::ate | 文件打开后定位到文件末尾。 |
| ios::in | 打开文件用于读取。 |
| ios::out | 打开文件用于写入。 |
| ios::trunc | 如果该文件已经存在，其内容将在打开文件之前被截断，即把文件长度设为 0。 |

对于 `ifstream`，可以直接在构造函数中提供以上参数，则不需要 `open()`。

当 C++ 程序终止时，它会自动关闭刷新所有流，释放所有分配的内存，并关闭所有打开的文件。但程序员应该养成一个好习惯，在程序终止前关闭所有打开的文件。

下面是 `close()` 函数的标准语法，`close()` 函数是 `fstream`、`ifstream` 和 `ofstream` 对象的一个成员。

```c++
void close();
```

## 读取文件

### C 语言风格


```c
int fgetc(FILE * fp); // 读取单个字符
char *fgets(char *buf, int n, FILE *fp); // 读取一段字符串
int fscanf(FILE *fp, const char *format, ...) // 格式化读取
```

- `fgetc()` 函数从 `fp` 所指向的输入文件中读取一个字符。返回值是读取的字符，如果发生错误则返回 `EOF`。

- `fgets()` 函数从 `fp` 所指向的输入流中读取 `n - 1` 个字符。它会把读取的字符串复制到缓冲区 `buf`，并在最后追加一个 `null` 字符来终止字符串。

 如果这个函数在读取最后一个字符之前就遇到一个换行符 `'\n'` 或文件的末尾 `EOF`，则只会返回读取到的字符，包括换行符。当 `fget()`读取失败，如已经达到 `EOF` 时，返回 `NULL`，借此可以判断文件是否读取完成。

- `fscanf()` 函数从文件中读取字符串，但是在遇到第一个空格和换行符时，它会停止读取。如果成功，该函数返回成功匹配和赋值的个数。如果到达文件末尾或发生读错误，则返回 `EOF`。`format` 的格式请见 [C 库函数 – fscanf() | 菜鸟教程 (runoob.com)](https://www.runoob.com/cprogramming/c-function-fscanf.html)

 > 也就是说，如果使用类似 `%*d` 的方式忽视了匹配的内容，则不会计入返回的成功匹配和赋值计数中。

- `fread()`函数用于读取二进制文件。

- 如果想再从头开始读取，使用以下函数：

 ```c
 void rewind(FILE *stream)
 ```

读取文件时需要注意这两个代码的差异

```c
/* --- data.txt --- 
3
3N,1E,1N,3E,2S,1W
*/
FILE* infile = fopen("data.txt", "r");
int i = 0;
char c1 = 0;
fscanf(infile, "%d", &i); // 这里没有空格
fscanf(infile, "%c", &c1); // c1='\n'
```

```c
FILE* infile = fopen("data.txt", "r");
int i = 0;
char c1 = 0;
fscanf(infile, "%d ", &i);// 这里有空格
fscanf(infile, "%c", &c1); // c1='3'
```

### C++ 风格

```c++
infile >> tmp;
std::istream &getline(char* _Str, std::streamsize _count);
```

- 使用类似 `cin`的写法，利用 `>>` 运算符读取。这种方法首先跳过流中连续的空白字符（空格、换行、制表符），然后开始按变量类型读取非空白字符，中间再遇到流中的空格、换行、制表符等空白字符就会停止读取，但是它不会读入这些空白字符，所以可以连续使用进行读取。
- 类方法 `getline()` 与 C 语言中的 `fgets()` 类似。如果它读取的字符少于给定的大小 `n - 1`，或到达 `EOF` ，它会追加空字符后读入内存中。但是，它会把每行结尾的 `'\n'` 丢弃。

 - 如果是读取了 `n - 1` 个字符，还不能达到设定的分隔符，或者换行符，则 `getline()` 会设置 `failbit` 如果要继续读取，需要调用 `clear()` 进行重置。
 - 如果使用 `infile >> tmp` 读取了某一行，则行末的换行还留在文件流中，那么再使用 `getline()` 就会读入该行末尾的换行，也就是读入一个空字符串。如果要文件位置指针跳过换行，需要用 `infile.seekg(2,ios::cur)`，因为 `windows`中换行是 `\r\n` 占两个字节。

- `read()`函数用于读取二进制文件。一定要注意配合相应的打开模式！参见“关于二进制读取的重要补充说明”
 
- 判断文件是否读取完毕需要用 `eof()`方法。
 
 注意，以下写法会出现问题。

 ```c++
 /* --- data.txt --- 
 1234
 */
 fstream infile ("data.txt");
 char c = 0;
 cout << "输出结果：";
 while (!infile.eof())
 {
 infile >> c;
 cout << c;
 }
 //输出结果：12344
 ```

 原因是 `C++` 判定文件读取到 `EOF` 的时机，是尝试读取最后一个元素后面的数据时，而不是读取完最后一个数据就到了 `EOF`。所以，当 `'4'` 被读取后，还未达到 `EOF`, `!infile.eof()` 为 `true` ，还会再进入一次循环，经过一次读取后才达到 `EOF`, `!infile.eof()` 才会变为 `false`。

 - `istream` 和 `ostream` 都提供了用于重新定位文件位置指针的成员函数。这些成员函数包括关于 `istream` 的 `seekg`（"seek get"）和关于 `ostream` 的 `seekp`（"seek put"）。

 `seekg` 和 `seekp` 的参数通常是一个长整型。第二个参数可以用于指定查找方向。查找方向可以是 `ios::beg`（默认的，从流的开头开始定位），也可以是 `ios::cur`（从流的当前位置开始定位），也可以是 `ios::end`（从流的末尾开始定位）。

 文件位置指针是一个整数值，指定了从文件的起始位置到指针所在位置的字节数。

 ```c++
 // 定位到 fileObject 的第 n 个字节（假设是 ios::beg）
 fileObject.seekg(n);

 // 把文件的读指针从 fileObject 当前位置向后移 n 个字节
 fileObject.seekg(n,ios::cur);

 // 把文件的读指针从 fileObject 末尾往回移 n 个字节
 fileObject.seekg(n,ios::end);

 // 定位到 fileObject 的末尾
 fileObject.seekg(0,ios::end);
 ```


## 写入文件

### C 语言风格


```c++
int fgetc( FILE * fp );
char *fgets( char *buf, int n, FILE *fp );
int fprintf(FILE *fp,const char *format, ...) 
```

- 函数 `fputc()` 把参数 `c` 的字符值写入到 `fp` 所指向的输出流中。如果写入成功，它会返回写入的字符，如果发生错误，则会返回 `EOF`。
- 函数 `fputs()` 把字符串 `s` 写入到 `fp` 所指向的输出流中。如果写入成功，它会返回一个非负值，如果发生错误，则会返回 `EOF`。
- 函数 `fprintf()` 把一个字符串写入到文件中。
- 函数 `fwrite()`用于写入二进制文件

### C++ 风格

- 使用类似 `cout`的写法，利用 `<<` 运算符写入。

```c++
outfile << tmp;
```

 写入的格式与 `cout` 的写法相同。需要包含 `<iomanip>`。

 > 注意：“流操纵算子”一栏中的星号`*`不是算子的一部分，星号表示在没有使用任何算子的情况下，就等效于使用了该算子。例如，在默认情况下，整数是用十进制形式输出的，等效于使用了 dec 算子。



<table>
<tr>
<th>
流操纵算子</th>
<th colspan="2">
作 &nbsp;用</th>
</tr>
<tr>
<td>
*dec</td>
<td>
以十进制形式输出整数</td>
<td rowspan="13">
常用</td>
</tr>
<tr>
<td>
hex</td>
<td>
以十六进制形式输出整数</td>
</tr>
<tr>
<td>
oct</td>
<td>
以八进制形式输出整数</td>
</tr>
<tr>
<td>
fixed</td>
<td>
以普通小数形式输出浮点数</td>
</tr>
<tr>
<td>
scientific</td>
<td>
以科学计数法形式输出浮点数</td>
</tr>
<tr>
<td>
left</td>
<td>
左对齐，即在宽度不足时将填充字符添加到右边</td>
</tr>
<tr>
<td>
*right</td>
<td>
右对齐，即在宽度不足时将填充字符添加到左边</td>
</tr>
<tr>
<td>
setbase(b)</td>
<td>
设置输出整数时的进制，b=8、10 或 16</td>
</tr>
<tr>
<td>
setw(w)</td>
<td>
指定输出宽度为 w 个字符，或输入字符串时读入 w 个字符</td>
</tr>
<tr>
<td>
setfill(c)</td>
<td>
在指定输出宽度的情况下，输出的宽度不足时用字符 c 填充（默认情况是用空格填充）</td>
</tr>
<tr>
<td>
setprecision(n)</td>
<td>
设置输出浮点数的精度为 n。 
 
在使用非 fixed 且非 scientific&nbsp;方式输出的情况下，n 即为有效数字最多的位数，如果有效数字位数超过 n，则小数部分四舍五人，或自动变为科学计数法输出并保留一共 n 位有效数字。 
 
在使用 fixed 方式和 scientific 方式输出的情况下，n 是小数点后面应保留的位数。</td>
</tr>
<tr>
<td>
setiosflags(flag)</td>
<td>
将某个输出格式标志置为 1</td>
</tr>
<tr>
<td>
resetiosflags(flag)</td>
<td>
将某个输出格式标志置为 0</td>
</tr>
<tr>
<td>
boolapha</td>
<td>
把 true 和 false 输出为字符串</td>
<td rowspan="13">
不常用</td>
</tr>
<tr>
<td>
*noboolalpha</td>
<td>
把 true 和 false 输出为 0、1</td>
</tr>
<tr>
<td>
showbase</td>
<td>
输出表示数值的进制的前缀</td>
</tr>
<tr>
<td>
*noshowbase</td>
<td>
不输出表示数值的进制.的前缀</td>
</tr>
<tr>
<td>
showpoint</td>
<td>
总是输出小数点</td>
</tr>
<tr>
<td>
*noshowpoint</td>
<td>
只有当小数部分存在时才显示小数点</td>
</tr>
<tr>
<td>
showpos</td>
<td>
在非负数值中显示 +</td>
</tr>
<tr>
<td>
*noshowpos</td>
<td>
在非负数值中不显示 +</td>
</tr>
<tr>
<td>
*skipws</td>
<td>
输入时跳过空白字符</td>
</tr>
<tr>
<td>
noskipws</td>
<td>
输入时不跳过空白字符</td>
</tr>
<tr>
<td>
uppercase</td>
<td>
十六进制数中使用 A~E。若输出前缀，则前缀输出&nbsp;0X，科学计数法中输出 E</td>
</tr>
<tr>
<td>
*nouppercase</td>
<td>
十六进制数中使用 a~e。若输出前缀，则前缀输出 0x，科学计数法中输出 e。</td>
</tr>
<tr>
<td>
internal</td>
<td>
数值的符号（正负号）在指定宽度内左对齐，数值右对 齐，中间由填充字符填充。</td>
</tr>
</table>



- 函数 `write()`用于写入二进制文件


## 关于二进制读取的重要补充说明

:::warning{title="注意"}
看我看我一定要看我！
:::

这部分内容是在夏令营之后添加的。我其实根本想不到题目居然会出二进制文件的读取，二进制文件读取我也没认真准备。这和前两年的题目风格完全不一样啊！

### 起因

在夏令营机试的时候，使用 C++ 风格的二进制文件读取 `infile.read()` 只成功读入了 42 个正确数据，之后就到了 `EOF`。其中 `fval.dat` 是存储了512*512个 `float` 数据的。

```c++
fstream infile1 ("fval.dat",ios::in);
float* f1 = new float[512 * 512];
infile1.read((char*)f1, 512 * 512 * sizeof(float));
infile1.close();
```

我 Debug 了半个小时还没有读进去，当时就慌了，心一狠，换了 C 语言风格的二进制文件读取，然后就成功读取了全部的数据。

```c
FILE* infile2 = fopen("fval.dat", "rb");
float* f2 = new float[512 * 512];
fread(f2, sizeof(float), 512 * 512, infile2);
fclose(infile2);
```

你发现什么问题了吗？

### 经过

夏令营之后，我查找了 c++ 文件读写出错的问题，最后在同学的指点下，意识到一个自己从来没注意但很严重的问题。由于我从来没有用 C++ 进行二进制文件读写过，所以我对 `ios::binary` 没有太多的印象。而之前提及的表格中，也少了一个用于打开二进制文件的 `ios::binary`

| 模式标志 | 描述 |
| :--------- | :----------------------------------------------------------- |
| ios::app | 追加模式。所有写入都追加到文件末尾。 |
| ios::ate | 文件打开后定位到文件末尾。 |
| ios::in | 打开文件用于读取。 |
| ios::out | 打开文件用于写入。 |
| ios::trunc | 如果该文件已经存在，其内容将在打开文件之前被截断，即把文件长度设为 0。 |

不使用 `ios::binary` 虽然在原理上也能进行读取。但是，如果不使用二进制模式，对于某些情况，存在转换的情况。在本次的数据（二进制）中

```
C7 91 1C C0 10 67 1b C0 47 3B 1A C0 6E 0E 19 C0
```

前8个字节能正常读取数据，`float` 占4个字节，因此成功读取了两个 `float` 数值。但是在读取第三个 `float` 数据时， `1A` 对应的是 `SUB`，或者说是 `^Z`。因此会导致文件读取提前结束。当我们把 `1A` 换成 `3B` 等不会被转换的字节时，读取就不会提前结束。

### 结论

- 二进制文件就好好用二进制模式读取。
- 二进制模式下，不会存在特殊字符的转换问题。

## 参考网页

- [C 文件读写 | 菜鸟教程 (runoob.com)](https://www.runoob.com/cprogramming/c-file-io.html)

- [C++ 文件和流 | 菜鸟教程 (runoob.com)](https://www.runoob.com/cplusplus/cpp-files-streams.html)

- [C++ cout格式化输出（输出格式）完全攻略 (biancheng.net)](http://c.biancheng.net/view/275.html)