toolkit-ry

Game UI Toolkit for Ry-Dit - HUD, Menus, Dialogs, Inventory + 5 Pre-built Themes

Overview

toolkit-ry is a comprehensive UI toolkit for building game interfaces in Rust. Built on top of migui (immediate mode GUI) and SDL2, it provides ready-to-use widgets for health bars, mana bars, inventory systems, dialog boxes, menus, loading screens, minimaps, and more.

Includes 5 pre-built visual themes (Dark, Light, Retro, Neon, Minimal) that can be customized or used out of the box.

Features

🎨 5 Pre-built Themes

📊 HUD Widgets

• Health Bar (HP) - With label and dynamic color
• Mana Bar (MP) - Magic/stamina resource
• XP Bar - Experience/progress tracking
• Score Display - Points counter
• Gold/Currency - Money display (with emoji 🪙)
• Timer - MM:SS format countdown
• Full HUD - Combined HP + MP + XP + Score in one call

🎮 Menu Systems

• Main Menu - Title + options with hover states
• Pause Menu - Continue, Options, Save, Exit
• Game Over - Score display + restart/menu options
• Options Menu - Volume slider, fullscreen toggle
• Loading Screen - Progress bar + percentage

💬 Dialog & Notifications

• NPC Dialog - Character name + text box
• Message Box - Confirmation dialogs with buttons
• Notifications - Toast-style popups

🎒 Inventory System

• Inventory Slot - Individual item with count
• Inventory Grid - Configurable cols × rows grid
• Item selection and hover states
• Stack count display

🗺️ Minimap

• Player position indicator
• Scaled to world coordinates
• Customizable size

Installation

[dependencies]
toolkit-ry = "0.1.0"
migui = "0.4.1"
sdl2 = "0.37"

Quick Start

Basic Health Bar

use toolkit_ry::theme::Theme;
use toolkit_ry::widgets::*;

// Create a migui instance (assuming you have SDL2 + migui setup)
// let mut gui = migui::Migui::new();

let theme = Theme::dark();

draw_health_bar(
    &mut gui,
    20.0,  // x position
    20.0,  // y position
    200.0, // width
    18.0,  // height
    75.0,  // current HP
    100.0, // max HP
    &theme,
);

Full HUD in One Call

use toolkit_ry::theme::Theme;
use toolkit_ry::widgets::draw_full_hud;

let theme = Theme::dark();

draw_full_hud(
    &mut gui,
    75.0,   // current HP
    100.0,  // max HP
    50.0,   // current MP
    100.0,  // max MP
    150.0,  // current XP
    200.0,  // max XP
    12500,  // score
    &theme,
);

Main Menu

use toolkit_ry::theme::Theme;
use toolkit_ry::widgets::draw_main_menu;

let theme = Theme::retro();
let mut hover_state = -1;

let selected = draw_main_menu(
    &mut gui,
    "MY AWESOME GAME",
    &["Start Game", "Options", "Quit"],
    &theme,
    &mut hover_state,
);

if selected >= 0 {
    println!("Menu option {} selected!", selected);
}

Inventory Grid

use toolkit_ry::theme::Theme;
use toolkit_ry::widgets::draw_inventory_grid;

let theme = Theme::dark();
let mut selected_slot = 0;

// Create inventory items
let items = vec![
    Some(("Sword".to_string(), 1)),
    Some(("Potion".to_string(), 5)),
    None, // Empty slot
    Some(("Key".to_string(), 1)),
    // ... up to cols × rows items
];

let selected = draw_inventory_grid(
    &mut gui,
    100.0,  // x
    100.0,  // y
    4,      // columns
    3,      // rows
    50.0,   // slot size
    4.0,    // spacing
    &items,
    &mut selected_slot,
    &theme,
);

Dialog with NPC

use toolkit_ry::theme::Theme;
use toolkit_ry::widgets::draw_dialog;

let theme = Theme::light();

draw_dialog(
    &mut gui,
    "Old Wizard",           // NPC name
    "Ah, a young adventurer! I have a quest for you...",
    50.0,   // x
    400.0,  // y
    700.0,  // width
    150.0,  // height
    &theme,
);

Loading Screen

use toolkit_ry::theme::Theme;
use toolkit_ry::widgets::draw_loading;

let theme = Theme::neon();

// Update progress each frame (0.0 to 1.0)
let progress = 0.65; // 65% loaded
draw_loading(&mut gui, "Loading world...", progress, &theme);

Minimap

use toolkit_ry::theme::Theme;
use toolkit_ry::widgets::draw_minimap;

let theme = Theme::dark();

draw_minimap(
    &mut gui,
    1100.0, // x (top-right corner)
    20.0,   // y
    150.0,  // size
    500.0,  // player x in world
    300.0,  // player y in world
    2000.0, // world width
    1500.0, // world height
    &theme,
);

API Reference

Theme System

pub struct Theme {
    pub name: &'static str,
    // Colors
    pub bg_color: ColorRGBA,
    pub panel_bg: ColorRGBA,
    pub text_color: ColorRGBA,
    // ... 30+ configurable properties
}

impl Theme {
    pub fn dark() -> Self;
    pub fn light() -> Self;
    pub fn retro() -> Self;
    pub fn neon() -> Self;
    pub fn minimal() -> Self;
    
    pub fn by_name(name: &str) -> Self;
    pub fn all() -> &'static [fn() -> Self];
}

ColorRGBA

pub struct ColorRGBA {
    pub r: u8,
    pub g: u8,
    pub b: u8,
    pub a: u8,
}

impl ColorRGBA {
    pub const fn new(r: u8, g: u8, b: u8, a: u8) -> Self;
    pub const fn rgb(r: u8, g: u8, b: u8) -> Self;
    pub const fn transparent() -> Self;
}

Widget Functions

HUD

Menus

Dialogs

Inventory

Other

Theme Customization

All theme properties are public, so you can easily create your own:

use toolkit_ry::theme::{Theme, ColorRGBA};

let my_theme = Theme {
    name: "My Custom Theme",
    bg_color: ColorRGBA::rgb(50, 50, 100),
    health_bar_fill: ColorRGBA::rgb(0, 255, 0),
    font_size: 18,
    ..Theme::dark() // Inherit dark theme as base
};

Dependencies

Examples

Complete Game Menu Flow

use toolkit_ry::theme::Theme;
use toolkit_ry::widgets::*;

enum GameState {
    MainMenu,
    Options,
    Playing,
    Paused,
    GameOver,
}

fn render_menu(gui: &mut migui::Migui, state: &mut GameState, theme: &Theme) {
    let mut hover = -1;
    
    match state {
        GameState::MainMenu => {
            let selected = draw_main_menu(
                gui,
                "EPIC QUEST",
                &["New Game", "Options", "Quit"],
                theme,
                &mut hover,
            );
            
            match selected {
                0 => *state = GameState::Playing,
                1 => *state = GameState::Options,
                2 => std::process::exit(0),
                _ => {}
            }
        }
        GameState::Paused => {
            let selected = draw_pause_menu(gui, theme, &mut hover);
            if selected == 0 {
                *state = GameState::Playing; // Continue
            }
        }
        GameState::GameOver => {
            let selected = draw_game_over(gui, 15000, theme, &mut hover);
            if selected == 0 {
                *state = GameState::Playing; // Restart
            }
        }
        _ => {}
    }
}

RPG HUD Example

// Full HUD with HP/MP/XP bars
let theme = Theme::retro();
draw_full_hud(
    &mut gui,
    120.0,  // HP: 120/150
    150.0,
    45.0,   // MP: 45/80
    80.0,
    230.0,  // XP: 230/500
    500.0,
    8750,   // Score
    &theme,
);

// Add timer and gold
draw_timer(&mut gui, 600.0, 720.0, 345.0, &theme); // 5:45
draw_gold(&mut gui, 600.0, 50.0, 1250, &theme);    // 🪙 1250

Performance

• Immediate mode - No retained state overhead
• Zero allocations in widget drawing (pure rendering)
• Theme system is copy-based (ColorRGBA is Copy)
• 10 unit tests ensuring widget correctness

Roadmap

• Scrollable panels
• Text input fields
• Dropdown menus
• Tooltip system
• Animated transitions
• Theme serialization (JSON/TOML)
• Custom widget macro
• Responsive layouts

Contributing

Contributions are welcome! This crate is part of the Ry-Dit game engine project.

• Repository: https://github.com/lapumlbb18-blip/Ry-dit
• Issues: https://github.com/lapumlbb18-blip/Ry-dit/issues
• Pull Requests: Welcome!

Please read CONTRIBUTING.md for guidelines.

License

MIT License - See LICENSE for details.

Related Crates

toolkit-ry - Build game UIs faster with pre-built widgets and themes 🎮✨

5 themes · 20+ widgets · HUD · Menus · Inventory · Dialogs