10 releases (6 breaking)
0.7.1 | Jul 5, 2024 |
---|---|
0.7.0 | Jul 4, 2024 |
0.6.0 | Apr 24, 2024 |
0.5.2 | Feb 21, 2024 |
0.1.0 | Apr 14, 2023 |
#47 in Game dev
471 downloads per month
Used in haalka
67KB
1K
SLoC
Bevy Rand
What is Bevy Rand?
Bevy Rand is a plugin to provide integration of rand
ecosystem PRNGs in an ECS friendly way. It provides a set of wrapper component and resource types that allow for safe access to a PRNG for generating random numbers, giving features like reflection, serialization for free. And with these types, it becomes possible to have determinism with the usage of these integrated PRNGs in ways that work with multi-threading and also avoid pitfalls such as unstable query iteration order.
Using Bevy Rand
There's now a tutorial, go to here if you want a more comprehensive rundown of how to use
bevy_rand
.
Usage of Bevy Rand can range from very simple to quite complex use-cases, all depending on whether one cares about deterministic output or not. First, add bevy_rand
, and either rand_core
or rand
to your Cargo.toml
to bring in both the components and the PRNGs you want to use, along with the various traits needed to use the RNGs. To select a given algorithm type with bevy_rand
, enable the feature representing the algorithm rand_*
crate you want to use. This will then give you access to the PRNG structs via the prelude. Alternatively, you can use bevy_prng
directly to get the newtyped structs with the same feature flags. However, using the algorithm crates like rand_chacha
directly will not work as these don't implement the necessary traits to support bevy's reflection.
All supported PRNGs and compatible structs are provided by the bevy_prng
crate. Simply activate the relevant features in bevy_rand
/bevy_prng
to pull in the PRNG algorithm you want to use, and then import them like so:
bevy_rand
feature activation
rand_core = "0.6"
bevy_rand = { version = "0.7", features = ["rand_chacha", "wyrand"] }
bevy_prng
feature activation
rand_core = "0.6"
bevy_rand = "0.7"
bevy_prng = { version = "0.7", features = ["rand_chacha", "wyrand"] }
The summary of what RNG algorithm to choose is: pick wyrand
for almost all cases as it is faster and more portable than other algorithms. For cases where you need the extra assurance of entropy quality (for security, etc), then use rand_chacha
. For more information, go here.
Registering a PRNG for use with Bevy Rand
Before a PRNG can be used via GlobalEntropy
or EntropyComponent
, it must be registered via the plugin.
use bevy::prelude::*;
use bevy_prng::WyRand;
use bevy_rand::prelude::EntropyPlugin;
use rand_core::RngCore;
fn main() {
App::new()
.add_plugins(EntropyPlugin::<WyRand>::default())
.run();
}
Basic Usage
At the simplest case, using GlobalEntropy
directly for all random number generation, though this does limit how well systems using GlobalEntropy
can be parallelised. All systems that access GlobalEntropy
will run serially to each other.
use bevy::prelude::ResMut;
use bevy_prng::WyRand;
use bevy_rand::prelude::GlobalEntropy;
use rand_core::RngCore;
fn print_random_value(mut rng: ResMut<GlobalEntropy<WyRand>>) {
println!("Random value: {}", rng.next_u32());
}
Forking RNGs
For seeding EntropyComponent
s from a global source, it is best to make use of forking instead of generating the seed value directly. GlobalEntropy
can only exist as a singular instance, so when forking normally, it will always fork as EntropyComponent
instances.
use bevy::prelude::*;
use bevy_prng::WyRand;
use bevy_rand::prelude::{GlobalEntropy, ForkableRng};
#[derive(Component)]
struct Source;
fn setup_source(mut commands: Commands, mut global: ResMut<GlobalEntropy<WyRand>>) {
commands
.spawn((
Source,
global.fork_rng(),
));
}
EntropyComponent
s can be seeded/forked from other EntropyComponent
s as well.
use bevy::prelude::*;
use bevy_prng::WyRand;
use bevy_rand::prelude::{EntropyComponent, ForkableRng};
#[derive(Component)]
struct Npc;
#[derive(Component)]
struct Source;
fn setup_npc_from_source(
mut commands: Commands,
mut q_source: Query<&mut EntropyComponent<WyRand>, (With<Source>, Without<Npc>)>,
) {
let mut source = q_source.single_mut();
for _ in 0..2 {
commands
.spawn((
Npc,
source.fork_rng()
));
}
}
Features
thread_local_entropy
- EnablesThreadLocalEntropy
, overridingSeedableRng::from_entropy
implementations to make use of thread local entropy sources for faster PRNG initialisation. Enabled by default.serialize
- EnablesSerialize
andDeserialize
derives. Enabled by default.rand_chacha
- This enables the exporting of newtypedChaCha*Rng
structs, for those that want/need to use a CSPRNG level source.rand_pcg
- This enables the exporting of newtypedPcg*
structs fromrand_pcg
.rand_xoshiro
- This enables the exporting of newtypedXoshiro*
structs fromrand_xoshiro
. It also reexportsSeed512
so to allow setting upXoshiro512StarStar
and so forth without the need to pull inrand_xoshiro
explicitly.wyrand
- This enables the exporting of newtypedWyRand
fromwyrand
, the same algorithm in use withinfastrand
/turborand
.
Supported Versions & MSRV
bevy_rand
uses the same MSRV as bevy
.
bevy |
bevy_rand |
---|---|
v0.14 | v0.7 |
v0.13 | v0.5 - v0.6 |
v0.12 | v0.4 |
v0.11 | v0.2 - v0.3 |
v0.10 | v0.1 |
The versions of rand_core
/rand
that bevy_rand
is compatible with is as follows:
bevy_rand |
rand_core |
rand |
---|---|---|
v0.1 -> v0.7 | v0.6 | v0.8 |
Migrations
Notes on migrating between versions can be found here.
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.
Dependencies
~24MB
~458K SLoC