176 lines
4.1 KiB
Markdown
176 lines
4.1 KiB
Markdown
# 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
|
|
|
|
```lua
|
|
local basalt = require("basalt")
|
|
local elementManager = basalt.getElementManager()
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Configure the loading behavior:
|
|
|
|
```lua
|
|
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:
|
|
|
|
```lua
|
|
-- 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:
|
|
|
|
```lua
|
|
-- 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:
|
|
|
|
```lua
|
|
-- 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:
|
|
|
|
```lua
|
|
-- Preload commonly used elements
|
|
elementManager.preloadElements({
|
|
"Button",
|
|
"Label",
|
|
"Frame",
|
|
"Input"
|
|
})
|
|
```
|
|
|
|
## Cache Management
|
|
|
|
When using `useGlobalCache`, elements are cached in `_G` for reuse:
|
|
|
|
```lua
|
|
-- 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
|
|
|
|
```lua
|
|
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:
|
|
|
|
```lua
|
|
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
|