Element Loading System

Basalt's Element Loading System allows you to load elements from different sources: local files, disk mounts, and even directly from the web.

Getting the Element Manager

local basalt = require("basalt")
local elementManager = basalt.getElementManager()

Configuration

Configure the loading behavior:

elementManager.configure({
    autoLoadMissing = true,           -- Auto-load elements that aren't found
    allowRemoteLoading = true,        -- Enable loading from URLs
    allowDiskLoading = true,          -- Enable loading from disk mounts
    useGlobalCache = true,            -- Cache loaded elements in _G
    globalCacheName = "_BASALT_CACHE" -- Name of the global cache variable
})

Loading from Disk

Register disk mount points to load elements from external locations:

-- Register a disk mount
elementManager.registerDiskMount("/disk/basalt-elements")

-- Elements in /disk/basalt-elements/elements/ are now available
local main = basalt.getMainFrame()
local customButton = main:addCustomButton()  -- Loads from disk

Loading from Remote URLs

Load elements directly from the web:

-- Enable remote loading
elementManager.configure({
    allowRemoteLoading = true
})

-- Register a remote source
elementManager.registerRemoteSource(
    "CustomElement",
    "https://example.com/elements/CustomElement.lua"
)

-- Use the element
local main = basalt.getMainFrame()
local custom = main:addCustomElement()

Manual Element Loading

Load elements manually when needed:

-- Load a specific element
elementManager.loadElement("Button")

-- Get an element (loads it if not already loaded)
local ButtonClass = elementManager.getElement("Button")

-- Check if an element exists
if elementManager.hasElement("CustomWidget") then
    elementManager.loadElement("CustomWidget")
end

-- Check if an element is loaded
if not elementManager.isElementLoaded("Label") then
    elementManager.loadElement("Label")
end

Preloading Elements

Preload multiple elements at startup for better performance:

-- Preload commonly used elements
elementManager.preloadElements({
    "Button",
    "Label",
    "Frame",
    "Input"
})

Cache Management

When using useGlobalCache, elements are cached in _G for reuse:

-- Get cache statistics
local stats = elementManager.getCacheStats()
print("Cached elements: " .. stats.size)
for _, name in ipairs(stats.elements) do
    print("- " .. name)
end

-- Clear the cache
elementManager.clearGlobalCache()

Complete Example

local basalt = require("basalt")
local elementManager = basalt.getElementManager()

-- Configure loading system
elementManager.configure({
    autoLoadMissing = true,
    allowRemoteLoading = true,
    allowDiskLoading = true,
    useGlobalCache = true
})

-- Register disk mount for custom elements
if fs.exists("/disk") then
    elementManager.registerDiskMount("/disk")
end

-- Register remote element
elementManager.registerRemoteSource(
    "SpecialButton",
    "https://raw.githubusercontent.com/user/repo/main/SpecialButton.lua"
)

-- Preload common elements
elementManager.preloadElements({"Button", "Label", "Frame"})

-- Use elements normally
local main = basalt.getMainFrame()

local btn = main:addButton()
    :setText("Standard Button")
    :setPosition(2, 2)

-- This will be loaded from disk or remote if available
local special = main:addSpecialButton()
    :setText("Special Button")
    :setPosition(2, 4)

basalt.run()

Use Cases

Remote Element Library

Load elements from a central repository:

local repository = "https://raw.githubusercontent.com/Basalt2/main/src/elements/"

elementManager.configure({allowRemoteLoading = true})
elementManager.registerRemoteSource("Chart", repository .. "Chart.lua")
elementManager.registerRemoteSource("DataGrid", repository .. "DataGrid.lua")

Notes

• Remote loading requires HTTP API to be enabled in CC:Tweaked config
• Disk loading looks for elements/ subfolder in the mount path
• Elements must follow Basalt's element structure
• Global cache persists across basalt.run() calls if not cleared
• Auto-loading tries disk mounts first, then remote sources