Skip to content

Add weak_handle! convenience macro - #17384

Merged
alice-i-cecile merged 1 commit into
bevyengine:mainfrom
SludgePhD:weak-handle-macro
Feb 5, 2025
Merged

Add weak_handle! convenience macro#17384
alice-i-cecile merged 1 commit into
bevyengine:mainfrom
SludgePhD:weak-handle-macro

Conversation

@SludgePhD

@SludgePhD SludgePhD commented Jan 15, 2025

Copy link
Copy Markdown
Contributor

Objective

  • A common bevy pattern is to pre-allocate a weak Handle with a static, random ID and fill it during Plugin::build via load_internal_asset!
  • This requires generating a random 128-bit number that is interpreted as a UUID. This is much less convenient than generating a UUID directly, and also, strictly speaking, error prone, since it often results in an invalid UUIDv4 – they have to follow the pattern xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx, where x is a random nibble (in practice this doesn't matter, since the UUID is just interpreted as a bag of bytes).

Solution

  • Add a weak_handle! macro that internally calls uuid::uuid! to parse a UUID from a string literal.
  • Now any random UUID generation tool can be used to generate an asset ID, such as uuidgen or entering "uuid" in DuckDuckGo.

Previously:

const SHADER: Handle<Shader> = Handle::weak_from_u128(314685653797097581405914117016993910609);

After this PR:

const SHADER: Handle<Shader> = weak_handle!("1347c9b7-c46a-48e7-b7b8-023a354b7cac");

Note that I did not yet migrate any of the existing uses. I can do that if desired, but want to have some feedback first to avoid wasted effort.

Testing

Tested via the included doctest.

@alice-i-cecile alice-i-cecile added A-Assets Load files from disk to use for things like images, models, and sounds C-Usability A targeted quality-of-life change that makes Bevy easier to use S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Jan 15, 2025
@BenjaminBrienen BenjaminBrienen added the D-Straightforward Simple bug fixes and API improvements, docs, test and examples label Jan 22, 2025
@BenjaminBrienen BenjaminBrienen added S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it and removed S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Feb 4, 2025

@alice-i-cecile alice-i-cecile left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Much nicer. I'd like to see the internal usages migrated in follow-up I think.

@alice-i-cecile
alice-i-cecile added this pull request to the merge queue Feb 5, 2025
Merged via the queue into bevyengine:main with commit ff466a3 Feb 5, 2025
@SludgePhD SludgePhD mentioned this pull request Feb 5, 2025
@SludgePhD
SludgePhD deleted the weak-handle-macro branch February 5, 2025 21:57
github-merge-queue Bot pushed a commit that referenced this pull request Feb 5, 2025
# Objective

- Make use of the new `weak_handle!` macro added in
#17384

## Solution

- Migrate bevy from `Handle::weak_from_u128` to the new `weak_handle!`
macro that takes a random UUID
- Deprecate `Handle::weak_from_u128`, since there are no remaining use
cases that can't also be addressed by constructing the type manually

## Testing

- `cargo run -p ci -- test`

---

## Migration Guide

Replace `Handle::weak_from_u128` with `weak_handle!` and a random UUID.
mrchantey pushed a commit to mrchantey/bevy that referenced this pull request Feb 17, 2025
# Objective

- A common bevy pattern is to pre-allocate a weak `Handle` with a
static, random ID and fill it during `Plugin::build` via
`load_internal_asset!`
- This requires generating a random 128-bit number that is interpreted
as a UUID. This is much less convenient than generating a UUID directly,
and also, strictly speaking, error prone, since it often results in an
invalid UUIDv4 – they have to follow the pattern
`xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx`, where `x` is a random nibble (in
practice this doesn't matter, since the UUID is just interpreted as a
bag of bytes).

## Solution

- Add a `weak_handle!` macro that internally calls
[`uuid::uuid!`](https://docs.rs/uuid/1.12.0/uuid/macro.uuid.html) to
parse a UUID from a string literal.
- Now any random UUID generation tool can be used to generate an asset
ID, such as `uuidgen` or entering "uuid" in DuckDuckGo.

Previously:

```rust
const SHADER: Handle<Shader> = Handle::weak_from_u128(314685653797097581405914117016993910609);
```

After this PR:

```rust
const SHADER: Handle<Shader> = weak_handle!("1347c9b7-c46a-48e7-b7b8-023a354b7cac");
```

Note that I did not yet migrate any of the existing uses. I can do that
if desired, but want to have some feedback first to avoid wasted effort.

## Testing

Tested via the included doctest.
mrchantey pushed a commit to mrchantey/bevy that referenced this pull request Feb 17, 2025
# Objective

- Make use of the new `weak_handle!` macro added in
bevyengine#17384

## Solution

- Migrate bevy from `Handle::weak_from_u128` to the new `weak_handle!`
macro that takes a random UUID
- Deprecate `Handle::weak_from_u128`, since there are no remaining use
cases that can't also be addressed by constructing the type manually

## Testing

- `cargo run -p ci -- test`

---

## Migration Guide

Replace `Handle::weak_from_u128` with `weak_handle!` and a random UUID.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-Assets Load files from disk to use for things like images, models, and sounds C-Usability A targeted quality-of-life change that makes Bevy easier to use D-Straightforward Simple bug fixes and API improvements, docs, test and examples S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants