Bevy 的 RunCriteria、States、FixedTimestep 的可组合替代方案

该软件包提供了 Bevy 游戏引擎当前提供的 Run Criteria、States 和 FixedTimestep 调度功能的替代方案。

该软件包提供的解决方案不使用 "循环阶段"，因此可以优雅地组合在一起，解决了 Bevy 中相应 API 的一些最令人烦恼的可用性限制。

版本兼容性表

这与 Bevy 无阶段 RFC 有何关系？

该软件包受到了 Bevy 的 "无阶段 RFC" 建议的极大启发。

向所有参与该 RFC 和其中描述的设计的作者表示衷心的感谢。

我制作这个软件包，因为我相信 Bevy 中当前的 API 急需进行可用性改进。

我想出了一个方法，可以在现有 Bevy 框架内实现 Stageless RFC 中的想法，而不需要像 RFC 建议的那样彻底重写调度 API。

这样我们就可以现在就有可用性，同时剩余的无阶段工作仍在进行中。

依赖关系和 Cargo 功能标志

"运行条件" 功能始终启用，仅依赖于 bevy_ecs。

"固定时间步长" 功能是可选的（"fixedtimestep" cargo 功能）并添加以下依赖项

• bevy_time
• bevy_utils

"状态" 功能是可选的（"states" cargo 功能）并添加以下依赖项

• bevy_utils

"app" cargo 功能启用扩展特性，这些特性向 App 添加新的构建方法，允许更方便地访问该软件包的功能。添加了对 bevy_app 的依赖。

“bevy-compat”功能增加了运行条件，以与Bevy的遗留状态实现保持兼容。

默认情况下，所有可选的Cargo功能都已被启用。

运行条件

此包提供了一种名为“运行条件”的替代方案，用于Bevy的运行标准。

选择不同的名称是为了避免与Bevy中的API发生命名冲突和混淆。Bevy运行标准已经深度集成到Bevy的调度模型中，而此包不会接触/替换它们。它们在技术上仍然存在并且可使用。

运行条件是如何工作的？

您可以将任何Bevy系统转换为“条件系统”。这允许您通过重复调用.run_if构建器方法来添加任意数量的“条件”。

每个条件都是一个输出（返回）布尔值的Bevy系统。

条件系统将自身呈现给Bevy作为一个单独的大系统（类似于Bevy的系统管道），结合了创建它的系统以及附加的所有条件系统。

运行时，它将运行每个条件，如果其中任何一个返回false，则终止。只有当所有条件返回true时，主系统才会运行。

(请参阅examples/conditions.rs以获取更完整的示例)

use bevy::prelude::*;
use iyes_loopless::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_system(
            notify_server
                .run_if(in_multiplayer)
                .run_if(on_mytimer)
        )
        .run();
}

/// Condition checking our timer
fn on_mytimer(mytimer: Res<MyTimer>) -> bool {
    mytimer.timer.just_finished()
}

/// Condition checking if we are connected to multiplayer server
fn in_multiplayer(gamemode: Res<GameMode>, connected: Res<ServerState>) -> bool {
    *gamemode == GameMode::Multiplayer &&
    connected.is_active()
}

/// Some system that should only run on a timer in multiplayer
fn notify_server(/* ... */) {
    // ...
}

强烈建议所有条件系统仅以不可变方式访问数据。避免在条件系统中进行可变访问或使用局部变量，除非您非常确定自己在做什么。如果您将相同的条件添加到多个系统中，它将针对每个系统运行。

还有一些辅助方法，可以轻松添加常见类型的运行条件

• .run_if_not：反转条件的输出
• .run_on_event::<T>()：如果有特定类型的事件，则运行
• .run_if_resource_exists::<T>()：如果存在特定类型的资源，则运行
• .run_unless_resource_exists::<T>()：如果不存在特定类型的资源，则运行
• .run_if_resource_equals(value)：如果资源的值等于提供的值，则运行
• .run_unless_resource_equals(value)：如果资源的值不等于提供的值，则运行

如果您正在使用状态

• .run_in_state(状态)
• .run_not_in_state(状态)

如果您需要使用经典Bevy状态，可以使用这些适配器使用运行条件来检查它们

• .run_in_bevy_state(状态)
• .run_not_in_bevy_state(状态)

您可以使用Bevy标签进行系统排序，就像通常一样。

注意：条件系统目前仅支持显式标签，您不能使用Bevy的“按函数名称排序”语法。例如：.after(another_system)不会工作，您需要创建一个标签。

此外还有 ConditionSet（类似于 Bevy 的 SystemSet）：用于轻松应用许多系统共有的条件和标签的语法糖。

use bevy::prelude::*;
use iyes_loopless::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_system(
            notify_server
                .run_if(in_multiplayer)
                .run_if(on_mytimer)
                // use bevy labels for ordering, as usual :)
                // (must be added at the end, after the conditions)
                .label("thing")
                .before("thing2")
        )
        // You can easily apply many conditions to many systems
        // using a `ConditionSet`:
        .add_system_set(ConditionSet::new()
            // all the conditions, and any labels/ordering
            // must be added before adding the systems
            // (helps avoid confusion and accidents)
            // (makes it clear they apply to all systems in the set)
            .run_if(in_multiplayer)
            .run_if(other_condition)
            .label("thing2")
            .after("stuff")
            .with_system(system1)
            .with_system(system2)
            .with_system(system3)
            .into() // Converts into Bevy `SystemSet` (to add to App)
        )
        .run();
}

注意：由于 Bevy 的一些限制，label/before/after 不支持在 ConditionSet 中的单个系统中使用。您只能在整个集合上使用标签和排序，以将其应用到所有成员系统。如果某些系统需要不同的排序，只需使用 .add_system 单独添加即可。

use bevy::prelude::*;
use iyes_loopless::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        // add the fixed timestep stage:
        // (in the default position, before CoreStage::Update)
        .add_fixed_timestep(
            Duration::from_millis(250),
            // we need to give it a string name, to refer to it
            "my_fixed_update",
        )
        // add fixed timestep systems:
        .add_fixed_timestep_system(
            "my_fixed_update", 0, // fixed timestep name, sub-stage index
            // it can be a conditional system!
            my_simulation
                .run_if(some_condition)
                .run_in_state(AppState::InGame)
                .after("some_label")
        )
        .run();
}

fn timestep_control(mut timesteps: ResMut<FixedTimestep>) {
    // we can access our timestep by name
    let info = timesteps.get_mut("my_fixed_update").unwrap();
    // set a different duration
    info.step = Duration::from_millis(125);
    // pause it
    info.paused = true;
}

/// Print info about the fixed timestep this system runs in
fn debug_fixed(timesteps: Res<FixedTimesteps>) {
    // from within a system that runs inside the fixed timestep,
    // you can use `.get_current`, no need for the timestep name:
    let info = timesteps.get_current().unwrap();
    println!("Fixed timestep duration: {:?} ({} Hz).", info.timestep(), info.rate());
    println!("Overstepped by {:?} ({}%).", info.remaining(), info.overstep() * 100.0);
}

use bevy::prelude::*;
use iyes_loopless::prelude::*;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
enum GameState {
    MainMenu,
    InGame,
}

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        // Add our state type
        .add_loopless_state(GameState::MainMenu)
        // If we had more state types, we would add them too...

        // Add a FixedTimestep, cuz we can!
        .add_fixed_timestep(
            Duration::from_millis(250),
            "my_fixed_update",
        )
        .add_fixed_timestep_system(
            "my_fixed_update", 0,
            my_simulation
                .run_in_state(AppState::InGame)
        )

        // Add our various systems
        .add_system(menu_stuff.run_in_state(GameState::MainMenu))
        .add_system(animate.run_in_state(GameState::InGame))

        // On states Enter and Exit
        .add_enter_system(GameState::MainMenu, setup_menu)
        .add_exit_system(GameState::MainMenu, despawn_menu)
        .add_enter_system(GameState::InGame, setup_game)

        .run();
}