- Luau 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| docs | ||
| examples | ||
| scripts | ||
| showcase | ||
| src/BehemothUI | ||
| tests | ||
| .gitignore | ||
| .luaurc | ||
| default.project.json | ||
| library.project.json | ||
| luau-analyze | ||
| lune | ||
| README.md | ||
| selene.toml | ||
| stylua.toml | ||
BehemothUI
A modular, themeable, animated GUI framework for Roblox, built for the B3H3M0TH project and usable in any experience, Studio plugin or developer tool.
BEHEMOTH uses a compact desktop workspace: black and charcoal surfaces, readable cool-gray text, restrained violet accents, and precise control geometry. Page headers, bounded forms and responsive columns organize real content. Windows use solid chrome, grouped navigation and uniform window controls; sections use headings and dividers. Daylight and HighContrast remain available.
- Windows: draggable, resizable (8 edges), minimize/maximize/restore, snapping, focus stacking, modal and always-on-top windows, floating tool panels, docks and split panes, remembered geometry, and viewport clamping.
- Navigation: sidebar tabs with groups, search and collapse; top tabs; nested tab strips; nav lists; breadcrumbs; a command palette; context menus; menu bars; keyboard navigation; recently visited pages.
- Components:
- Buttons: every button variant.
- Inputs: text/password/multiline/validated/search, number, slider, range, toggle, checkbox, radio, segmented.
- Pickers: dropdown (single, multi, searchable), keybind, color picker (RGB/HSV/HEX/alpha).
- Content: cards, badges, banners, popovers, accordions, progress bars and rings, avatars, skeletons, grids.
- Data: virtualized list, table, tree and JSON viewer.
- Developer tools: a Luau script editor (layered syntax highlighting, undo/redo, find & replace, tabs, minimap), console, property inspector, graphs, stats, task list, activity feed, status bar and HUD, keybind list, debug panel.
- Feedback: toasts with a queue, stacking, priorities, dedupe, progress and actions; dialogs; banners; notification history.
- Animation engine: tweens, springs, sequence, parallel, stagger, pause/resume/reverse/cancel, interruption-safe property channels, and quality presets (Off → Cinematic) with resource budgets.
- Text effects: 18 effects, including typewriter, scramble, terminal decode, glitch, wave, shimmer, particle assembly and disintegration, scan and mask reveals. Each has budgets and graceful fallbacks.
- Theme engine: token-based, with 6 presets, live accent, component overrides, inheritance, high-contrast and light modes, and JSON import/export.
- Reactive state:
State.Value,State.Computed,State.Batch, two-way component binding, derived visibility and availability. - Icons: a bundled Lucide snapshot with 1,573 icons. Write
Icon = "layout-dashboard"on components that support icons.
Installation
URL loader
In a runtime that provides game:HttpGet and loadstring:
local BehemothUI = loadstring(game:HttpGet("https://repo.samthedev.de/samthedev/SkelUI/raw/branch/main/src/BehemothUI/init.luau"))()
The URL entry is a generated, self-contained library. It includes every module and Lucide data; no BehemothUI folder needs to be installed first. It returns the library table used by BehemothUI.new(...). loadstring compiles source text, so a URL string alone does not fetch or execute the library. See examples/Remote.client.luau for a complete loader and window.
After editing Main.luau or any module, run ./lune run scripts/build.luau and publish the regenerated src/BehemothUI/init.luau with the source changes. Tests reject an outdated generated entry. Publishing is separate from the local build.
Studio / normal LocalScripts (Rojo)
Roblox's normal client LocalScripts do not provide this HTTP/loadstring loading workflow; install the ModuleScript for that environment. Roblox documents loadstring as server-only in its standard engine.
rojo serve default.project.json # library + showcase + tests
# or build only the library model:
rojo build library.project.json -o BehemothUI.rbxm
default.project.json maps:
src/BehemothUItoReplicatedStorage.BehemothUI- the showcase to
StarterPlayerScripts.BehemothShowcase - the tests to
ReplicatedStorage.BehemothUITests
Manual: insert BehemothUI.rbxm into ReplicatedStorage.
The included Lune binary can build that model without installing Rojo:
./lune run scripts/build.luau # regenerates URL entry + dist/BehemothUI.rbxm
BehemothUI uses only standard Roblox APIs. It runs in Studio and in normal client LocalScripts. Studio plugins can use it by passing Parent = dockWidget and Storage = BehemothUI.Storage.Plugin.new(plugin).
For a small runnable example in a client runtime providing game:HttpGet and loadstring, execute Basic.luau directly or load it from the repository URL; see the example run instructions. All examples load the library from the repository URL and open their interface immediately.
See examples/README.md for the basic window, settings panel, component gallery and standalone loader, with instructions for running each.
Quick start
local BehemothUI = loadstring(game:HttpGet("https://repo.samthedev.de/samthedev/SkelUI/raw/branch/main/src/BehemothUI/init.luau"))()
-- Installed ModuleScript alternative: local BehemothUI = require(game.ReplicatedStorage.BehemothUI)
local State = BehemothUI.State
local UI = BehemothUI.new({
Name = "BEHEMOTH", -- re-running replaces the previous instance (no duplicates)
Theme = "Obsidian",
Accent = Color3.fromRGB(161, 138, 250),
AnimationQuality = "Balanced", -- Off | Minimal | Balanced | High | Cinematic
})
local Window = UI:CreateWindow({
Title = "BEHEMOTH",
Size = UDim2.fromOffset(950, 600),
Resizable = true,
ToggleKey = Enum.KeyCode.RightShift,
})
local Tab = Window:CreateTab({ Name = "Dashboard", Icon = "layout-dashboard" })
local Section = Tab:CreateSection({ Title = "General" })
local enabled = State.Value(false)
Section:CreateToggle({
Label = "Example Setting",
Value = enabled, -- two-way bound
Flag = "ExampleSetting", -- included in UI:ExportConfig()
OnChanged = function(value) print(value) end,
})
Section:CreateSlider({ Label = "Speed", Min = 0, Max = 100, Default = 16, Enabled = enabled })
UI:Notify({ Title = "Ready", Content = "The interface has initialized.", Type = "Success", Duration = 4 })
UI:AnimateText({ Target = someTextLabel, Text = "BEHEMOTH INITIALIZED", Effect = "ScrambleReveal", Duration = 1.5 })
Every container (tab, section, card, accordion item, popover, dock, split pane, panel window) supports container:Create<Component>(config) for every registered component. Custom components register with BehemothUI.RegisterComponent(name, module).
Showcase
Press Play in Studio with default.project.json served. The showcase opens with seven primary destinations: Overview, Controls, Navigation, Feedback, Animations, Developer Tools, and Themes. Nested pages preserve the full button/input/picker gallery, text and particle effects, notifications, live theme previews, script editor, console, data views, windows/docking, and stress tests. Selecting a category reveals its child pages; the command palette can open any page. The stress test covers 50 000-row virtualization, console flooding, 300 concurrent tweens, bulk create/destroy, and a repeated-init leak check.
- Press RightShift to toggle the window.
- Press Ctrl+Shift+P to open the command palette.
- Press Ctrl+Tab to cycle pages.
Run the Viewports example in a client runtime providing game:HttpGet and loadstring to exercise real controls at 560×420, 900×620 and 1280×800; see examples/README.md. Column layouts stack on narrow pages and the sidebar automatically compacts unless explicitly expanded. Small forms stay bounded instead of stretching across large windows.
Tests
The tests use a dependency-free runner with unit and integration specs. Unit coverage includes Signal, Maid, State, themes, Animator, icon resolution/swaps, navigation registration, editor models and particle caps. Integration specs cover client lifecycle, windows, navigation, cleanup, state binding, flags and repeated initialization.
./lune run scripts/test.luau # compile + module loading + local unit tests + docs checks + repository URL test
The local adapter does not render Roblox UI or deliver engine input. Run the full client suite in Studio too:
-- Studio Play mode (client), command bar or a LocalScript:
require(game.ReplicatedStorage.BehemothUITests.TestRunner).Run()
-- pure-logic specs only (edit mode / server):
require(game.ReplicatedStorage.BehemothUITests.TestRunner).Run({ UnitOnly = true })
The local command also fetches the published entry with loadstring(game:HttpGet("https://repo.samthedev.de/samthedev/SkelUI/raw/branch/main/src/BehemothUI/init.luau"))() with no installed library and rejects external requires, checks all bundled component factories and Lucide resolution, and verifies repeated loads reuse the library. This checks the version served by the repository and requires network access; local source modules are checked separately by the unit tests. ./lune run scripts/test-bundle.luau runs the repository URL check alone. HTTP or loader failures fail the test; there is no local-file fallback.
Documentation
- docs/DESIGN_SYSTEM.md: desktop tokens, component geometry, focus and layout rules.
- docs/ARCHITECTURE.md: module layout and the component authoring contract.
- docs/API.md: public API reference.
- docs/TEXT_EFFECTS.md: text effects, budgets, fallbacks and Roblox text-rendering limitations.
- docs/EDITOR.md: script editor architecture and limitations.
- docs/NAVIGATION.md: navigation, palette, menus, split panes and docking.
- docs/LIMITATIONS.md: everything Roblox cannot do and what BehemothUI does instead.
Every source file also starts with a usage doc block.
Icons
Icons come from Lucide (ISC). The sprite-sheet asset data is vendored from latte-soft/lucide-roblox (MIT) into src/BehemothUI/Core/Lucide/. BehemothUI.Icons.GetLucideNames() lists the 1,573 bundled names. You can also pass rbxassetid:// strings, or register your own icons with BehemothUI.Icons.Register(name, { Image, RectOffset, RectSize }). See the icon API and asset limitations.
License
No framework source license has been selected in this snapshot. Lucide data: ISC (Lucide) and MIT (lucide-roblox); see src/BehemothUI/Core/Lucide/LICENSE-lucide-roblox.md.