README.md

Note

This repository has moved to Codeberg.

ugui

Flexible immediate-mode GUI library for Lua

🚀 Quickstart

Download breitbandgraphics-amalgamated.lua and ugui-amalgamated.lua from the latest release and place them anywhere in your project.

Then call dofile for them with their absolute paths:

-- Get the directory where your entry script file is located (Windows, includes trailing backslash)
folder = debug.getinfo(1).source:sub(2):match('(.*\\)')

---@module "breitbandgraphics-amalgamated"
BreitbandGraphics = dofile(folder .. 'breitbandgraphics-amalgamated.lua')

---@module "ugui-amalgamated"
ugui = dofile(folder .. 'ugui-amalgamated.lua')

That's it.
Read the demo scripts for usage examples.

✨ Features

Control Suite

• button
• carrousel_button
• combobox
• joystick
• label
• listbox
  • Scrolling support
  • Unlimited items with no performance degradation
• menu
  • Checkable items
• numberbox
• scrollbar
• spinner
  • Optional negative/positive toggle
• tabcontrol
  • Adjustable magnitude circle
• textbox
• toggle_button
• trackbar

Rendering

Can render using a built-in Windows 10-like style, or with ninesliced images.

Depends on BreitbandGraphics for rendering, which is included in this repository as well (see below).

Hackability

Any part of the library can be overwritten externally. Future compatibility not guaranteed.

🛠️ Building from source

The breitbandgraphics-amalgamated.lua and ugui-amalgamated.lua files are both built via the build.py python script.

Requirements:

• Python >= 3.9 (official download site)
• git bash (as included in Git for Windows)

Build steps:

1. Open a git bash, then clone the repository and navigate into the repository via the following command:

git clone https://github.com/mupen64/ugui.git && cd ./ugui

2. Create a python virtual environment and activate it:

python -m venv ./.venv
source ./.venv/Scripts/activate

Note: The second line must be executed in each new terminal session in order to build.

3. Install dependencies:

pip install -r requirements.txt

4. Run the build script:

python build.py

That's it.
breitbandgraphics-amalgamated.lua and ugui-amalgamated.lua should now have been created in the ./build/ directory.

---

BreitbandGraphics

The rendering abstraction

Backends

Built-in backend for the Mupen64 emulator.

Utilities

Provides various utilities for color conversion and manipulation.