Giters

Leinnan / bevy_ecss

Bevy crate which uses a subset of CSS to update Bevy ECS components

Home Page:https://leinnan.github.io/bevy_ecss/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Bevy

MIT/Apache 2.0 Realease Doc Rust Crate Bevy tracking

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

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!

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.

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

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% auto. No global values are 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 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.

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:

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.

Custom Component Selector

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");
}

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.

# 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,
        _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 support table

bevy bevy_ecss
0.8 0.1
0.9 0.2
0.10 0.3

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:

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.

About

Bevy crate which uses a subset of CSS to update Bevy ECS components

https://leinnan.github.io/bevy_ecss/

License:Apache License 2.0

Languages

Language:Rust 94.6%Language:CSS 5.4%