Bevy ECSS is a crate which allows the usage of a subset of CSS to interact with bevy_ecs. It's mainly aimed to apply styling on bevy_ui but it can be used by any component by implementing custom properties.
Just because Bevy ECS + CSS is a perfect fit!
To use Bevy ECSS just add a StyleSheet with a loaded css file to any entity and all style sheet rules will be applied to the entity and all its descendants (children of children of children and so on).
use bevy::prelude::*;
use bevy_ecss::prelude::*;
fn setup_awesome_ui(root: Entity, mut commands: Commands, asset_server: Res<AssetServer>) {
commands
.entity(root)
.insert(StyleSheet::new(asset_server.load("sheets/awesome.css")));
}That's it, now your UI will indeed look awesome!
Bevy ECSS only supports a subset of CSS at moment, since many properties and features requires more advanced selectors, components and properties which currently isn't implemented.
Here you can find a list of all currently supported selectors and properties:
| Type | Details | Example |
|---|---|---|
| Name | Selects by using bevy built-int Name component. |
#inventory { ... } |
| Class | Selects by using Class component, which is provided by Bevy ECSS. |
.enabled { ... } |
| Component | Selects by using any component, but it has to be registered before usage. You can find more details bellow. | button { ... } |
You may combine any of the above selector types to create a complex selector, if you like so. For instance, window.enabled.pop-up select all windows, which are enabled and are of pop-up type. The same rules of CSS Class selectors applies here.
This assumes that window is a bevy_ecs component and was registered before usage. Also assumes the entities has the Class component with at least enabled pop-up class name.
Aditionally, Bevy ECSS also supports descendant combinator which selects all entities that are descendant the given selector tree.
#quest-window text {
color: red;
}The above rule will match all entities which has a Text component and is descendant of any entity which as a Name component which the value of quest-window.
So it's possible to combine complex composed selectors with descendant combinator.
#main-menu button.enabled .border {
background-color: #ff03ab;
}This rule will match all components which has a Class with the value of border and are descendant of any entity which has a button component and a Class component with the value of enabled and also are descendant of any entity which has a Name component with value main-menu.
Here is a list of all currently supported properties. Note that these are properties which are provived by Bevy ECSS but you can also add your own properties at anytime.
Before reading properties description, we'll use this notation to describe accepted values:
| Notation | Description |
|---|---|
00.00% |
Any percent value, like 93% or 4.45% |
00.00px |
Any dimensional value, like 11px or 0.99px |
00.00 |
Any number value, like 0 or 14.2 |
<ident> | <ident> |
Only one of the identifiers are allowed, without quotes, like none or hidden |
<area-short-hand> |
Allows the short hand area constructor by using either dimensions or percentage, like 10px or 5% 10px 3%. No global values, or auto keyword is supported yet |
Style properties
| Property | Values | Description |
|---|---|---|
display |
flex | none |
Applies the display property on display field of all sections on matched Style components. |
position-type
8000
|
absolute | relative |
Applies the position-type property on position_type field of all sections on matched Style components. |
direction |
inherit | left-to-right | right-to-left |
Applies the direction property on direction field of all sections on matched Style components. |
flex-direction |
row | column | row-reverse | column-reverse |
Applies the flex-direction property on flex_direction field of all sections on matched Style components. |
flex-wrap |
no-wrap | wrap | wrap-reverse |
Applies the flex-wrap property on flex_wrap field of all sections on matched Style components. |
align-items |
flex-start | flex-end | center | baseline | stretch |
Applies the align-items property on align_items field of all sections on matched Style components. |
align-self |
auto | flex-start | flex-end | center | baseline | stretch |
Applies the align-self property on align_self field of all sections on matched Style components. |
align-content |
flex-start | flex-end | center | stretch | space-between | space-around |
Applies the align-content property on align_content field of all sections on matched Style components. |
justify-content |
flex-start | flex-end | center | space-between | space-around | space-evenly |
Applies the justify-content property on justify_content field of all sections on matched Style components. |
overflow |
visible | hidden |
Applies the overflow property on overflow field of all sections on matched Style components. |
left |
00.00% | 00.00px |
Applies the property on position.left field of all matched components. |
right |
00.00% | 00.00px |
Applies the property on position.right field of all matched components. |
top |
00.00% | 00.00px |
Applies the property on position.top field of all matched components. |
bottom |
00.00% | 00.00px |
Applies the property on position.bottom field of all matched components. |
width |
00.00% | 00.00px |
Applies the property on size.width field of all matched components. |
height |
00.00% | 00.00px |
Applies the property on size.height field of all matched components. |
min-width |
00.00% | 00.00px |
Applies the property on min_size.width field of all matched components. |
min-height |
00.00% | 00.00px |
Applies the property on min_size.height field of all matched components. |
max-width |
00.00% | 00.00px |
Applies the property on max_size.width field of all matched components. |
max-height |
00.00% | 00.00px |
Applies the property on max_size.height field of all matched components. |
flex-basis |
00.00% | 00.00px |
Applies the property on max_size.height field of all matched components. |
flex-grow |
0 | 1 | 2 |
Applies the property on flex_grow field of all matched components. |
flex-shrink |
0 | 1 | 2 |
Applies the property on flex_shrink field of all matched components. |
aspect-ratio |
00.00 | none |
Applies the property on aspect_ratio field of all matched components. |
margin |
<area-short-hand> |
Applies the property on margin field of all matched components. |
padding |
<area-short-hand> |
Applies the property on padding field of all matched components. |
border |
<area-short-hand> |
Applies the property on border field of all matched components. |
Text properties
| Property | Values | Description |
|---|---|---|
color |
named-colors | hex_colors |
Applies the property on style.color for all sections of matched components. |
font |
"path/to/font.ttf" |
Applies the property on style.font for all sections of matched components. |
font-size |
00.00 |
Applies the property on style.font_size for all sections of matched components. |
text-content |
"Some text value" |
Applies the property on value for all sections of matched components. |
text-align |
left | center | right |
Applies the property on alignment of all matched components. |
| Property | Values | Description |
|---|---|---|
background-color |
named-colors | hex_colors |
Applies the property on BackgroundColor of all matched components. |
Bevy ECSS provites the following components selector:
| Selector | Component |
|---|---|
background-color |
BackgroundColor |
text |
Text |
button |
Button |
node |
Node |
style |
Style |
ui-image |
UiImage |
interaction |
Interaction |
This list will be expanded to match bevy_ui and other bevy core components.
You may also register your own components or alias/overwrite builtin components selector.
use bevy::prelude::*;
use bevy_ecss::prelude::*;
#[derive(Component)]
struct MyFancyComponentSelector;
#[derive(Component)]
struct FancyColor;
fn some_main() {
let mut app = App::new();
app.add_plugins(DefaultPlugins).add_plugin(EcssPlugin::default());
// You may use it as selector now, like
// fancy-pants {
// background-color: pink;
// }
app.register_component_selector::<MyFancyComponentSelector>("fancy-pants");
// Or you can overwrite a component selector.
app.register_component_selector::<FancyColor>("background-color");
}It's also possible to implement your own properties, be it part of CSS standard or not.
Let's implement a custom alpha property with will set the alpha channel of any BackgroundColor.
# use bevy::{ecs::query::QueryItem, prelude::*};
# use bevy_ecss::{prelude::*, EcssError, Property, PropertyValues};
#[derive(Default)]
pub(crate) struct AlphaProperty;
impl Property for AlphaProperty {
// This is the cached value to be used when applying the property value.
// It is evaluated only on the first time and futures runs are cached for performance reasons.
type Cache = f32;
// Which components the property needs when applying the cached value.
// It is the same as using bevy_ecs Query<C, F>.
type Components = &'static mut BackgroundColor;
// If this property can be set only when there is another property, it's possible to filter here.
// It's not recommended to use only With<> and Without<>.
type Filters = ();
fn name() -> &'static str {
// The name of property. prefer kebab-case for consistency.
"alpha"
}
fn parse<'a>(values: &PropertyValues) -> Result<Self::Cache, EcssError> {
// PropertyValues::f32 tries to parse property value into a numeric value
if let Some(value) = values.f32() {
Ok(value)
} else {
Err(EcssError::InvalidPropertyValue(Self::name().to_string()))
}
}
// This function will be called for every entity matched on every rule selector.
fn apply<'w>(
cache: &Self::Cache,
mut components: QueryItem<Self::Components>,
_asset_server: &AssetServer,
6576
_commands: &mut Commands,
) {
components.0.set_a(*cache);
}
}Now just register the property on App:
app.register_property::<AlphaProperty>();Done! Whenever an alpha property is found on any css file, the AlphaProperty will be applied. You can find this full example here.
| bevy | bevy_ecss |
|---|---|
| 0.8 | 0.1 |
| 0.9 | 0.2 |
| 0.10 | 0.3 |
Got some idea, feedback, question or found any bug? Feel free to open an issue at any time!
Bevy ECSS is dual-licensed under either:
- MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
This means you can select the license you prefer! This dual-licensing approach is the de-facto standard in the Rust ecosystem and there are very good reasons to include both.