Skip to content

Commit

Permalink
chore: Correct example usage for migration
Browse files Browse the repository at this point in the history
  • Loading branch information
Bluefinger committed Aug 29, 2023
1 parent a09eb51 commit b02c688
Show file tree
Hide file tree
Showing 2 changed files with 12 additions and 12 deletions.
18 changes: 9 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -160,7 +160,7 @@ bevy_prng = { version = "0.1", features = ["rand_chacha", "wyrand"] }
```rust ignore
use bevy::prelude::*;
use bevy_rand::prelude::*;
use bevy_prng::ChaCha8Rng;
use bevy_prng::{ChaCha8Rng, WyRand};
```

Using PRNGs directly from the `rand_*` crates is not possible without newtyping, and better to use `bevy_prng` instead of writing your own newtypes. Types from `rand` like `StdRng` and `SmallRng` are not encouraged to be used or newtyped as they are not **portable**, nor are they guaranteed to be stable. `SmallRng` is not even the same algorithm if used on 32-bit platforms versus 64-bit platforms. This makes them unsuitable for purposes of reflected/stable/portable types needed for deterministic PRNG. Likely, you'd be using `StdRng`/`SmallRng` directly without integration into Bevy's ECS. This is why the algorithm crates are used directly by `bevy_prng`, as this is the recommendation from `rand` when stability and portability is important.
Expand All @@ -185,20 +185,20 @@ If that extra level of security is not necessary, but there is still need for ex

## Migrating from v0.2 to v0.3

As v0.3 is a breaking change to v0.2, the process to migrate over is fairly simple. The rand algorithm crates can no longer be used directly, but they can be swapped wholesale with `bevy_prng` instead. So the following:
As v0.3 is a breaking change to v0.2, the process to migrate over is fairly simple. The rand algorithm crates can no longer be used directly, but they can be swapped wholesale with `bevy_prng` instead. So the following `Cargo.toml` changes:

```rust ignore
use bevy::prelude::*;
use bevy_rand::prelude::*;
use rand_chacha::ChaCha8Rng;
```diff
- rand_chacha = { version = "0.3", features = ["serde1"] }
+ bevy_prng = { version = "0.1", features = ["rand_chacha"] }
```

becomes:
allows then you to swap your import like so, which should then plug straight into existing `bevy_rand` usage seamlessly:

```rust ignore
```diff
use bevy::prelude::*;
use bevy_rand::prelude::*;
use bevy_prng::ChaCha8Rng;
- use rand_chacha::ChaCha8Rng;
+ use bevy_prng::ChaCha8Rng;
```

This **will** change the type path and the serialization format for the PRNGs, but currently, moving between different bevy versions has this problem as well as there's currently no means to migrate serialized formats from one version to another yet. The rationale for this change is to enable stable `TypePath` that is being imposed by bevy's reflection system, so that future compiler changes won't break things unexpectedly as `std::any::type_name` has no stability guarantees. Going forward, this should resolve any stability problems `bevy_rand` might have and be able to hook into any migration tool `bevy` might offer for when scene formats change/update.
Expand Down
6 changes: 3 additions & 3 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@
#![deny(missing_docs)]
#![doc = include_str!("../README.md")]

/// Components for integrating `RngCore` PRNGs into bevy.
/// Components for integrating [`RngCore`] PRNGs into bevy. Must be newtyped to support [`Reflect`].
pub mod component;
/// Plugin for integrating `RngCore` PRNGs into bevy.
/// Plugin for integrating [`RngCore`] PRNGs into bevy. Must be newtyped to support [`Reflect`].
pub mod plugin;
/// Prelude for providing all necessary types for easy use.
pub mod prelude;
/// Resource for integrating `RngCore` PRNGs into bevy.
/// Resource for integrating [`RngCore`] PRNGs into bevy. Must be newtyped to support [`Reflect`].
pub mod resource;
#[cfg(feature = "thread_local_entropy")]
mod thread_local_entropy;
Expand Down

0 comments on commit b02c688

Please sign in to comment.