raylib-lua-ui

A lightweight, WoW-inspired Lua UI framework built for Raylib and Lua 5.4.

It enables developers to build data-driven, modular user interfaces inside Raylib games using Lua scripts. The system handles layout anchoring, mouse interaction, event dispatching, and styling, and includes standard UI widgets (Frames, Buttons, Status Bars, FontStrings, Textures, and EditBoxes).

---

Features

• WoW-Like Frame Hierarchy & Layouts: Anchoring with SetPoint, SetAllPoints, and ClearAllPoints.
• Event-Driven Architecture: Queue and dispatch custom game events to Lua with RegisterEvent and lua_system_fire_event.
• Script Callbacks: Support for OnLoad, OnUpdate, OnEvent, OnClick, OnEnter, OnLeave, OnDraw, OnDragStart, OnDragStop, and OnReceiveDrag.
• Standard UI Widgets:
  • Frame: Base container panel.
  • Button: Interactive button with hover and click states.
  • StatusBar: Progress bar (e.g. Health, Mana, Castbar).
  • FontString: Rendered text block with horizontal justification.
  • Texture: Solid color or textured rectangles.
  • EditBox: Single or multi-line text input fields.
• Drag-and-Drop System: Built-in support for dragging frames and tracking drag data.
• State Serialization: Save and restore layout configurations automatically to/from a configuration file (layout.cfg).

---

Documentation

Full detailed documentation is available in the docs/ directory. You can read the Markdown files directly on GitHub or run a Docsify harness to view them as an interactive website.

• Getting Started & Host Integration: Installation, CMake integration, C++ host setup, C bindings, and event dispatching.
• Core UI Concepts: Frame parenting, layout anchoring, strata rendering, and color code formatting.
• Lua API Reference: Globals, rendering namespaces (Draw2D, CCursor), frame methods, widget APIs, and callbacks.
• Layout Persistence: Position auto-saving, state tracking, and draggable frame setup.

---

Compilation & Setup

This library is configured to build with CMake. By default, if Lua 5.4 or Raylib are not found on your system, CMake will automatically download and build them from source.

Option 1: Integrating directly into a CMake Project (Recommended)

Add raylib-lua-ui as a subdirectory (e.g. external/raylib-lua-ui):

add_subdirectory(external/raylib-lua-ui)
target_link_libraries(my_game PRIVATE raylib-lua-ui)

Option 2: Compiling Standalone (Static or Shared Library)

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release

The compiled library will be in build/ (e.g., libraylib-lua-ui.a), and the public headers are in include/ui/.

---

Quick Example (Lua)

Below is a quick overview of how a Lua UI addon looks:

-- Create a main window panel
myWindow = CreateFrame("Frame", "MyWindow", UIParent)
myWindow:SetSize(300, 200)
myWindow:SetPoint("CENTER", UIParent, "CENTER", 0, 0)
myWindow:SetBackdropColor(0.1, 0.1, 0.12, 0.9)
myWindow:SetBackdropBorderColor(0.4, 0.4, 0.5)

-- Create a close button inside the window
closeBtn = CreateFrame("Button", "MyCloseButton", myWindow)
closeBtn:SetSize(80, 30)
closeBtn:SetPoint("BOTTOM", myWindow, "BOTTOM", 0, 15)
closeBtn:SetText("Close")
closeBtn:SetScript("OnClick", function(self)
    myWindow:Hide()
end)

---

License

This project is licensed under the MIT License. See LICENSE for details.