From 24095f69636591d3542bf59411bf855d1df45301 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Wed, 17 Sep 2025 16:26:41 -0700 Subject: [PATCH 1/7] Detailed migration guide for automatic reflection registration --- .../reflect_registration_changes.md | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 release-content/migration-guides/reflect_registration_changes.md diff --git a/release-content/migration-guides/reflect_registration_changes.md b/release-content/migration-guides/reflect_registration_changes.md new file mode 100644 index 0000000000000..e27e79c6c8e5b --- /dev/null +++ b/release-content/migration-guides/reflect_registration_changes.md @@ -0,0 +1,26 @@ +--- +title: Changes to type registration for reflection +pull_requests: [15030, 20435, 20893] +--- + +Calling `.register_type` has long been a nuisance for Bevy users: both library authors and end users. +This step was previously required in order to register reflected type information in the `TypeRegistry`. + +This comes with a few caveats however: + +1. This functionality is gated by feature flags. Projects with default features off will not see reflected types unless one of these features is enabled. +2. There are two approaches to do this: one has incomplete platform support, while the other relies on a specific project structure. +3. Generic types are not automatically registered, and must still be manually registered. + +In order for Bevy to automatically register your types, you need to turn on the `reflect_auto_register` feature, or the fallback `reflect_autoregister_static`. +The `reflect_auto_register` feature is part of Bevy's default features, and is mutually incompatible with `reflect_autoregister_static`. +Be aware that the `reflect_autoregister_static` feature comes with some caveats for project structure: check the docs for [load_type_registrations!](https://docs.rs/bevy/0.17.0-rc.1/bevy/reflect/macro.load_type_registrations.html). + +We recommend: + +1. Enable `reflect_auto_register` in your application code, CI and in examples/tests. You can enable `bevy` features for tests only by adding a matching copy of `bevy` to `dev-dependencies` with the needed features enabled. + 1. Many libraries, and most production games do not need this functionality. This feature flag (like all reflection) is often only used for development, not for production projects. +2. Do not enable these features in your library code. +3. As a library author, you can safely remove all non-generic `.register_type` calls. +4. As a user, if you run into an unregistered generic type with the correct feature enabled, file a bug with the project that defined the offending type, and workaround it by calling `.register_type` manually. +5. If you are on an unsupported platform but need reflection support, try the `reflect_autoregister_static` feature, and consider working upstream to add support for your platform in `inventory`. As a last resort, you can still manually register all of the needed types in your application code. From 09ea72a1d74cd6d787010914cc84ac8f0ac62da7 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Wed, 17 Sep 2025 16:51:52 -0700 Subject: [PATCH 2/7] Address feedback from Jan --- .../migration-guides/reflect_registration_changes.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/release-content/migration-guides/reflect_registration_changes.md b/release-content/migration-guides/reflect_registration_changes.md index e27e79c6c8e5b..e34b2aa88c766 100644 --- a/release-content/migration-guides/reflect_registration_changes.md +++ b/release-content/migration-guides/reflect_registration_changes.md @@ -6,6 +6,7 @@ pull_requests: [15030, 20435, 20893] Calling `.register_type` has long been a nuisance for Bevy users: both library authors and end users. This step was previously required in order to register reflected type information in the `TypeRegistry`. +In Bevy 0.17 however, types which implement `Reflect` are now automatically registered, with the help of some compiler magic. This comes with a few caveats however: 1. This functionality is gated by feature flags. Projects with default features off will not see reflected types unless one of these features is enabled. @@ -19,7 +20,7 @@ Be aware that the `reflect_autoregister_static` feature comes with some caveats We recommend: 1. Enable `reflect_auto_register` in your application code, CI and in examples/tests. You can enable `bevy` features for tests only by adding a matching copy of `bevy` to `dev-dependencies` with the needed features enabled. - 1. Many libraries, and most production games do not need this functionality. This feature flag (like all reflection) is often only used for development, not for production projects. + 1. Most libraries and some production applications do not need this functionality. This feature flag (like all reflection) is most useful for dev tools, although some workflows enable it during production as well. Reflection can seriously increase both compile times and binary sizes, so enabling reflection in your library or project should be a deliberate choice. 2. Do not enable these features in your library code. 3. As a library author, you can safely remove all non-generic `.register_type` calls. 4. As a user, if you run into an unregistered generic type with the correct feature enabled, file a bug with the project that defined the offending type, and workaround it by calling `.register_type` manually. From df16f3ba72143a5688814502c4ad76587b72fce7 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Thu, 18 Sep 2025 00:03:22 -0400 Subject: [PATCH 3/7] Clarify advice on not enabling feature flags Co-authored-by: Chris Biscardi --- .../migration-guides/reflect_registration_changes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/release-content/migration-guides/reflect_registration_changes.md b/release-content/migration-guides/reflect_registration_changes.md index e34b2aa88c766..e6b97bdb3c0cc 100644 --- a/release-content/migration-guides/reflect_registration_changes.md +++ b/release-content/migration-guides/reflect_registration_changes.md @@ -21,7 +21,7 @@ We recommend: 1. Enable `reflect_auto_register` in your application code, CI and in examples/tests. You can enable `bevy` features for tests only by adding a matching copy of `bevy` to `dev-dependencies` with the needed features enabled. 1. Most libraries and some production applications do not need this functionality. This feature flag (like all reflection) is most useful for dev tools, although some workflows enable it during production as well. Reflection can seriously increase both compile times and binary sizes, so enabling reflection in your library or project should be a deliberate choice. -2. Do not enable these features in your library code. +2. Do not enable the `reflect_auto_register` feature, or the fallback `reflect_autoregister_static`, in your library code. 3. As a library author, you can safely remove all non-generic `.register_type` calls. 4. As a user, if you run into an unregistered generic type with the correct feature enabled, file a bug with the project that defined the offending type, and workaround it by calling `.register_type` manually. 5. If you are on an unsupported platform but need reflection support, try the `reflect_autoregister_static` feature, and consider working upstream to add support for your platform in `inventory`. As a last resort, you can still manually register all of the needed types in your application code. From 00dcf7f45f42bc7da80d0f1357b32563381955e6 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sun, 21 Sep 2025 12:33:44 -0700 Subject: [PATCH 4/7] Feedback from reviewers --- .../migration-guides/reflect_registration_changes.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/release-content/migration-guides/reflect_registration_changes.md b/release-content/migration-guides/reflect_registration_changes.md index e6b97bdb3c0cc..a500c38eaad04 100644 --- a/release-content/migration-guides/reflect_registration_changes.md +++ b/release-content/migration-guides/reflect_registration_changes.md @@ -7,21 +7,22 @@ Calling `.register_type` has long been a nuisance for Bevy users: both library a This step was previously required in order to register reflected type information in the `TypeRegistry`. In Bevy 0.17 however, types which implement `Reflect` are now automatically registered, with the help of some compiler magic. +You should be able to remove almost all of your `register_type` calls. This comes with a few caveats however: 1. This functionality is gated by feature flags. Projects with default features off will not see reflected types unless one of these features is enabled. 2. There are two approaches to do this: one has incomplete platform support, while the other relies on a specific project structure. 3. Generic types are not automatically registered, and must still be manually registered. -In order for Bevy to automatically register your types, you need to turn on the `reflect_auto_register` feature, or the fallback `reflect_autoregister_static`. -The `reflect_auto_register` feature is part of Bevy's default features, and is mutually incompatible with `reflect_autoregister_static`. -Be aware that the `reflect_autoregister_static` feature comes with some caveats for project structure: check the docs for [load_type_registrations!](https://docs.rs/bevy/0.17.0-rc.1/bevy/reflect/macro.load_type_registrations.html). +In order for Bevy to automatically register your types, you need to turn on the `reflect_auto_register` feature, or the fallback `reflect_auto_register_static`. +The `reflect_auto_register` feature is part of Bevy's default features, and can be overridden by the `reflect_auto_register_static` feature flag. +Be aware that the `reflect_auto_register_static` feature comes with some caveats for project structure: check the docs for [load_type_registrations!](https://docs.rs/bevy/0.17.0-rc.1/bevy/reflect/macro.load_type_registrations.html) and follow the [`auto_register_static` example](https://github.com/bevyengine/bevy/tree/main/examples/reflection/auto_register_static). We recommend: 1. Enable `reflect_auto_register` in your application code, CI and in examples/tests. You can enable `bevy` features for tests only by adding a matching copy of `bevy` to `dev-dependencies` with the needed features enabled. 1. Most libraries and some production applications do not need this functionality. This feature flag (like all reflection) is most useful for dev tools, although some workflows enable it during production as well. Reflection can seriously increase both compile times and binary sizes, so enabling reflection in your library or project should be a deliberate choice. -2. Do not enable the `reflect_auto_register` feature, or the fallback `reflect_autoregister_static`, in your library code. +2. Do not enable the `reflect_auto_register` feature, or the fallback `reflect_auto_register_static`, in your library code. 3. As a library author, you can safely remove all non-generic `.register_type` calls. 4. As a user, if you run into an unregistered generic type with the correct feature enabled, file a bug with the project that defined the offending type, and workaround it by calling `.register_type` manually. 5. If you are on an unsupported platform but need reflection support, try the `reflect_autoregister_static` feature, and consider working upstream to add support for your platform in `inventory`. As a last resort, you can still manually register all of the needed types in your application code. From 783b08b93e4b694d331e9b795d89929e6ecc0042 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sun, 21 Sep 2025 12:34:37 -0700 Subject: [PATCH 5/7] Cut digression on utility of reflection --- .../migration-guides/reflect_registration_changes.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/release-content/migration-guides/reflect_registration_changes.md b/release-content/migration-guides/reflect_registration_changes.md index a500c38eaad04..7355d697da46d 100644 --- a/release-content/migration-guides/reflect_registration_changes.md +++ b/release-content/migration-guides/reflect_registration_changes.md @@ -18,11 +18,10 @@ In order for Bevy to automatically register your types, you need to turn on the The `reflect_auto_register` feature is part of Bevy's default features, and can be overridden by the `reflect_auto_register_static` feature flag. Be aware that the `reflect_auto_register_static` feature comes with some caveats for project structure: check the docs for [load_type_registrations!](https://docs.rs/bevy/0.17.0-rc.1/bevy/reflect/macro.load_type_registrations.html) and follow the [`auto_register_static` example](https://github.com/bevyengine/bevy/tree/main/examples/reflection/auto_register_static). -We recommend: +We recommend that you: 1. Enable `reflect_auto_register` in your application code, CI and in examples/tests. You can enable `bevy` features for tests only by adding a matching copy of `bevy` to `dev-dependencies` with the needed features enabled. - 1. Most libraries and some production applications do not need this functionality. This feature flag (like all reflection) is most useful for dev tools, although some workflows enable it during production as well. Reflection can seriously increase both compile times and binary sizes, so enabling reflection in your library or project should be a deliberate choice. -2. Do not enable the `reflect_auto_register` feature, or the fallback `reflect_auto_register_static`, in your library code. +2. Do not enable the `reflect_auto_register` feature or the fallback `reflect_auto_register_static` in your library code. 3. As a library author, you can safely remove all non-generic `.register_type` calls. 4. As a user, if you run into an unregistered generic type with the correct feature enabled, file a bug with the project that defined the offending type, and workaround it by calling `.register_type` manually. 5. If you are on an unsupported platform but need reflection support, try the `reflect_autoregister_static` feature, and consider working upstream to add support for your platform in `inventory`. As a last resort, you can still manually register all of the needed types in your application code. From e2ff3cca1fed918082d7a845e76d0ecb4a5226dd Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sun, 21 Sep 2025 12:35:12 -0700 Subject: [PATCH 6/7] Clarify what's gated by feature flags --- .../migration-guides/reflect_registration_changes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/release-content/migration-guides/reflect_registration_changes.md b/release-content/migration-guides/reflect_registration_changes.md index 7355d697da46d..9742e83ed1cc8 100644 --- a/release-content/migration-guides/reflect_registration_changes.md +++ b/release-content/migration-guides/reflect_registration_changes.md @@ -10,7 +10,7 @@ In Bevy 0.17 however, types which implement `Reflect` are now automatically regi You should be able to remove almost all of your `register_type` calls. This comes with a few caveats however: -1. This functionality is gated by feature flags. Projects with default features off will not see reflected types unless one of these features is enabled. +1. Automatic type registration is gated by feature flags. Projects with default features off will not see reflected types unless one of these features is enabled. 2. There are two approaches to do this: one has incomplete platform support, while the other relies on a specific project structure. 3. Generic types are not automatically registered, and must still be manually registered. From 3f8390858c9dff62168918f93c0c78dead1cf177 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sun, 21 Sep 2025 16:32:18 -0400 Subject: [PATCH 7/7] Clarify that manual type registration still works Co-authored-by: Chris Biscardi --- .../migration-guides/reflect_registration_changes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/release-content/migration-guides/reflect_registration_changes.md b/release-content/migration-guides/reflect_registration_changes.md index 9742e83ed1cc8..ce35c13b5e52e 100644 --- a/release-content/migration-guides/reflect_registration_changes.md +++ b/release-content/migration-guides/reflect_registration_changes.md @@ -10,7 +10,7 @@ In Bevy 0.17 however, types which implement `Reflect` are now automatically regi You should be able to remove almost all of your `register_type` calls. This comes with a few caveats however: -1. Automatic type registration is gated by feature flags. Projects with default features off will not see reflected types unless one of these features is enabled. +1. Automatic type registration is gated by feature flags. 2. There are two approaches to do this: one has incomplete platform support, while the other relies on a specific project structure. 3. Generic types are not automatically registered, and must still be manually registered.