A plugin to enable random number generation for the Bevy game engine.

Last update: Dec 23, 2022

Related tags

Overview

bevy_turborand

A plugin to enable random number generation for the Bevy game engine, built upon turborand. Implements ideas from Bevy's Deterministic RNG RFC.

turborand's internal implementation uses Wyrand, a simple and fast generator but not cryptographically secure.

Example

use bevy::prelude::*;
use bevy_turborand::*;

#[derive(Debug, Component)]
struct Player;

fn setup_player(mut commands: Commands, mut global_rng: ResMut<GlobalRng>) {
    commands.spawn()
        .insert(Player)
        .insert(RngComponent::from_global(&mut global_rng));
}

fn do_damage(mut q_player: Query<&mut RngComponent, With<Player>>) {
    let mut rng = q_player.single_mut();

    println!("Player attacked for {} damage!", rng.u32(10..=20));
}

fn main() {
    App::new()
        .add_plugin(RngPlugin::default())
        .add_startup_system(setup_player)
        .add_system(do_damage)
        .run();
}

Deterministic RNG

In order to obtain determinism for your game/app, the Rng's must be seeded. GlobalRng and RngPlugin can given a seed which then sets the internal PRNG to behave deterministically. Instead of having to seed every RngComponent manually, as long as the GlobalRng is seeded, then RngComponent can be created directly from the global instance, cloning the internal Rng to itself, which gives it a random but deterministic seed. This allows for better randomised states among RngComponents while still having a deterministic app.

Systems also must be ordered correctly for determinism to occur. Systems however do not need to be strictly ordered against every one as if some linear path. Only related systems that access a given set of RngComponents need to be ordered. Ones that are unrelated can run in parallel and still yield a deterministic result. So systems selecting a Player entity with a RngComponent should all be ordered against each other, but systems selecting an Item entity with an RngComponent that never interacts with Player don't need to be ordered with Player systems, only between themselves.

To see an example of this, view the project's tests to see how to make use of determinism for testing random systems.

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Comments

Deref implementation

Adding Deref and DerefMut derive macro attributes on both the resource and component allow direct usage instead of calling get_mut every time.

I also added some must_use attributes and extra methods

opened by ManevilleF 4
feat(Rng): Reflection support

Adding in reflection support under the serialized feature flag. Got it working after seeing some strategies for reflecting certain internal values, though will need to check and resolve if this works as intended.
enhancement

opened by Bluefinger 0
chore(Rng): Add prelude module

Does what it says on the tin. Not changing what is exposed on the root module level just yet, but will leave that to a major release in our to rejig the project structure. In the mean time, a prelude exposes all the necessary structs/traits by default and will eventually replace the root level usage.
enhancement

opened by Bluefinger 0
chore(Rng): Migrate to 0.6 turborand, prep docs and README

Preparing the crate for release, needing to pin to turborand v0.6 now that it is out, adjusting any trait implementations and also amending various things to reflect new conventions, including docs. Also providing a migration guide on the README to highlight areas to change as new version will be a breaking change over 0.2.
documentation enhancement

opened by Bluefinger 0
feat(Rng): Traitification rework, Secure RNG, granular features
Prepping for turborand 0.6 release, by taking advantage of more flexible trait implementations to improve ergonomics around components/resources, as well as improving the APIs for the crate itself. This does include breaking changes however, so this will represent a new major version for bevy_turborand 0.3.

Major Changes included:

SecureRng based component & resource, using ChaCha8 based source. Intended for cases needing higher quality entropy sources.

DelegatedRng trait, allowing for more flexible APIs around Rng & SecureRng based components/resources. Enables possibility to create own PRNGs & component variants on top of the provided DelegatedRng and turborand traits and be compatible with the crate's components.

Better rand ergonomics, by providing as_rand method to return a RandBorrowed struct to shim the underlying PRNG from a component or resource, allowing for use of rand crates within systems more easily.

Granular features, so to enable only what you need from the crate. No default features has the crate only exporting traits to allow one to write their own components/resources.

Builder pattern for RngPlugin, so to allow simpler configuration of potentially one or two Global sources of RNG.

enhancement
opened by Bluefinger 0

Owner

Gonçalo Rica Pais da Silva

Frontend Developer, lover of Typescript, recently converted Rustacean and caffiene addict.

GitHub

A Client/Server game networking plugin using QUIC, for the Bevy game engine.

Bevy Quinnet A Client/Server game networking plugin using QUIC, for the Bevy game engine. Bevy Quinnet QUIC as a game networking protocol Features Roa

65 Feb 20, 2023

Minecraft-esque voxel engine prototype made with the bevy game engine. Pending bevy 0.6 release to undergo a full rewrite.

vx_bevy A voxel engine prototype made using the Bevy game engine. Goals and features Very basic worldgen Animated chunk loading (ala cube world) Optim