Godot Rust Helper

一个简单的命令行工具，帮助您创建和更新Godot项目的Rust组件。

安装

$ cargo install godot_rust_helper

升级

$ cargo install --force godot_rust_helper

注意：此文档适用于4.x和5.x版本。其他版本的文档可以在下面找到

• 3.x
• 2.x
• 1.x

目录

• 完整示例
• 命令
  • new
  • 创建
  • 销毁
  • 构建
  • 插件
  • 更新
  • rebase

完整示例

以下是设置Rust与Godot项目从开始到结束的基本指南。

步骤1：创建项目的库

在Godot中创建每个游戏时，您都需要创建一个新的库。库本身是一个cargo库，它包含游戏中使用的所有组件。

要创建项目的库，导航到您希望存储组件的位置（在Godot项目目录外），并使用new命令

$ godot_rust_helper new <destination> <path_to_godot_project> [options]

让我们通过一些示例详细说明参数和选项。

参数

• library_name 包含您的Rust组件的库的名称。建议库的名称与您的游戏名称相同或相似。此外，请注意，库是用cargo new创建的，因此您应遵守cargo项目命名标准。
• path_to_godot_project 这是组件所属的Godot项目的根目录路径。

选项

• --targets Godot 中的本地组件可以针对多个平台，而 godot_rust_helper 需要提前知道您打算为哪些平台创建组件，目前可用的选项有：Windows、Linux 和 OS X。例如，如果您针对 Windows 和 OS X，则需要将 cargo 设置为构建 dll 和 dylib 文件，并且您将使用 --targets=windows,osx 作为目标。默认情况下，如果没有传递任何目标，则仅设置 --targets=windows。
• --output-path godot_rust_helper 必须将 gdnlib 文件和构建文件放置在游戏目录中。默认情况下，这些文件放置在游戏目录的根目录下，但您可以使用此选项指定一个目录，将这些文件放在游戏中（无论是否存在）。
• --nativescript-path 所有本地脚本文件将输出的 Godot 项目路径。默认情况下，本地脚本文件放置在 Godot 项目的根目录。

示例

仅针对 Windows 构建创建默认库

$ godot_rust_helper new breakout_components ~/Documents/projects/breakout

为 Windows、Linux 和 OS X 构建创建库

$ godot_rust_helper new breakout_components ~/Documents/projects/breakout --targets=windows,linux,osx

创建库并将文件输出到 build-output

$ godot_rust_helper new breakout_components ~/Documents/projects/breakout --output-path ~/Documents/projects/breakout/build-output

创建库并将本地脚本文件输出到 scripts

$ godot_rust_helper new breakout_components ~/Documents/projects/breakout --nativescript-path ~/Documents/projects/breakout/scripts

注意： src/lib.rs 文件完全由 godot_rust_helper 管理，不应进行修改。对文件的任何修改都可能导致组件无法正常工作，或者当创建/销毁模块时将被覆盖。自定义修改（即将推出）可以添加到该文件中。

注意： 每个库实例都包含 godot_rust_helper_extensions 作为依赖项，它将包含使某些事情更简单的方法（例如获取类型化节点）以及包含 gdnative 但不在 gdscript 中的方法。如果您不想使用任何扩展，则不必使用它们；但如果您对它们感兴趣，请查看这里的扩展。

如果您收到一个错误消息，说 crate 不存在，那是因为扩展名的名称第一次设置不正确，并且在 1.0.2 中已修复。要修复它，您可以更新并重新创建库，或者简单地去到您的 Cargo.toml 并将 godot_rust_helper_extensions 更改为 godot_rust_helper_ext。

步骤 2：创建组件

现在您已创建了库，您可以去新创建的文件夹中查看配置文件。此配置文件包含 Godot 项目目录的路径以及从 new 命令传递的目标。此配置文件不应手动修改，因为 godot_rust_helper 严重依赖它。

从该目录开始，我们可以现在开始使用创建命令创建组件，如下所示

$ godot_rust_helper create <class_name>

• 名称 传递给此命令的名称应该是组件的类名。类名必须以大写字母开头。例如，包括 'Player'、'Princess'、'Mob'、'HUD' 等。

这会为组件创建一个 src/<name>.rs 文件，并在 src/lib.rs 文件中添加一个条目。如果你将此组件直接附加到节点并运行游戏，"hello, world" 将会输出到 Godot 控制台。这还会在创建库时指定的位置创建一个 <name>.gdns 文件。这是你将附加到 Godot 中节点的脚本。

注意：此命令必须在库目录中运行。

示例

$ godot_rust_helper create Player

$ godot_rust_helper create MainScene

步骤 3：构建库

创建组件后（或者你可以使用默认内容进行测试），你就可以使用以下命令运行构建：

$ godot_rust_helper build

这首先会运行 cargo build，然后将构建文件移动到 Godot 项目目录。

注意：此命令必须在库目录中运行。

注意：第一次运行此命令时需要一些时间，因为它需要下载必要的依赖项，之后的每次构建都会快得多。

构建命令还支持 --watch 选项，它将监视组件的 src 目录中的更改，并自动重新构建。

示例

运行构建命令

$ godot_rust_helper build

运行构建命令并监视库中任何组件的更改。

$ godot_rust_helper build --watch

步骤 4：在 Godot 中使用组件

最后一步是将脚本附加到 Godot 中的节点

1. 选择要添加组件的节点，然后在检查器中转到脚本下拉菜单并选择加载。
2. 在根目录或创建库时指定的 --nativescript-path 目录中找到要加载的脚本并选择它。

现在，如果你运行游戏，你会看到你的组件功能正在运行！

注意：如果你更新了 Rust 组件并运行了构建，你不需要在 Godot 中更新相应的 .gdnlib 文件，它将自动更新。

注意：你不需要将 .gdns 脚本放在任何特定位置，所以请随意移动它们。只要不移动 gdnlib 和动态库文件，nativescript 文件就可以放在 Godot 项目的任何位置。

命令

new

为你的 Rust 脚本创建一个新的库，该库连接到 Godot 项目。

Usage: godot_rust_helper new <destination> <godot-project> [options]

destination:                    The destination directory for the library. Note that libraries are created using cargo so you should adhere to cargo naming guidelines and use underscores for multiple words.
godot-project:                  The directory of the Godot project that this library contains the Rust scripts for.

Options:
-t, --targets <targets>         A string of comma separated targets of the platforms you would like to build the project for. Currently the available options are windows, linux, and osx with a default value of just windows.
-o, --output-path <path>        The path within the Godot project where the gdnlib and dynamic libraries will get output to. By default these files will be output to the root of the Godot project.
-n, --nativescript-path <path>  The path within the Godot project where the gdns files will be output to. By default these files will be output to the root of the Godot project.

示例

仅针对 Windows 构建创建默认库

$ godot_rust_helper new breakout_components ~/Documents/projects/breakout

为 Windows、Linux 和 OS X 构建创建库

$ godot_rust_helper new breakout_components ~/Documents/projects/breakout --targets=windows,linux,osx

创建库并将文件输出到 build-output

$ godot_rust_helper new breakout_components ~/Documents/projects/breakout --output-path ~/Documents/projects/breakout/build-output

创建库并将本地脚本文件输出到 scripts

$ godot_rust_helper new breakout_components ~/Documents/projects/breakout --nativescript-path ~/Documents/projects/breakout/scripts

创建

在 Godot 项目中创建一个 Rust 脚本和一个相应的 gdns 文件，当构建时可以放置在节点上。

Usage: godot_rust_helper create <class-name>

class-name  The name passed to this command should be the class name of the component. Class names must start with capital letters. Examples include 'Player', 'Princess', 'Mob', 'HUD', etc.

示例

$ godot_rust_helper create Player

$ godot_rust_helper create MainScene

销毁

删除使用 create 创建的脚本的全部痕迹。

Usage: godot_rust_helper destroy <class-name>

class-name The name of the class to destroy. This should be the same name that was used when it was created with `godot_rust_helper create`.

示例

$ godot_rust_helper destroy Player

$ godot_rust_helper destroy MainScene

构建

构建项目以生成动态库，然后将它们复制到 Godot 项目的 output-path 目录。

Usage: godot_rust_helper build [options]

Options:
-w,--watch  Watches the src directory of the library for changes and runs the build command automatically.

示例

$ godot_rust_helper build

$ godot_rust_helper build --watch

插件

创建一个用作插件的库。这创建了插件的目录结构（addons/plugin-name），还创建了插件配置文件和基本插件脚本。

Usage: godot_rust_helper plugin <name> <destination> <godot-project> [options]

name                           The name of the plugin. If the plugin consists of more than 1 word then it needs to be in quotes.
destination                    The destination directory for the library. Note that libraries are created using cargo so you should adhere to cargo naming guidelines and use underscores for multiple words.
godot-project                  The directory of the Godot project that this library contains the Rust scripts for.

Options:
-t, --targets <targets>         A string of comma separated targets of the platforms you would like to build the project for. Currently the available options are windows, linux, and osx with a default value of just windows.
-a, --author <author>           The author of the plugin.
-d, --description <description> The description of the plugin.
-v, --version <version>         The initial version of the plugin. If no version is provided then "1.0" will be used.

示例

$ godot_rust_helper plugin "Directory Browser" directory_browser ../path/to/godot/game --description "Helps you map out your game's file structure" --author "Bob"

更新

将项目从使用较旧的 godot_rust_helper 版本更新到使用最新的 godot_rust_helper 版本。

必须在此要更新的项目内部使用此命令。

注意：在 4.x 版本中，gdns 文件现在以蛇形命名而不是 Pascal 命名。更新命令会更新你的现有 gdns 文件名，因为这会在 Godot 项目中引起很多问题，所以你可以保留它们不变或手动更新它们。

Usage: godot_rust_helper update [options]

Options:
output-path       Since version 2.x, godot_rust_rust doesn't create a rust-modules folder you can specify this to change the location where the gdnlib and dynamic libraries reside. If left blank, the rust-modules folder will be used by default.
nativescript-path Since version 3.x, godot_rust_helper lets you spcify the directory where your .gdns files get output to.

示例

保留 rust-modules 文件夹（如果你是从 1.x 或 2.x 更新到最新版）

$ godot_rust_helper update

将输出文件移动到新目录

$ godot_rust_helper update --output-path /path/to/godot-project/gdr-output

指定 gdns 文件的目录

$ godot_rust_helper update --output-path /path/to/godot-project/gdr-output --nativescript-path /path/to/godot-project/gdr-scripts

注意：你可能需要运行另一个构建，并且在更新后你肯定需要将脚本重新分配给 gdnlib 文件。

rebase

rebase命令非常有用，如果你导入他人的godot_rust_helper项目并想对其进行本地修改时。

此命令允许你更改godot项目位置和目标。

必须在该rebase项目的内部使用此命令。

Usage: godot_rust_helper rebase <new-godot-path> [options]

new-godot-path The path to where the Godot project that this library is for is on your file system.

Options:
targets The new build targets for the project, this should be used like it is in the `new` command.

示例

$ godot_rust_helper rebase ../path/to/game

$ godot_rust_helper rebase ../path/to/game --targets=linux,osx

测试

确保你处于godot_rust_helper的根目录中，然后运行

$ cargo test -- --test-threads=1

许可证

MIT