Famiq - Getting start

Kim Hong Muong — Sun, 09 Feb 2025 00:35:30 +0000

Famiq is a UI library built on top of Bevy UI by providing default widgets and a simple way to manage styles.

Instead of writing Rust code for styling, developers can define styles in a well known JSON file. These styles are then parsed into Bevy's native UI styles, significantly reducing boilerplate code.

You can read introduction to Famiq here.

Today we will create a simple UI app (Counter) in bevy engine using Famiq.

The Final result will look like this

Create project

in your terminal, create new rust project using cargo

cargo new counter

navigate into counter directory, and install famiq

cargo add famiq

This will install the latest version of famiq which is v0.2.5. Noted that famiq supports only bevy 0.15.x onward.

open the project in your favorite code editor and get ready to write some code!

Coding time

open main.rs inside src/ directory, paste code below into it

use bevy::prelude::*;
use famiq::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(FamiqPlugin) // required by Famiq
        .add_systems(Startup, setup)
        .run();
}

fn setup() {}

This is what we need to get started in every bevy project.

Write setup system to spawn widgets

// use this component to keep track of counter number
#[derive(Component)]
struct Count(i32);

fn setup(
    mut commands: Commands,
    asset_server: ResMut<AssetServer>, // required by Famiq
    mut famiq_res: ResMut<FamiqWidgetResource>, // required by Famiq
) {
    // spawn new 2d camera
    commands.spawn(Camera2d::default());

    // create a widget builder with hot-reload feature on
    let mut builder = FamiqWidgetBuilder::new(&mut commands, &mut famiq_res, &asset_server)
        .hot_reload();

    // Text widget
    let count_text = fa_text(&mut builder, "0").id("#count-text").build();
    builder.insert_component(count_text, Count(0));

    // Button widget
    let button = fa_button(&mut builder, "Press me").id("#button").build();

    // Container widget
    fa_container(&mut builder)
        .id("#container")
        .children([count_text, button])
        .build();
}

What is `FamiqWidgetBuilder`?

In simple terms, FamiqWidgetBuilder is the root UI node that acts as a starting point for building and managing widgets. All widgets are created and structured on top of this root.

.hot_reload() is used to enable hot-reload feature. When we make changes to JSON file (style) it will reflect the running app without needing to re-compile.

If you run the app cargo run, without any styles, you will see

Give our widgets some styles

inside root directory, create a folder called assets. Inside assets folder, create a file called styles.json.
open styles.json, paste below code into it.

{
  "#container": {
    "justify_content": "center",
    "align_items": "center",
    "width": "300px",
    "margin": "auto auto auto auto",
    "background_color": "grey",
    "padding": "35px 35px 25px 25px",
    "border": "2px 2px 2px 2px",
    "border_radius": "10px 10px 10px 10px"
  },
  "#button": {
    "margin_top": "20px"
  },
  "#count-text": {
    "font_size": "40",
    "color": "blue"
  }
}

now run the app again, you will see a better UI.

By default, famiq will look for json file at assets/styles.json. If you want to use different file name or path, you can call method use_style_path().

    let mut builder = FamiqWidgetBuilder::new(&mut commands, &mut famiq_res, &asset_server)
        .use_style_path("assets/some_name.json")
        .hot_reload();

Increase counter on button press

in order to handle button press, you will to create a new system that run in Update schedule.

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(FamiqPlugin)
        .add_systems(Startup, setup)
        .add_systems(Update, handle_button_press) // add this
        .run();
}

fn handle_button_press(
    mut events: EventReader<FaInteractionEvent>,
    mut text_res: ResMut<FaTextResource>,
    mut count_query: Query<&mut Count>
) {
    for e in events.read() {
        if e.is_button_pressed() {
            let mut count = count_query.get_single_mut().unwrap();

            count.0 += 1;
            text_res.update_value_by_id("#count-text", &count.0.to_string());
        }
    }
}

we need FaInteractionEvent to get the button press event.
we need FaTextResource to get or update text widget's value.

Now run the app again, you will be able to increase the counter!

This post is just about getting start using famiq. For more info, please go to the documentation.

Famiq's github: https://github.com/MuongKimhong/famiq
Famiq's docs: https://muongkimhong.github.io/famiq/
Famiq's crate: https://crates.io/crates/famiq

Famiq - UI Development in Bevy engine

Kim Hong Muong — Sat, 08 Feb 2025 23:45:47 +0000

Bevy engine is a modern, data-driven game engine built in Rust, designed with simplicity, speed, and flexibility in mind. Powered by the Entity-Component-System (ECS) architecture. It’s free and open-source, making it accessible to everyone from hobbyists to professional game developers.

Bevy UI is a bevy's plugin for managing UI in the engine. It's fast, flexible, and seamlessly integrates with Bevy’s ECS model. However, there’s one major challenge, the code can quickly become deeply nested and redundant. Writing UI elements in Bevy often requires explicit hierarchies, making simple UI layouts feel verbose.

Famiq - Simplify UI development in Bevy engine

Famiq is a newborn UI library buit on top of Bevy UI by providing default widgets and a simple way to manage styles.

Instead of writing Rust code for styling, developers can define styles in a well known JSON file (similar to css). These styles are then parsed into Bevy's native UI styles, significantly reducing boilerplate code.

Simple: Follows Bevy's philosophy—widgets are just Rust functions
Clean: Styles can be defined in a JSON file, reducing boilerplate code
Widgets: Includes useful default widgets like button, modal, progress bar and more.
Flexible: Just like in HTML/CSS, styles can be applied using id or classes
Hot-reload: Hot-Reload can be enabled. When it's enabled, any changes made to JSON file will reflect the running app without needing to re-compile.

Example of a simple button & text

let btn = fa_button(&mut builder, "Press me").build();
let txt = fa_text(&mut builder, "Hello World").build();

want to change button's background color? want to change text's color? you can simply give them an id or class and write the style inside JSON file.

let btn = fa_button(&mut builder, "Press me").id("#btn").build();
let txt = fa_text(&mut builder, "Hello World").id("#txt").build();

{
  "#btn": {
    "background_color": "green"
  },
  "#txt": {
    "color": "blue"
  }
}

That is it!

See simple counter app using famiq

Famiq is still in early stage of development, meaning improvements and optimization are needed, feedbacks & contributions are always welcomed. Currently, it supports bevy 0.15.x onward.

Goals in future:

Add more useful default widgets
Improve documentation
Improve overall performance

Github: https://github.com/MuongKimhong/famiq
Documentation: https://muongkimhong.github.io/famiq/
Crateio: https://crates.io/crates/famiq

Forem: Kim Hong Muong