Cruiser 🏎️

A lively, interactive desktop plugin for Omarchy Linux and Hyprland. A miniature sports car cruises infinitely along your active window borders with realistic exhaust smoke particles, night headlights, live configurable speed and sizing, a status bar quick-toggle, and a visual car selector overlay.

Features

• Smooth Border Driving: Cars dynamically calculate window geometries and rounded corner radii to drift along window edges seamlessly.
• Particle System: Exhaust smoke puffs trail realistically behind the vehicle with drift, drag, buoyancy, and alpha decay.
• Headlights: Projects a single smooth volumetric light beam forward onto window edges based on current speed.
• Visual Car Picker: Summon an elegant overlay menu (or right-click the bar icon) to search and pick between 7 sports cars.
• Status Bar Integration: Click to enable/disable animation instantly; hover to view current active car.
• Live Hot-Reloading: Change car sprite, size, or speed on the fly via files in ~/.config/cruiser/ without reloading Hyprland.
• Linewave Audio Mode: Optionally sync with audio-border to transform borders into audio loudness visualizer dots.

Included Cars

• Lamborghini Countach (White, Red, Yellow)
• Ferrari Testarossa
• Porsche 959
• McLaren 540C
• Lamborghini Urus

Prerequisites & Dependencies

• Hyprland (Aquamarine / Hyprutils compositor)
• Quickshell (Omarchy Quattro shell)
• Build tools: cmake, pkg-config, gcc or clang
• Libraries: pangocairo, libdrm, pixman-1, wayland-server, xkbcommon

Note: No sudo or pkexec is required. The plugin builds and runs entirely in user space.

Installation

From Omarchy Marketplace / CLI

omarchy plugin add https://github.com/JoeJoeflyn/cruiser

Build & Enable Hyprland Plugin

The C++ Hyprland decoration plugin must be compiled once:

cd ~/.config/omarchy/plugins/cruiser
./setup.sh

Load the plugin into your running Hyprland session:

hyprctl plugin load ~/.config/omarchy/plugins/cruiser/cruiser.so

To automatically load Cruiser on boot, add this line to your ~/.config/hypr/autostart.lua:

o.launch_on_start("bash -c 'sleep 2 && hyprctl plugin load " .. os.getenv("HOME") .. "/.config/omarchy/plugins/cruiser/cruiser.so'")

Ensure cruiser is added to your bar widgets in ~/.config/omarchy/shell.json:

"bar": {
  "layout": {
    "right": [
      { "id": "cruiser" }
    ]
  }
}

Usage

Status Bar Widget

• Left-Click: Toggle car animation on or off.
• Right-Click: Open the visual car picker overlay.

Visual Car Picker

Summon the car picker directly via shell IPC:

omarchy-shell shell toggle cruiser

Navigate with arrow keys, type to search, press Enter to select, and Esc to close.

CLI Controls

Switch cars, sizes, and speeds on the fly without restarting:

# List available cars
~/.config/omarchy/plugins/cruiser/cruiser-switch

# Switch car
~/.config/omarchy/plugins/cruiser/cruiser-switch countach_red

# Change car size (height in pixels)
~/.config/omarchy/plugins/cruiser/cruiser-switch size 16

# Change car speed (px/s; negative = reverse, 0 = parked)
~/.config/omarchy/plugins/cruiser/cruiser-switch speed 120

Removal

1. Unload the Hyprland plugin:

   hyprctl plugin unload ~/.config/omarchy/plugins/cruiser/cruiser.so
   

2. Remove from ~/.config/hypr/autostart.lua.
3. Remove the shell plugin:

   omarchy plugin remove cruiser
   

4. (Optional) Remove configuration files:

   rm -rf ~/.config/cruiser
   

License

MIT License. See LICENSE for details.