Bevy ECSS

What is Bevy ECSS?

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.

Why the name?

Just because Bevy ECS + CSS is a perfect fit!

Usage

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).

```rust use bevy::prelude::; use bevy_ecss::prelude::;

fn setupawesomeui(root: Entity, mut commands: Commands, assetserver: Res) { commands .entity(root) .insert(StyleSheet::new(assetserver.load("sheets/awesome.css"))); } ```

That's it, now your UI will indeed look awesome!

CSS Subset

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:

Selectors

| 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.

```css

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.

```css

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.

Properties

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

`Text` properties

Components properties

| Property | Values | Description | | :----------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------- | | background-color | named-colors \| hex_colors | Applies the property on BackgroundColor of all matched components. |

Component Selector Builtin

Bevy ECSS provites the following components selector:

This list will be expanded to match bevy_ui and other bevy core components.

Custom Component Selector

You may also register your own components or alias/overwrite builtin components selector. ```rust use bevy::prelude::; use bevy_ecss::prelude::;

[derive(Component)]

struct MyFancyComponentSelector;

[derive(Component)]

struct FancyColor;

fn somemain() { let mut app = App::new(); app.addplugins(DefaultPlugins).addplugin(EcssPlugin::default()); // You may use it as selector now, like // fancy-pants { // background-color: pink; // } app.registercomponentselector::("fancy-pants"); // Or you can overwrite a component selector. app.registercomponent_selector::("background-color"); } ```

Custom Property

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. ```rust

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. 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,
    _commands: &mut Commands,
) {
    components.0.set_a(*cache);
}

} ```

Now just register the property on App: rust ignore 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 support table

| bevy | bevy_ecss | | :---: | :-------: | | 0.8 | 0.1 | | 0.9 | 0.2 |

Contributing

Got some idea, feedback, question or found any bug? Feel free to open an issue at any time!

License

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.

Bevy ECSS

What is Bevy ECSS?

Why the name?

Usage

CSS Subset

Selectors

quest-window text {

main-menu button.enabled .border {

Properties

Style properties

Text properties

Components properties

Component Selector Builtin

Custom Component Selector

[derive(Component)]

[derive(Component)]

Custom Property

use bevy::{ecs::query::QueryItem, prelude::*};

use bevy_ecss::{prelude::*, EcssError, Property, PropertyValues};

[derive(Default)]

Bevy support table

Contributing

License

`Style` properties

`Text` properties