The Configuration System is an annotation-driven metadata registry that automatically generates a component catalog (config.lua) by scanning source files for special comment annotations. This registry serves as the single source of truth for component metadata, dependencies, and categorization, powering both the build pipeline and the custom installation system.
For information about the build and bundling process, see Build Pipeline. For installation modes and deployment, see Installation.
The Configuration System provides:
@config* annotationsgenerate-config.lua tool scans source files and produces config.luacore, libraries, elements, and plugins@requires and @class annotationsinstall.luaThe Configuration System operates as a build-time code analysis pipeline:
Sources: tools/generate-config.lua1-153 config.lua1-510 install.lua8-21
Component metadata is declared using special comment annotations that are parsed during configuration generation:
| Annotation | Purpose | Example | Default Value |
|---|---|---|---|
@configDescription | Human-readable component description | @configDescription A button element | "" (empty string) |
@configDefault | Whether component is included by default | @configDefault false | true |
@requires | Component dependency (can be repeated) | @requires VisualElement | {} (no dependencies) |
@class | Class inheritance (parsed for dependencies) | @class Button : VisualElement | N/A |
Elements use annotations to declare metadata:
Elements can specify non-default inclusion:
Components can declare multiple dependencies:
Sources: tools/generate-config.lua26-63 config.lua107-444
The generate-config.lua tool implements a four-stage pipeline:
The scanner uses find to recursively locate all .lua files in the source directory, excluding LuaLS.lua.
Sources: tools/generate-config.lua78-100
For each file, parseFile() extracts metadata:
The function uses Lua pattern matching to extract annotation values:
@configDescription: content:match("%-%-%-@configDescription%s*(.-)%s*\n")@configDefault: content:match("%-%-%-@configDefault%s*(%w+)")@requires: content:gmatch("%-%-%-@requires%s*(%w+)")@class: content:match("%-%-%-@class%s*([^%s:]+)%s*:%s*([^%s\n]+)")Sources: tools/generate-config.lua26-63
Files are automatically categorized based on path patterns:
Sources: tools/generate-config.lua65-76
After categorization, the system validates all dependencies:
This ensures that every @requires annotation references an actual component in the system.
Sources: tools/generate-config.lua123-138
The generated config.lua file is a Lua table with two top-level keys:
Each category follows this schema:
From config.lua:
Sources: config.lua1-510
The install.lua script consumes config.lua to implement three installation modes:
Downloads all components from all categories:
Sources: install.lua52-83
Uses config.lua to populate selectable component lists:
The UI presents components with their metadata:
Sources: install.lua343-398 install.lua485-638
The Configuration System tracks two types of dependencies:
@requires)Components explicitly declare dependencies:
This generates:
@class inheritance)Class inheritance automatically adds the parent as a dependency:
The parser extracts the parent class:
The special case parent ~= "PropertySystem" prevents adding PropertySystem as a dependency since it's mixed in rather than inherited.
Sources: tools/generate-config.lua57-60
When a user selects ComboBox in Custom installation, the system automatically includes: ComboBox → DropDown → List → Collection → VisualElement → BaseElement.
Sources: config.lua204-212 config.lua356-364 config.lua426-434
The @configDefault annotation controls whether a component is included by default in installations:
Most core elements are included by default:
| Component | Category | Reason |
|---|---|---|
Button | elements | Common UI element |
Label | elements | Common UI element |
Container | elements | Essential container |
Frame | elements | Essential container |
List | elements | Common data display |
Large or specialized components are opt-in:
| Component | Category | Size (bytes) | Reason |
|---|---|---|---|
TextBox | elements | 43,530 | Large, specialized editor |
Image | elements | 15,117 | Image format dependency |
Display | elements | 4,668 | CC Window API wrapper |
BigFont | elements | 21,551 | Large font renderer |
Graph | elements | 6,933 | Specialized visualization |
ComboBox | elements | 13,613 | Extends DropDown |
DropDown | elements | 7,667 | Extends List |
LineChart | elements | 3,171 | Extends Graph |
Sources: config.lua240-248 config.lua356-372 config.lua400-416
The Configuration System records file sizes for progress indication during installation:
This enables accurate progress bars:
From the generated config:
| Category | Total Files | Total Size (KB) |
|---|---|---|
| core | 7 | ~83 KB |
| libraries | 4 | ~7 KB |
| elements | 39 | ~395 KB |
| plugins | 7 | ~77 KB |
| Total | 57 | ~562 KB |
Sources: tools/generate-config.lua32-34 install.lua58-69
The serialize() function converts the configuration table to valid Lua source code:
This produces human-readable output:
Sources: tools/generate-config.lua4-24
The installer fetches config.lua from the repository:
This enables the installer to work without bundling the full configuration, and ensures it always uses the latest component metadata.
Sources: install.lua4-21
To add a new component to the system:
The component is automatically:
elements (based on path src/elements/DataWidget.lua)config.lua with metadataVisualElement validatedUsers can now:
DataWidget in the Custom installation UIVisualElementSources: tools/generate-config.lua102-147
The Configuration System provides a centralized, annotation-driven approach to component metadata management:
The system bridges the gap between development-time organization and deployment-time needs, enabling users to install exactly the components they need while maintaining dependency integrity.
Sources: tools/generate-config.lua1-153 config.lua1-510 install.lua1-689
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.