dfhack_remote

dfhack_remote是一个库，允许用户通过远程API与Dwarf Fortress交互。

Dwarf Fortress是由Bay 12 Games开发的一款视频游戏。DFHack是Dwarf Fortress的一个粉丝mod，为游戏添加了许多功能。其中之一是一个远程API，允许远程控制某些Dwarf Fortress功能。这个crates是这个远程API的客户端，允许Rust工具开发者与Dwarf Fortress交互。

示例

显示有关当前世界的某些信息。

let mut client = dfhack_remote::connect().unwrap();
let world_info = client.core().get_world_info().unwrap();

println!(
    "Welcome to {} ({})",
    world_info.world_name.last_name(),
    world_info.world_name.english_name()
);

暂停或恢复游戏

let mut client = dfhack_remote::connect().unwrap();
let status = client.remote_fortress_reader().get_pause_state().unwrap();
client.remote_fortress_reader().set_pause_state(!status).unwrap();

生成的API主要是直接从原始RPC翻译过来的，因此相当冗长。

它包含一些小的语法糖，例如省略EmptyMessage输入。

DFHack API

DFHack 远程API依赖于protobuf进行消息序列化。这意味着每个消息的输入和输出都依赖于protobuf代码生成来创建类型安全的体验。

dfhack_remote使用crates protobuf 和 protobuf-codegen-pure 进行protobuf代码生成。

然而，DFHack不使用gRPC来表示远程调用，而使用特定的协议。DFHack的RPC定义通过在.proto文件中插入注释来描述。为了绑定所有RPC，这个crates直接从DFHack源代码生成所有的API入口点。

为不同的DFHack版本构建

用于代码生成的DFHack源可以通过构建时的DFHACK_ZIP_URL环境变量来控制。例如，在构建时将此环境变量设置为https://github.com/DFHack/dfhack/archive/refs/heads/develop.zip将针对DFHack中包含的最新更改。

为了触发下载和源代码再生，DFHACK_REGEN和DFHACK_DOWNLOAD也必须设置为1。

crate结构

此crate的主入口点是[connect]函数。

代码分为三个crate

• dfhack_proto_srcs在构建时下载并提取DFHack源代码中的proto。
• dfhack_proto构建包含RPC的protobuf消息和插件结构
• dfhack_remote是主入口点。它实现了实际协议并公开了功能。

为了便于使用，dfhack_remote重新导出dfhack_proto中生成的所有代码。

内部，message模块处理在protobuf之上运行的序列化/反序列化逻辑，而channel模块处理交换流程。

测试

大多数测试都需要与Dwarf Fortress通信的能力。可以通过将环境变量DF_EXE设置为Dwarf Fortress的可执行文件来启用此功能。设置完成后，可以启用test-with-df功能来运行这些测试

cargo test --features test-with-df

这将运行此Dwarf Fortress安装的第一个存档。您应该为此目的准备一个带有口袋世界的专用存档。

发布

版本控制是通过cargo release完成的。使用cargo release --workspace --execute发布当前版本并切换到下一个修补程序，或者cargo release [level] --workspace --execute（次要、主要）。