Element Manager

Relevant source files

• BasaltLS.lua
• config.lua
• release/basalt.lua
• src/elementManager.lua
• src/plugins/theme.lua
• src/propertySystem.lua
• tools/bundler.lua

The Element Manager is the core component responsible for discovering, loading, caching, and registering UI elements and plugins in Basalt2. It handles element lifecycle management, plugin integration, and supports multiple loading sources including local files, disk mounts, and remote HTTP sources.

For information about the plugin architecture and extension points, see Plugin Architecture. For details on individual element classes, see Element Hierarchy.

---

Overview

The Element Manager provides a centralized registry and loading system for all UI elements in Basalt2. It discovers elements from multiple sources, applies plugins through a hook system, and maintains both in-memory and optional global caches to optimize performance.

Key Responsibilities:

• Discover and register elements from local directories, disk mounts, and remote sources
• Load elements on-demand with dependency resolution
• Apply plugin hooks and mixins to element classes
• Manage element caching strategies (in-memory and global _G cache)
• Provide configuration for auto-loading and source prioritization

Sources: src/elementManager.lua1-451

---

Architecture

Element Manager Structure

Sources: src/elementManager.lua14-28

---

Element Discovery and Registration

The Element Manager discovers elements during initialization by scanning multiple sources in a specific order.

Discovery Pipeline

Local Element Discovery: src/elementManager.lua33-48

Minified Bundle Discovery: src/elementManager.lua73-85

Sources: src/elementManager.lua30-105

---

Element Loading System

Loading Pipeline with Multiple Sources

Source Loading Implementation

Local Loading: src/elementManager.lua295-298

Disk Loading: src/elementManager.lua222-236

Remote Loading: src/elementManager.lua194-220

Sources: src/elementManager.lua194-364

---

Plugin Application System

Plugin Hook Mechanism

Hook Application Code

Hook Wrapping Logic: src/elementManager.lua327-362

Plugin Discovery and Registration: src/elementManager.lua50-71

Sources: src/elementManager.lua50-71 src/elementManager.lua327-362

---

Configuration System

Configuration Options

Property	Type	Default	Description
autoLoadMissing	boolean	false	Automatically try to load elements from available sources when not found
allowRemoteLoading	boolean	false	Enable loading elements from HTTP URLs
allowDiskLoading	boolean	true	Enable loading elements from disk mounts
remoteSources	table	{}	Map of element names to remote URLs
diskMounts	table	{}	List of disk mount paths to scan for elements
useGlobalCache	boolean	false	Enable caching elements in _G[globalCacheName]
globalCacheName	string	"_BASALT_ELEMENT_CACHE"	Name of the global cache variable

Configuration Structure: src/elementManager.lua20-28

Sources: src/elementManager.lua20-28

---

Caching Mechanism

Cache Strategy

Cache Implementation

Save to Cache: src/elementManager.lua107-116

Load from Cache: src/elementManager.lua118-128

Cache Management Functions: src/elementManager.lua414-449

Sources: src/elementManager.lua107-128 src/elementManager.lua414-449

---

Auto-Loading System

Auto-Load Priority

Auto-Load Implementation: src/elementManager.lua238-268

Sources: src/elementManager.lua238-268

---

API Reference

Core Functions

ElementManager.loadElement(name)

• Loads an element and applies plugins
• Parameters: name (string) - Element name
• Throws error if element not found and auto-loading disabled
• src/elementManager.lua270-364

ElementManager.getElement(name)

• Gets a loaded element class, loading it if necessary
• Parameters: name (string) - Element name
• Returns: Element class table
• src/elementManager.lua366-385

ElementManager.configure(config)

• Updates configuration options
• Parameters: config (table) - Configuration options to update
• src/elementManager.lua130-138

ElementManager.registerDiskMount(mountPath)

• Registers a disk mount for element loading
• Parameters: mountPath (string) - Path to disk mount
• Scans mount for available elements
• src/elementManager.lua140-167

ElementManager.registerRemoteSource(elementName, url)

• Registers a remote URL for an element
• Parameters: elementName (string), url (string)
• Requires allowRemoteLoading = true
• src/elementManager.lua169-192

Utility Functions

ElementManager.hasElement(name)

• Checks if element is registered
• Returns: boolean
• src/elementManager.lua400-405

ElementManager.isElementLoaded(name)

• Checks if element is loaded
• Returns: boolean
• src/elementManager.lua407-412

ElementManager.getElementList()

• Returns all registered elements
• Returns: table of element metadata
• src/elementManager.lua387-391

ElementManager.getAPI(name)

• Gets a plugin API by name
• Parameters: name (string) - Plugin name
• Returns: API table or nil
• src/elementManager.lua393-398

Cache Management

ElementManager.clearGlobalCache()

• Clears the global element cache
• src/elementManager.lua414-421

ElementManager.getCacheStats()

• Returns cache statistics
• Returns: {size: number, elements: string[]}
• src/elementManager.lua423-439

ElementManager.preloadElements(elementNames)

• Preloads elements into cache
• Parameters: elementNames (table) - Array of element names
• src/elementManager.lua441-449

Sources: src/elementManager.lua130-449

---

Element Metadata Structure

Each element in _elements registry has the following structure:

Example Registry Entry:

Sources: src/elementManager.lua39-45 src/elementManager.lua315-321

---

Minified Bundle Integration

In the minified release/basalt.lua, the Element Manager integrates with the bundler's custom require() system.

Minified Bundle Structure: release/basalt.lua1-52

The Element Manager detects minified == true and registers elements from minified_elementDirectory: src/elementManager.lua73-85

Sources: release/basalt.lua1-52 src/elementManager.lua73-105