Crate bevy_prng 

Bevy PRNG

What is Bevy PRNG?

bevy_prng is a crate that provides componentised versions of various rand_* PRNG algorithm crates to make them suitable for integration within bevy for reflection purposes. It enables these types to have stable TypePaths and otherwise implement various required traits. This crate can be used as standalone to provide access to various PRNG algorithms of one’s choice, to then use components for one’s game in bevy, but primarily, it’s purpose to support and be a counterpart to bevy_rand (which provides the utilities that bevy_prng types can plug in to).

This crate is no_std compatible.

Using Bevy PRNG

By default, bevy_prng won’t export anything unless the feature/algorithm you require is explicitly defined. In order to gain access to a PRNG component, you’ll have activate one of the following features:

• bevy_reflect - Enables reflection support for all bevy_prng types.
• std - This enables some std specific functionality. Only for std environments.
• thread_local_entropy - Enables ThreadLocalEntropy, overriding SeedableRng::from_entropy implementations to make use of thread local entropy sources for faster PRNG initialisation. Requires std environments so it enables the std feature.
• chacha20 - This enables the exporting of ChaCha*Rng components, for those that want/need to use a CSPRNG level source.
• rand_pcg - This enables the exporting of Pcg* components from rand_pcg.
• rand_xoshiro - This enables the exporting of Xoshiro* components from rand_xoshiro. It also exports a remote-reflected version of Seed512 so to allow setting up Xoshiro512StarStar and so forth.
• wyrand - This enables the exporting of the WyRand component from wyrand, the same algorithm in use within fastrand/turborand.
• compat_06 - This enables the old v0.6 RngCore trait implementation on the RNGs, providing additional compatibility with other crates that haven’t yet upgraded to the latest rand_core/rand versions.
• compat_09 - This enables the old v0.9 RngCore trait implementation on the RNGs, providing additional compatibility with other crates that haven’t yet upgraded to the latest rand_core/rand versions.
• wasm_js - This enables the getrandom WASM JS backend, though this should only be activated conditionally for wasm targets. That requires extra steps outlined here.

In addition to these feature flags to enable various supported algorithms, there’s also serialize flag to provide serde support for Serialize/Deserialize.

All types are provided at the top-level of the module:

use bevy_prng::*;

Supported PRNG Algorithms/Crates

All the below crates implement the necessary traits to be compatible with bevy_prng. Additional PRNG crates can be added via PR’s to this crate/repo, provided the PRNGs implement Debug, Clone, PartialEq and have optional Serialize/Deserialize serde traits implemented and put behind appropriate feature flags.

Cryptographically Secure PRNGs

• chacha20

Non-Cryptographically Secure PRNGS

• wyrand
• rand_xoshiro
• rand_pcg

Usage within Web WASM environments

To enable bevy_prng to work with Web WASM in v0.15, just paste the following into your Cargo.toml for your binary crate:

[target.'cfg(all(target_family = "wasm", any(target_os = "unknown", target_os = "none")))'.dependencies]
bevy_prng = { version = "0.15", features = ["wasm_js"] }

This enables the wasm_js backend to be made available for getrandom, which will allow bevy_prng to compile correctly for web WASM environments. The reason for this is that wasm32-unknown-unknown is itself not actually a web target, so to actually target a web environment, we must specify the feature in order to activate wasm-bindgen to do its thing.

If you have older versions of getrandom in your dep tree that are getting compiled in, then you might need to add further configuration to your Cargo.toml in order to enable Web WASM builds to compile correctly:

[target.'cfg(all(target_family = "wasm", any(target_os = "unknown", target_os = "none")))'.dependencies]
bevy_prng = { version = "0.15", features = ["wasm_js"] }
# Add the line below to make v0.3.4 getrandom work in Web WASM builds
getrandom_03 = { version = "0.3.4", features = ["wasm_js"], package = "getrandom" }
# Add the line below to make v0.2.17 getrandom work in Web WASM builds
getrandom_02 = { version = "0.2.17", features = ["js"], package = "getrandom" }

Supported Versions & MSRV

bevy_prng uses the same MSRV as bevy.

bevy	bevy_prng
v0.19	v0.15
v0.18	v0.13 - v0.14
v0.17	v0.12
v0.16	v0.10 - v0.11
v0.15	v0.8 - v0.9
v0.14	v0.7 - v0.8
v0.13	v0.5 - v0.6
v0.12	v0.2
v0.11	v0.1

The versions of rand_core/rand that bevy_prng is compatible with is as follows:

bevy_prng	rand_core	rand	getrandom	compat_* features
v0.14 -> v0.15	v0.10	v0.10	v0.4	✅ (supports rand_core v0.6, v0.9)
v0.10 -> v0.13	v0.9	v0.9	v0.3	✅ (supports rand_core v0.6)
v0.1 -> v0.9	v0.6	v0.8	v0.2	❌

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.

Structs

ChaCha8Rngchacha20

A chacha20::ChaCha8Rng RNG component

ChaCha12Rngchacha20

A chacha20::ChaCha12Rng RNG component

ChaCha20Rngchacha20

A chacha20::ChaCha20Rng RNG component

Pcg32rand_pcg

A rand_pcg::Pcg32 RNG component

Pcg64rand_pcg

A rand_pcg::Pcg64 RNG component

Pcg64Dxsmrand_pcg

A rand_pcg::Pcg64Dxsm RNG component

Pcg64Mcgrand_pcg

A rand_pcg::Pcg64Mcg RNG component

ReflectRemoteRng

A type generated by the #[reflect_trait] macro for the RemoteRng trait.

ThreadLocalEntropythread_local_entropy

ThreadLocalEntropy uses thread local ChaCha8Rng instances to provide faster alternative for sourcing entropy to OS/Hardware sources. The use of ChaCha8 with 8 rounds as opposed to 12 or 20 rounds is due to tuning for additional speed/throughput. While this does minimise the quality of the entropy, the output should still be sufficiently secure as per the recommendations set in the Too Much Crypto paper. ThreadLocalEntropy is not thread-safe and cannot be sent or synchronised between threads, it should be initialised within each thread context it is needed in.

WyRandwyrand

A wyrand::WyRand RNG component

Xoroshiro64Starrand_xoshiro

A rand_xoshiro::Xoroshiro64Star RNG component

Xoroshiro64StarStarrand_xoshiro

A rand_xoshiro::Xoroshiro64StarStar RNG component

Xoroshiro128Plusrand_xoshiro

A rand_xoshiro::Xoshiro128Plus RNG component

Xoroshiro128PlusPlusrand_xoshiro

A rand_xoshiro::Xoshiro256PlusPlus RNG component

Xoroshiro128StarStarrand_xoshiro

A rand_xoshiro::Xoshiro128StarStar RNG component

Xoshiro128Plusrand_xoshiro

A rand_xoshiro::Xoshiro128Plus RNG component

Xoshiro128PlusPlusrand_xoshiro

A rand_xoshiro::Xoshiro256PlusPlus RNG component

Xoshiro128StarStarrand_xoshiro

A rand_xoshiro::Xoshiro128StarStar RNG component

Xoshiro256Plusrand_xoshiro

A rand_xoshiro::Xoshiro256Plus RNG component

Xoshiro256PlusPlusrand_xoshiro

A rand_xoshiro::Xoshiro256PlusPlus RNG component

Xoshiro256StarStarrand_xoshiro

A rand_xoshiro::Xoshiro256StarStar RNG component

Xoshiro512Plusrand_xoshiro

A rand_xoshiro::Xoshiro512Plus RNG component

Xoshiro512PlusPlusrand_xoshiro

A rand_xoshiro::Xoshiro512PlusPlus RNG component

Xoshiro512StarStarrand_xoshiro

A rand_xoshiro::Xoshiro512StarStar RNG component

Traits

EntropySeed

Marker trait for a suitable seed for EntropySource. This is an auto trait which will apply to all suitable types that meet the trait criteria.

EntropySource

A marker trait to define the required trait bounds for a seedable PRNG to be integrated as a component. This is a sealed trait.

RemoteRng

Reflectable Rng. This trait ensures that if bevy_reflect is active, that all EntropySource PRNGs can be used through reflection and interface with Rng.

RngReflectablebevy_reflect

Trait for handling contraints for valid implementations of EntropySource depending on whether reflection support is enabled or not

TypedSeedbevy_reflect

Trait for handling SeedableRng requirements, imposing constraints depending on whether reflection support is enabled or not