This adds properties to the `FeathersColorSwatch` SceneComponent to
allow specifying a percentage of the swatch to remain opaque. This is
useful for color-pickers and generally handling colors with alpha
channels.
The property value will default to 0% so no migration guide is needed.
# Objective
- Allow a single `FeathersColorSwatch` to display the selected color
with and without its alpha channel.
## Solution
- Adds `FeathersColorSwatchProps` to allow dedicating a percentage of
the swatch area to the opaque color value
## Testing
Updated the `feathers_gallery` example to display the `rgba` color
swatch with 30% dedicated to the opaque color.
---
## Showcase
<img width="1280" height="720" alt="Screenshot_2026-06-15_21-09-53"
src="https://github.com/user-attachments/assets/1b3405f5-973b-42fb-abd5-b08c39c59cb6"
/>
# Objective
`bsn!` currently requires surrounding macros in "field value position"
with `{}`:
```rust
bsn! {
Foo { value: {vec![ 100, 200 ]} }
}
```
This is annoying!
## Solution
Support macros in field-value-position:
```rust
bsn! {
Foo { value: vec![ 100, 200 ] }
}
```
## Testing
- Added a test that checks that this works
- Ported bsn! examples to use this
# Objective
Implement changes discussed with cart around erroring when using caching
syntax where its not implemented.
## Solution
Throw a compile error, in a way which is easy to remove once caching
exists/works for more cases.
Also contains a commit to alleviate trait errors which will (from my
experience writing this PR and fixing them in bevy) arise from fixing
this for existing bsn code. This commit can be dropped if not desired.
This would ideally be fixed upstream so this workaround can be removed:
https://github.com/rust-lang/rust/issues/141258#issuecomment-4565897810
Note: The error caused by this workaround is far from ideal. It
initially looks like a method call is missing, but ultimately the
hint/advice *is* correct
<img width="1982" height="477" alt="image"
src="https://github.com/user-attachments/assets/879f7630-ada8-4e63-9c59-80be466f37cf"
/>
## Testing
- `cargo test -p bevy_scene --lib`
- `cargo check`
---------
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
# Objective
Fix#19101. (Kinda, this is not the exact solution proposed in that
issue, but it still shortens most of the examples)
## Solution
Most of the images created in examples are for use in render targets.
`Image::new_target_texture` is made for exactly that and significantly
shortens the image creation process.
## Testing
I tested all the examples I changed and they seem to work fine.
---
btw for some reason most of the examples use
`TextureFormat::Bgra8UnormSrgb` while the documentation for
`Image::new_target_texture` recommends `TextureFormat::Rgba8UnormSrgb`
for SDR images. What's up with that?
---------
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
# Objective
Changes discussed with cart:
- `:` will not be called "inheritance" anymore, but instead "cacheable"
(name not final)
- the Template patching prefix changes `@` -> `~`
- the SceneComponent prefix changes `:` -> `@`
- the `:` prefix is allowed in front of `@SceneComponent` as well,
marking it as being cached
>> me: do we forbid caching of functions which take an argument?
> cart: We should forbid it until we support it, and I don't plan on
supporting this in the short term, as it adds new controversial design
aspects to the system (building a mapping from parameters to cached
scenes, ensuring the parameters are all hashable, etc).
Link to the discord thread, specifically my [recap
message](https://discord.com/channels/691052431525675048/1264881140007702558/1506422311056576702).
The exact reasoning is in the linked discord discussion, but the tldr
is:
"Inheritance" as a term for the ":" syntax didn't really fit what bsn
was doing, since scenes without `:` produce the same result. All `:` is,
is a way to say "cache this pls" with the design of bsn imposing the
limitation that only the first scene can be cached
That was all fine, except for one case: Disambiguating SceneComponents
from normal components. So if we redefine `:` to just mean "caching" we
needed to untangle it from SceneComponents. That means disambiguating
SceneComponents needed a different syntax, and the decision ended up
being to take the @ prefix from the *much* less common `@Template`
usecase, since `SceneComponent {@prop: val}` already used @ as well and
introduce a new prefix to replace `@Template` instead, replacing it with
`~Template`.
## Solution
Implement these changes in macros.
Notably, this *still* doesn't implement/enable caching right now.
Most docs are updated, except for the big blocks in
`bevy_scene/src/lib.rs` and `bevy_scene/macros/src/lib.rs` since i've
been working on reworking those on another branch and didn't want to
duplicate whats already been a lot of work and likely to be a bunch more
## Testing
- [x] `bevy_scene` tests passing
- [x] `cargo check --workspace` and `cargo check --workspace --examples`
passing
Since this PR does not yet enable caching, I think passing the current
tests should be enough.
---------
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
Co-authored-by: François Mockers <francois.mockers@vleue.com>
See release notes for rationale and usage.
Fixes#17644, #20524
(It may not be a 100% fix, but it's good enough to close the ticket I
think.)
## Testing
- Manual testing with VoiceOver on MacOS (note that VoiceOver /
AccessKit does not work well without `desktop_app` being set, but this
causes other issues)
---------
Co-authored-by: Richard Braakman <rebraakman@gmail.com>
Use our "shorthand" conventions for `Val` everywhere in feathers code /
usage
This also:
- adds a `VariantDefaults` derive to `Visibility` to make it usable
without `template_value`
- adds `From<Val>` to BorderRadius to support `px(10)` assignments
instead of `BorderRadius::all(px(10))`
---------
Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
Co-authored-by: ickshonpe <david.curthoys@googlemail.com>
with naming conventions for other widgets.
# Objective
The `ToolButton` widget was not consistently named like the other
controls.
## Solution
Renamed.
## Testing
Basic manual testing.
@cart
# Objective
> With the introduction of scene components, the feathers API has now
reached its final form. This has a number of consequences:
> - There's no longer any reason to keep the experimental flag around
> - The effort of migrating the Bevy examples to feathers widgets is
unblocked, however I think we should start with migrating just one
example
- @viridia
## Solution
1. Rename the feature flag.
2. Write a migration guide.
This was previously attempted as part of
https://github.com/bevyengine/bevy/pull/22934, but I got pushback there.
Now that bsn! is more complete (scene components!) things are better.
I've opted not to change the default features here, even though it makes
it much harder to move our examples over, because that's a much more
contentious change. While I feel that Bevy's default features should be
example-oriented, that's still up for debate!
# Objective
It is essentially a Bevy rite of passage to define a `Player` component
and then ask "ok when I spawn `Player`, how do I spawn all of the other
entities / components / scenes it needs to function with it?".
In Bevy, components are the "unit of behavior". The presence of a
component indicates that the entity should behave a certain way. Scenes
are _inextricable_ from behaviors, yet currently there is no way to tie
Components (bevy's unit of behavior) to scenes. _This is a fundamental
gap in the Bevy data model_. It is a problem that developers expect
their engine to solve for them.
It is high time that we had an official solution to this problem. BSN
was built to be that solution, and it is now time to do the last-mile
work to facilitate the `Component <-> Scene` relationship
## Solution
It is now possible to define "scene components", where `SceneComponent:
Component`:
```rust
#[derive(SceneComponent, Default, Clone)]
struct Player {
score: usize
}
impl Player {
fn scene() -> impl Scene {
bsn! {
Transform { translation: Vec3 { x: 10. } }
Children [
LeftHand,
RightHand,
]
}
}
}
```
This enables inheriting from the Player component as a scene:
```rust
world.spawn_scene(bsn! {
:Player { score: 0 }
})
```
After the inherited `Player` scene component is spawned, the _entire_
scene is available. This means that you can `Query<&Player>` in your ECS
systems, and _trust_ that the entire scene is also present.
### Inheritance Syntax vs Patch Syntax
Notice that this uses inheritance syntax in BSN (`:`), rather than
normal "component patch" syntax (ex: `bsn! { Player { score: 0 } }`.
Semantically these are different things:
- Scene inheritance syntax: constructs the full scene and inherits from
it
- Component patch syntax: _Just_ patches the component directly and
creates it if it doesn't exist. This will not do any scene inheritance.
You can still patch scene components this way as long as the scene
component is inherited somewhere "earlier" in the inheritance hierarchy.
Attempting to spawn a scene component on its own _without_ the scene
(ex: `commands.spawn(Player::default())`) will log an error, as Scene
Components should never exist without their scene.
### Custom Scene Functions
When deriving `SceneComponent`, it defaults to using `Self::scene` as
the "scene function". Scene functions can also be manually specified:
```rust
#[derive(SceneComponent, Default, Clone)]
#[scene(player)]
struct Player {
score: usize
}
fn player() -> impl Scene {
bsn! { /* scene here */}
}
```
### Inherit BSN Asset Paths
Alternatively, a scene asset path can be specified:
```rust
#[derive(SceneComponent, Default, Clone)]
#[scene("player.bsn")]
struct Player {
score: usize
}
```
Once we port the glTF loader to BSN, this will also be supported:
```rust
#[derive(SceneComponent, Default, Clone)]
#[scene("player.gltf")]
struct Player {
score: usize
}
```
### Scene Props
Sometimes it is desirable to "parameterize" a scene: pass in values to
the scene which determine what the scene outputs are.
The answer to this in BSN is "scene props":
```rust
/// A UI widget that repeats "hello" text a given number of times.
#[derive(SceneComponent, Default, Clone)]
#[scene(HelloRepeaterProps)]
struct HelloRepeater;
#[derive(Default)]
struct HelloRepeaterProps {
repeat: usize,
}
impl HelloRepeater {
fn scene(props: HelloRepeaterProps) -> impl Scene {
let hellos = (0..props.repeat)
.map(|_| bsn!{ Text("hello") })
.collect::<Vec<_>>();
bsn! {
Node
Children [
{hellos}
]
}
}
}
world.spawn_scene(bsn! {
:HelloRepeater {
@repeat: 5
}
});
```
Notice the `@field` syntax, which specifies that a prop is being set
instead of a field. Props are evaluated "immediately" at the point of
inheritance where the scene is constructed. This means that they are not
"patchable".
You can set _both_ props and normal fields at the same time:
```rust
#[derive(SceneComponent, Default, Clone)]
#[scene(WidgetProps)]
struct Widget {
value: usize
}
#[derive(Default)]
struct WidgetProps {
border: bool,
}
world.spawn_scene(bsn! {
:Widget {
@border: true,
value: 10,
}
});
```
Scene props can be used with templates:
```rust
#[derive(SceneComponent, Default, Clone)]
#[scene(PlayerProps)]
struct Player;
#[derive(Default)]
struct PlayerProps {
head: AssetPath<'static>,
body: AssetPath<'static>,
}
impl Player {
fn scene(props: PlayerProps) -> impl Scene {
bsn! {
Transform
Visibility
Children [
(Head, Sprite { image: {props.head} }),
(Body, Sprite { image: {props.body} }),
]
}
}
}
world.spawn_scene(bsn! {
:Player {
@head: "big_head.png"
@body: "small_body.png"
}
});
```
### Scene Components are Template-able
```rust
#[derive(SceneComponent, FromTemplate)]
struct Player {
image: Handle<Image>,
}
impl Player {
fn scene() -> impl Scene {
bsn! { /* scene here */}
}
}
world.spawn_scene(bsn! {
:Player { image: "player.png" }
});
```
### The Scene Component is Always Added
Specifying the scene component manually in the scene function is not
necessary. It will be added automatically:
```rust
#[derive(SceneComponent, Default, Clone)]
struct Player {
score: usize
}
impl Player {
fn scene() -> impl Scene {
bsn! {
// No need to specify a Player component here.
// It is implied!
}
}
}
```
However you _can_ patch the scene component in the scene if you would
like. This comes in handy if you would like props to contribute to the
scene component's value:
```rust
impl Player {
fn scene(props: PlayerProps) -> impl Scene {
bsn! {
Player {
size_in_meters: {props.size_in_millimeters / 1000. }
}
}
}
}
```
### SceneComponent Trait
This is what SceneComponent looks like under the hood:
```rust
pub trait SceneConstructor: FromTemplate<Template: Default>
where
<Self::Template as Template>::Output: Component,
{
type Props: Default;
fn scene(props: Self::Props) -> impl Scene;
}
```
In general, developers should prefer `#[derive(SceneComponent)`, which
derives this trait automatically, ensures the Component is never spawned
without its scene, and automatically initializes the `Component` even if
it isn't specified explicitly in the user-defined scene function.
### Reusable Component Derive Logic
This PR moves the component derive logic into a new
`bevy_ecs_macro_logic` crate and refactors it to be reusable and
extendable.
This enables the `SceneComponent` derive to reuse and configure the
`Component` derive. I also took the liberty of porting the redundant
`Resource` derive logic to this system, as it follows the same pattern.
## PR Todo
- [ ] Port this PR description to docs on `Scene`.
## Whats Next
- Scene Component scene caching: It might make sense to cache
unparameterized scenes (like we do for scene assets) to cut down on
spawn costs. We could even have an opt-in parameterized scene cache (ex:
hash the props).
- Reactivity: It is important to note that props _are not reactive_.
They do not exist post-spawn (aka "at runtime") and they cannot be
changed. However they could easily be _part_ of a reactivity story:
- Props as components: insert props as components and re-run the scene
constructor when they are mutated
- Signal props: Reactive "signal" types could be passed down the init
hierarchy via props.
- Simpler "prop patching" codegen: currently for simplicity props reuse
the template-patching logic, but this introduces a few constraints and
complexities that are unnecessary. We should consider writing
specialized logic for them.
# Objective
The `feathers gallery` example logs "Disabled button clicked!" when its
"Primary" button is clicked.
## Solution
Log "Primary button clicked!" instead.
# Objective
- Users would like the ability to know how a focus was gained
## Solution
- Add `FocusCause` field to `FocusGained` event
- Automatically select all when navigating into a text input (even
without `SelectAllOnFocus`)
## Testing
- Tab into the color input of `feathers_gallery` to test that its text
gets highlighted
# Objective
This prefix was ruled unhelpful, and we previously removed it from most
of our types.
We missed a few apparently (spotted in #23924).
## Solution
Find and replace + update the migration guide.
# Objective
Part of #19236
## Solution
A numeric text input widget. This includes:
* Colored stripes ("sigils") for designating X, Y and Z input fields.
* Character filtering
* ValueChange events
Not supported:
* Validation error events
* Range and precision options
Additional changes in this PR:
* Added small labels (related to text inputs only insofar as numeric
inputs have small labels above them in the editor design).
* Refactored labels to be simple spans instead of nested entities - this
required a non-inherited text font theme component, so we renamed the
existing component to have the word "inherited" in the name.
* Consolidated the way focus outlines work for text inputs and other
widgets
* I had to make changes to Slider and other widgets to support the
`is_final` flag in `ValueChange`. This is necessary to allow listeners
the choice between spammy and not-spammy updates when listening to
widget outputs.
## Testing
Manual testing
## Showcase
<img width="353" height="101" alt="numeric_input"
src="https://github.com/user-attachments/assets/36efd243-fa01-484e-bab5-689aa6be4d9e"
/>
# Objective
No helper nor example code exists for handling multiple radio button
groups. Currently if a user tries to use existing feathers_gallery code
to create multiple radio groups, radio buttons from all other groups
will become unchecked.
## Solution
- Within queries, only update the radio buttons inside their own group
- Add `radio_self_update()` convenience function to encapsulate this
desired behavior
## Testing
Manually tested inside feathers_gallery example
# Objective
Spawning a scene on startup is a common pattern. Lets make it easier to
do so!
## Solution
- Add `SpawnSystem` and `SpawnListSystem` traits that are implemented
for functions that return scenes / scene lists, and return a system that
spawns the scene / handles errors.
### Before
```rust
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_systems(Startup, setup)
.run();
}
fn setup(world: &mut World) -> Result {
world.spawn_scene_list(bsn_list![Camera2d, ui()])?;
Ok(())
}
```
### After
```rust
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_systems(Startup, scene.spawn())
.run();
}
fn scene() -> impl SceneList {
bsn_list![Camera2d, ui()]
}
```
This cuts out some boilerplate. It also further encourages people to
define standalone "scene functions" rather than embedding them in code,
which is generally a good pattern.
# Objective
* Bevy UI's accessibility module doesn't set the transform on
accessiblity nodes, ignoring scaling and rotation.
* UI accessibility nodes should be updated before `bevy_winit` updates
the accesskit adaptors, otherwise there will be a frames delay.
## Solution
Replaced the `calc_bounds` systems with a new system
`sync_bounds_and_transforms`.
Each accesskit `Node` corresponding to an `AccessibleNode` UI entity is
now given object-centered coordinates for its bounding rect (instead of
window coordinates) and a transform.
Accesskit uses local transforms so if an accessible node also has an
accessible parent, its transform has to be recomputed relative to its
parent.
## Testing
I modified the button example so that accesskit integration is enabled
by default and the button is drawn at a 45 degrees angle.
```
cargo run --example button
```
Screen readers should only react when the pointer is directly over the
rotated button if the changes are working.
The example changes should be reverted before merging.
# Objective
In the `feathers_gallery` example, on a `TextEditChange`
`handle_hex_color_change` updates `DemoWidgetStates` which causes
`update_colors` to update the hex input triggering another
`TextEditChange`.
## Solution
Only update `DemoWidgetStates` in `handle_hex_color_change` if the new
color is different.
# Objective
Part of #19236
The "disclosure toggle" is a small checkbox-like widget which displays a
chevron that toggles between pointing right and pointing down.
## Testing
Manual testing
# Objective
* Fix toggle behavior
* Add more style tokens and polish appearance
The original intention for the Feathers Checkbox was to toggle the
change immediately on mouse press, but currently only toggles on mouse
release, and lacks styling. Both behaviors are desirable depending on
context, such as being able to cancel an expensive checkmark click that
vastly changes render settings, so this pull request allows both, with
the mouse-press behavior enabled via the `ActivateOnPress` component.
In addition to adding styling, there will no longer a visible outline
for the checkbox in the checked state in the default theme. Having a
border and check symbol made it visually busy, especially at small
sizes.
---
## Showcase
### Before
<img width="161" height="83" alt="Screenshot 2026-04-15 at 7 58 09 PM"
src="https://github.com/user-attachments/assets/9cae7bcf-0b2a-46db-954a-b09332a7b06f"
/>
### After
<img width="161" height="108" alt="Screenshot 2026-04-15 at 8 34 57 PM"
src="https://github.com/user-attachments/assets/72d5083f-20db-45cd-8c1b-1ee711fcedf3"
/>
(Not pictured: new intermediate styling for mouse press)
# Objective
Horizontal equivalent of the `visible_lines` option.
Allow users to set the width of a text input widget by number of glyphs.
Or for proportional fonts, where the glyph widths are non-uniform, it
would use a multiple of the advance width for "0".
## Solution
* New `visible_width: Option<f32>` field on `EditableText`.
* `TextInputMeasure` now has both a width and height field and both are
`Option<f32>`.
* `update_editable_text_content_size` calculates the width if
`visible_width` is `Some`.
* The width is calculated by multiplying the advance width of "0" by the
`visible_width` (if set) and the current scale factor.
## Testing
I altered the hex input in the `feathers` example to so it's sized to
fit 10 characters (includes space for the cursor).
```
cargo run --example feathers --features="experimental_bevy_feathers"
```
---------
Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
# Objective
As discussed in [this discord
thread](https://discord.com/channels/691052431525675048/1492688648360165406),
using the `Children` relation to append caption elements to feathers
widgets is dodgy.
## Solution
Make `caption` an explicit parameter for button, radio, and checkbox
widgets.
Also fixed some erroneous docs.
## Testing
Manual testing of feathers and bevy_city examples.
Note that there's no migration guide because this only affects the bsn
functions, which are new.
# Objective
- The feathers example is more a gallery than a simple introduction to
feathers.
- We need a simple example to introduce people to feathers
## Solution
- Add a simple counter that uses feathers
## Testing
I ran the example on my machine
---
## Showcase
https://github.com/user-attachments/assets/4e827e9a-aed9-4c23-918e-05464a5ada67
It doesn't look super great so any styling suggestion is appreciated.
---------
Co-authored-by: Kevin Chen <chen.kevin.f@gmail.com>
# Objective
When working with more complex widgets, users have repeatedly asked for
a way to reliably detect when an entity gains or loses focus. They have
not, however, filed an issue about this 🎟️
These are called
[`focus`](https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event)
/
[`focusin`](https://developer.mozilla.org/en-US/docs/Web/API/Element/focusin_event)
+
[`blur`](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event)
/
[`focusout`](https://developer.mozilla.org/en-US/docs/Web/API/Element/focusout_event)
on the web. The former element in these pairs does not bubble, while the
latter does.
Because Bevy's observer infrastructure allows you to get the original
target of a bubbled event, we can create only bubbling variations.
@viridia has suggested that
https://github.com/bevyengine/bevy/pull/23707 would benefit from a form
of this feature.
## Rejected designs
The simplest approach would be to simply add a `previously_focused`
field on `InputFocus`, and then emit events based on the difference
using an ordinary system. Unfortunately, this has a serious flaw: events
are lost if this changes state multiple times in the same frame.
We can resolve this problem by completely locking down access, and
requiring commands or events to be used to change the input focus. This
ensures no changes are lost and sends them off semi-immediately, but is
a major breaking change to this API and prevents immediate-mode checks
of "what is the current input focus".
## Solution
We can do better. If we sacrifice "FocusGained and Lost must be emitted
immediately", we can track changes inside of `InputFocus`, before
sending them off in an ordinary system.
This is minimally breaking (you have to use the getters/setters now),
and ensures no gained/lost events are ever missed. Users who completely
overwrite `InputFocus` (e.g. by using `from_entity`) will miss changes,
but frankly, you deserve it if you ignore the nice setters and clear
warnings in the docs.
- Define `FocusGained` and `FocusLost` events. Split to their own file
for cleanliness.
- Lock down access to `InputFocus`, forcing users to always go through
the existing getters and setters.
- Modify `InputFocus` to track changes as they have been made.
- Add a system to drain these once-per-frame in `PostUpdate`, converting
them into `FocusGained` and `FocusLost`.
- This timing helps ensure that any user / library code that changes the
focus has time to run, but rendering code that relies on accurate focus
information to display widgets has the information available.
- I could not find existing systems in `PostUpdate` that this needed a
relative ordering for.
- Create an `InputFocusPlugin` to store this new system, stealing some
of the setup that was previously in `InputDispatchPlugin`. Somewhat
incidentally, this fixes#19057, by selecting option 1.
## Testing
I was *not* very confident that my implementation of this logic was
correct, so I wrote a rather aggressive set of mid-level tests, using
`App`.
They pass, so apparently my first implementation was actually good
enough.
# Objective
Feathers text input widget
Part of #19236
## Solution
Build a wrapper around `EditableText` that has feathers styling and
themes.
## Testing
WiP
---------
Co-authored-by: Kevin Chen <chen.kevin.f@gmail.com>
# Objective
Now that BSN is on main, we can port Feathers over!
Related: #23030#23413
## Solution
Port Feathers, leaving the bundle functions around (renamed to
`x_bundle` and deprecated). This is largely 1:1, other than removing
HandleOrPath (which is filling the same role as HandleTemplate). I've
also ported the `feathers` and `virtual_keyboard` examples to BSN.
---------
Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
# Objective
Reposition `Popovers` in `PostLayout` using `UiGlobalTransform`.
Related: https://github.com/bevyengine/bevy/pull/23346
## Solution
* Move `popover_system` into the `PostLayout` system set.
* Reposition `Popovers` in `PostLayout` using `UiGlobalTransform`.
* Updates are immediate, so removed the trick with visibility.
## Testing
```
cargo run --example standard_widgets
```
The pop up menu still seems to work anyway.
The `Slider` widget auto-detects orientation based on dimensions
(vertical if height > width). This causes the Feathers slider to behave
as vertical when its layout happens to be taller than wide, while its
visuals (gradient direction, cursor icon) are hardcoded as horizontal.
Adds a `SliderOrientation` enum (`Auto`/`Horizontal`/`Vertical`) to give
explicit control. Sets the Feathers sliders to `Horizontal` so their
interaction matches their presentation.
Fixes#23294
---------
Co-authored-by: moktamd <moktamd@users.noreply.github.com>
# Objective
Add responsive font sizes supporting rem and viewport units to
`bevy_text` with minimal changes to the APIs and systems.
## Solution
Introduce a new `FontSize` enum:
```rust
pub enum FontSize {
/// Font Size in logical pixels.
Px(f32),
/// Font size as a percentage of the viewport width.
Vw(f32),
/// Font size as a percentage of the viewport height.
Vh(f32),
/// Font size as a percentage of the smaller of the viewport width and height.
VMin(f32),
/// Font size as a percentage of the larger of the viewport width and height.
VMax(f32),
/// Font Size relative to the value of the `RemSize` resource.
Rem(f32),
}
```
This replaces the `f32` value of `TextFont`'s `font_size` field.
The viewport variants work the same way as their respective `Val`
counterparts.
`Rem` values are multiplied by the value of the `RemSize` resource
(which newtypes an `f32`).
`FontSize` provides an `eval` method that takes a logical viewport size
and rem base size and returns an `f32` logical font size. The resolved
logical font size is then written into the `Attributes` passed to Cosmic
Text by `TextPipeline::update_buffer`.
Any text implementation using `bevy_text` must now provide viewport and
rem base values when calling `TextPipeline::update_buffer` or
`create_measure`.
`Text2d` uses the size of the primary window to resolve viewport values
(or `Vec2::splat(1000)` if no primary window is found). This is a
deliberate compromise, a single `Text2d` can be rendered to multiple
viewports using `RenderLayers`, so it's difficult to find a rule for
which viewport size should be chosen.
### Change detection
`ComputedTextBlock` has two new fields: `uses_viewport_sizes` and
`uses_rem_sizes`, which are set to true in `TextPipeline::update_buffer`
iff any text section in the block uses viewport or rem font sizes,
respectively.
The `ComputedTextBlock::needs_rerender` method has been modified to take
take two bool parameters:
```rust
pub fn needs_rerender(
&self,
is_viewport_size_changed: bool,
is_rem_size_changed: bool,
) -> bool {
self.needs_rerender
|| (is_viewport_size_changed && self.uses_viewport_sizes)
|| (is_rem_size_changed && self.uses_rem_sizes)
}
```
This ensures that text reupdates will also be scheduled if one of the text section's uses a viewport font size and the local viewport size changed, or if one of the text section's uses a rem font size and the rem size changed.
#### Limitations
There are some limitations because we don't have any sort of font style inheritance yet:
* "rem" units aren't proper rem units, and just based on the value of a resource.
* "em" units are resolved based on inherited font size, so can't be implemented without inheritance support.
#### Notes
* This PR is quite small and not very technical. Reviewers don't need to be especially familiar with `bevy_text`. Most of the changes are to the examples.
* We could consider using `Val` instead of `FontSize`, then we could use `Val`'s constructor functions which would be much nicer, but some variants might not have sensible interpretations in both UI and Text2d contexts. Also we'd have to make `Val` accessible to `bevy_text`.
## Testing
The changes to the text systems are relatively trivial and easy to understand. I already added a minor change to the `text` example to use `Vh` font size for the "hello bevy" text in the bottom right corner. If you change the size of the window, you should see the text change size in response. The text initially flickers before it updates because of some unrelated asset/image changes that mean that font textures aren't ready until the frame after the text update that changes the font size.
Most of the example migrations were automated using regular expressions, and there are bound to be mistakes in those changes. It's infeasible to check every single example thoroughly, but it's early enough in the release cycle that I don't think we should be too worried if a few bugs slip in.
---------
Co-authored-by: Kevin Chen <chen.kevin.f@gmail.com>
# Objective
- Fixes#22644
## Solution
- Create new subdirectories for categorization, and update the paths in
`Cargo.toml` and `README`.
## Testing
- `cargo check --example *`
Jeb Brooks