快速入门
捐赠 心形图标 GitHub 仓库

设置

我知道你迫不及待地想要开始制作游戏，但我们首先需要进行一些小的设置。

Rust 设置 #

所有 Bevy 应用和引擎代码都是用 Rust 编写的。这意味着在开始之前，我们需要设置 Rust 开发环境。

安装 Rust #

Bevy 极大地依赖于 Rust 语言和编译器的改进。因此，最低支持的 Rust 版本 (MSRV) 为 Rust 的“最新稳定版本”。

按照Rust 入门指南安装 Rust。

完成后，您应该在路径中安装了rustc 编译器和cargo 构建系统。

安装操作系统依赖项 #

Linux #

按照Linux 依赖项中的说明操作

Windows #
  • 运行Visual Studio 2019 构建工具安装程序
  • 为了简化设置，在安装程序中选择使用 C++ 进行桌面开发工作负载。
  • 对于最小设置，请按照以下步骤操作
    1. 在安装程序中，导航到单个组件
    2. 选择适合您的体系结构和 Windows 版本的最新MSVC
    3. 选择适合您的 Windows 版本的最新Windows SDK
    4. 选择Windows 的 C++ CMake 工具组件
    5. 安装组件

MacOS #

使用xcode-select --install或Xcode 应用安装 Xcode 命令行工具

代码编辑器/IDE #

您可以使用任何您想要的代码编辑器，但我们强烈建议使用具有rust-analyzer 插件的代码编辑器。它仍在开发中，但它已经提供了顶级自动完成和代码智能。Visual Studio Code 有一个官方支持的rust-analyzer 扩展。

Rust 学习资源 #

本指南的目标是快速开始学习 Bevy，因此它不会用作完整的 Rust 教育。如果您想详细了解 Rust 语言，请查看以下资源

  • Rust 书籍：从头开始学习 Rust 的最佳场所
  • Rust 示例：通过实况编码示例学习 Rust
  • Rustlings：通过一系列有趣且交互式的练习学习 Rust

创建新的 Bevy 项目 #

现在我们可以设置 Bevy 项目了！Bevy 只是一个普通的 Rust 依赖项。您可以将其添加到现有 Rust 项目中，也可以创建一个新的项目。为了完整起见，我们将假设您是从头开始。

创建新的 Rust 可执行文件项目 #

首先，导航到您要创建新项目的文件夹。然后，运行以下命令以创建一个包含 Rust 可执行文件项目的新文件夹

cargo new my_bevy_game
cd my_bevy_game

现在运行cargo run以构建和运行您的项目。您应该看到Hello, world!打印到您的终端。在您选择的代码编辑器中打开my_bevy_game文件夹，并花一些时间浏览这些文件。

main.rs是程序的入口点

fn main() {
    println!("Hello, world!");
}

Cargo.toml是您的“项目文件”。它包含有关您的项目（例如其名称、依赖项和构建配置）的元数据。

[package]
name = "my_bevy_game"
version = "0.1.0"
edition = "2021"

[dependencies]

将 Bevy 添加为依赖项 #

Bevy在 crates.io 上可用作库，crates.io 是官方 Rust 包存储库。

将它添加到您的项目的最佳方法是使用cargo add

cargo add bevy
备选方法 - 手动将 Bevy 添加到 Cargo.toml您也可以手动将其添加到项目的 Cargo.toml 中，如下所示
[package]
name = "my_bevy_game"
version = "0.1.0"
edition = "2021" # this needs to be 2021, or you need to set "resolver=2"

[dependencies]
bevy = "0.14" # make sure this is the latest version

确保使用最新的bevy 仓版本 (Crates.io)。

Cargo 工作区 #

如果您使用的是Cargo 工作区，您还需要将解析器添加到根目录中的 Cargo.toml 文件中

[workspace]
resolver = "2" # Important! wgpu/Bevy needs this!

使用性能优化编译 #

虽然对于简单的项目可能不是问题，但 Rust 中的调试构建可能非常慢- 尤其是在开始使用 Bevy 制作真实游戏时。

调试构建使用默认配置通常需要几分钟才能加载大型 3D 模型，或者简单场景的帧速率会降至几乎不可玩的地步。

幸运的是，有一个简单的解决方法，我们不必放弃快速迭代编译！将以下内容添加到您的Cargo.toml中

# Enable a small amount of optimization in the dev profile.
[profile.dev]
opt-level = 1

# Enable a large amount of optimization in the dev profile for dependencies.
[profile.dev.package."*"]
opt-level = 3

您可能认为只需在发布模式下进行开发即可，但我们建议不要这样做，因为这会通过减慢重新编译速度和禁用有用的调试符号和断言来恶化开发体验。

发布模式优化（可选）

实际上，您可能希望通过将以下内容添加到您的Cargo.toml中，以更多编译时间换取发布模式下的性能

# Enable more optimization in the release profile at the cost of compile time.
[profile.release]
# Compile the entire crate as one unit.
# Slows compile times, marginal improvements.
codegen-units = 1
# Do a second optimization pass over the entire program, including dependencies.
# Slows compile times, marginal improvements.
lto = "thin"

# Optimize for size in the wasm-release profile to reduce load times and bandwidth usage on web.
[profile.wasm-release]
# Default to release profile values.
inherits = "release"
# Optimize with size in mind (also try "z", sometimes it is better).
# Slightly slows compile times, great improvements to file size and runtime performance.
opt-level = "s"
# Strip all debugging information from the binary to slightly reduce file size.
strip = "debuginfo"

在为网页发布时，您可以将--profile wasm-release传递给cargo，而不是--release。

高级 Wasm 优化（可选） #

Binaryen 是一个 Wasm 编译器工具链，它提供了一个wasm-opt CLI 工具，用于使.wasm 文件更小、更快

wasm-opt -Os --output output.wasm input.wasm

请注意，wasm-opt 运行速度非常慢，但它可以产生很大的影响，尤其是在与上一节中的优化结合使用时。

有关优化 Wasm 的更多信息，请参见以下内容

启用快速编译（可选） #

Bevy 可以在稳定版 Rust 上使用默认配置很好地构建。不幸的是，编译时间相当长。本节说明如何加快迭代编译速度：更改单个文件后重建项目所需的时间。

动态链接 #

这是最显著的编译时间减少！您可以将bevy 编译为动态库，防止每次重建项目时都必须进行静态链接。您可以使用dynamic_linking 特性标志启用此功能。

cargo run --features bevy/dynamic_linking

如果您不想将--features bevy/dynamic_linking 添加到每次运行中，可以使用以下命令永久设置此标志（为您编辑Cargo.toml）

cargo add bevy -F dynamic_linking

备选链接器 #

Rust 编译器在最后的“链接”步骤中花费了大量时间，尤其是在使用像 Bevy 这样的庞大库时。lld 在链接方面比默认的 Rust 链接器快得多。要安装 LLD，请在下面找到您的操作系统并运行给定命令。

LLD 安装

  • Ubuntu: sudo apt-get install lld clang

  • Fedora: sudo dnf install lld clang

  • Arch: sudo pacman -S lld clang

  • Windows: 确保您拥有最新的cargo-binutils，因为这允许像cargo run这样的命令自动使用 LLD 链接器。

    cargo install -f cargo-binutils
rustup component add llvm-tools-preview

  • MacOS: 在 MacOS 上，默认系统链接器ld-prime 比 LLD 快。

然后，根据您的操作系统，将以下内容之一添加到您在/path/to/project/.cargo/config.toml（其中/path/to/project 是包含Cargo.toml 的目录）中的 Cargo 配置中

# for Linux
[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=lld"]

# for Windows
[target.x86_64-pc-windows-msvc]
linker = "rust-lld.exe"
备选方法 - Mold

Mold 比 LLD快 5 倍（5 倍！），但有一些注意事项，例如平台支持有限以及偶尔的稳定性问题。要安装 mold，请在下面找到您的操作系统并运行给定命令

  • Ubuntu: sudo apt-get install mold clang
  • Fedora: sudo dnf install mold clang
  • Arch: sudo pacman -S mold clang
  • Windows: 未计划支持；查看此跟踪问题以获取更多信息。
  • MacOS: 可作为sold获得，但由于默认链接器同样快，因此没有必要。

您还需要将以下内容添加到您在/path/to/project/.cargo/config.toml中的 Cargo 配置中

[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=/usr/bin/mold"]

Nightly Rust 编译器 #

这提供了对最新性能改进和“不稳定”优化的访问，包括下面提到的泛型共享。

在您的项目根目录中，在Cargo.toml旁边创建一个rust-toolchain.toml 文件。

[toolchain]
channel = "nightly"

有关更多信息，请参见Rustup 书籍：覆盖。

Cranelift #

这使用了一个新的仅限 nightly 的代码生成器，其编译速度比 LLVM 快约 30%。它目前在 Linux 上运行效果最佳。

要安装 cranelift，请运行以下命令。

rustup component add rustc-codegen-cranelift-preview --toolchain nightly

要为您的项目激活它，请将以下内容添加到您的.cargo/config.toml中。

[unstable]
codegen-backend = true

[profile.dev]
codegen-backend = "cranelift"

[profile.dev.package."*"]
codegen-backend = "llvm"

这将为您的二进制文件启用更快的编译，但使用更优化的 LLVM 后端构建 Bevy 和其他依赖项。有关启用 cranelift 的其他方法的详细信息，请参见cranelift 设置指南。Windows 的安装过程更加复杂。查阅链接的文档以获取帮助。MacOS 构建目前可能会在 Bevy 应用程序上崩溃，因此您应该在使用 cranelift 在该系统上之前等待一段时间。

虽然 cranelift 编译速度非常快，但生成的二进制文件未针对速度进行优化。此外，它通常仍不成熟，因此您可能会遇到一些问题。值得注意的是，Wasm 构建目前尚不可用。

在发布您的游戏时，您仍然应该使用 LLVM 编译它。

泛型共享 #

允许板条箱共享单态化泛型代码，而不是重复它。在某些情况下，这允许我们“预编译”泛型代码，使其不会影响迭代编译。目前，这仅在 nightly Rust 上可用（参见上面）。

泛型共享设置 #

查看 此文件 以获取更全面的跨平台示例。

# /path/to/project/.cargo/config.toml
[target.x86_64-unknown-linux-gnu]
rustflags = [
  # (Nightly) Make the current crate share its generic instantiations
  "-Zshare-generics=y",
]

提高运行时性能（可选） #

Bevy 的依赖项执行了大量对最终用户不相关的跟踪日志记录。为了提高运行时性能，您可以在 Cargo.toml 的 [dependencies] 部分添加以下内容。它将在编译时禁用详细的日志级别，以便在您的应用程序运行时不需要过滤掉它们。

log = { version = "*", features = ["max_level_debug", "release_max_level_warn"] }

构建 Bevy #

现在再次运行 cargo run。Bevy 的依赖项应该开始构建。这将需要一些时间，因为您实际上是从头开始构建引擎。您只需要进行一次完整重建。此后的每次构建都将很快！

现在我们已经设置好了 Bevy 项目，我们可以开始创建第一个 Bevy 应用程序了！

改善此页面