No description
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-15 09:52:17 +01:00
docs feat: overhaul BEHEMOTH desktop UI and component showcase 2026-11-15 09:14:54 +01:00
examples fix: execute examples directly without entry function wrappers 2026-11-15 09:52:17 +01:00
scripts fix: execute examples directly without entry function wrappers 2026-11-15 09:52:17 +01:00
showcase feat: overhaul BEHEMOTH desktop UI and component showcase 2026-11-15 09:14:54 +01:00
src/BehemothUI feat: overhaul BEHEMOTH desktop UI and component showcase 2026-11-15 09:14:54 +01:00
tests feat: overhaul BEHEMOTH desktop UI and component showcase 2026-11-15 09:14:54 +01:00
.gitignore Initial commit 2026-11-15 08:08:09 +01:00
.luaurc Initial commit 2026-11-15 08:08:09 +01:00
default.project.json Initial commit 2026-11-15 08:08:09 +01:00
library.project.json Initial commit 2026-11-15 08:08:09 +01:00
luau-analyze Initial commit 2026-11-15 08:08:09 +01:00
lune Initial commit 2026-11-15 08:08:09 +01:00
README.md fix: execute examples directly without entry function wrappers 2026-11-15 09:52:17 +01:00
selene.toml Initial commit 2026-11-15 08:08:09 +01:00
stylua.toml Initial commit 2026-11-15 08:08:09 +01:00

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/BehemothUI to ReplicatedStorage.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

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.