Skip to content

Modularity Library

This page documents the functions for working with modules and modularity.

Overview

The modularity library (lia.module) provides a comprehensive system for managing modules, module loading, and module initialization in the Lilia framework, serving as the core architecture for the framework's extensible and modular design. This library handles sophisticated module management with support for dynamic module loading, dependency resolution, and automatic initialization sequences that ensure proper module startup order and inter-module communication. The system features advanced module loading with support for hot-reloading during development, lazy loading for performance optimization, and conditional loading based on server configuration or player requirements. It includes comprehensive module registration with validation systems, version checking, and compatibility verification to ensure stable module integration and prevent conflicts. The library provides robust module management functionality with lifecycle hooks, state tracking, and error handling to maintain system stability even when individual modules fail or are removed. Additional features include module discovery and auto-registration, dependency graph visualization for debugging, and integration with the framework's configuration system for flexible module management, making it essential for creating maintainable and extensible server configurations that can adapt to different needs and scale with growing communities.

load

Purpose

Loads a module by its unique identifier and path.

Parameters

  • uniqueID (string): The unique identifier of the module.
  • path (string): The filesystem path to the module directory.
  • isSingleFile (boolean, optional): Whether the module is loaded from a single file.
  • variable (string, optional): The variable name to use for the module table (default: "MODULE").
  • skipSubmodules (boolean, optional): Whether to skip loading submodules.

Returns

None

Realm

Server.

Example Usage

-- Load a module by unique ID and path
local function loadModule(uniqueID, path)
    lia.module.load(uniqueID, path)
end

-- Use in a function
local function loadPlayerModule()
    lia.module.load("player", "gamemode/modules/player")
    print("Player module loaded")
end

-- Use in a function
local function loadInventoryModule()
    lia.module.load("inventory", "gamemode/modules/inventory")
    print("Inventory module loaded")
end

-- Load a single-file module
local function loadSingleFileModule()
    lia.module.load("mymodule", "gamemode/modules/mymodule.lua", true)
    print("Single-file module loaded")
end

initialize

Purpose

Initializes all modules in the framework, including the schema, preload modules, and gamemode modules.

Parameters

None

Returns

None

Realm

Server.

Example Usage

-- Initialize all modules
local function initializeAllModules()
    lia.module.initialize()
    print("All modules initialized")
end

-- Use in a hook
hook.Add("Initialize", "InitializeModules", function()
    lia.module.initialize()
    print("Framework modules initialized")
end)

-- Use in a function
local function reloadAllModules()
    lia.module.initialize()
    print("All modules reloaded")
end

loadFromDir

Purpose

Loads all modules from a directory, optionally skipping specific modules.

Parameters

  • directory (string): The directory path to load modules from.
  • group (string, optional): The variable name to use for modules (default: "MODULE").
  • skip (table, optional): Table of module IDs to skip loading.

Returns

None

Realm

Server.

Example Usage

-- Load modules from directory
local function loadModules(directory)
    lia.module.loadFromDir(directory)
end

-- Use in a function
local function loadAllModules()
    lia.module.loadFromDir("gamemode/modules/")
    print("All modules loaded from directory")
end

-- Use in a function
local function loadModulesSkipSome()
    local skipList = {
        ["disabled_module"] = true,
        ["test_module"] = true
    }
    lia.module.loadFromDir("gamemode/modules/", "MODULE", skipList)
    print("Modules loaded, skipping some")
end

-- Use with custom variable name
local function loadModulesCustomVar()
    lia.module.loadFromDir("gamemode/modules/", "MYMODULE")
    print("Modules loaded with custom variable name")
end

get

Purpose

Gets a module by name.

Parameters

  • moduleName (string): The module name.

Returns

  • module (table): The module data or nil.

Realm

Shared.

Example Usage

-- Get a module
local function getModule(moduleName)
    return lia.module.get(moduleName)
end

-- Use in a function
local function checkModuleExists(moduleName)
    local module = lia.module.get(moduleName)
    if module then
        print("Module exists: " .. moduleName)
        return true
    else
        print("Module not found: " .. moduleName)
        return false
    end
end

Definitions

Module Fields

This document describes the default MODULE fields provided by the Lilia framework. Use these to configure module metadata, dependencies, loading behavior, and lifecycle hooks.

Unspecified fields will use sensible defaults.

Overview

A MODULE table defines a self-contained add-on for the Lilia framework. Each field controls how the module is identified, loaded, and interacts with permissions and workshop content.

Field Summary

Field Type Default Description
name string "Unknown" Identifies the module in logs and UI.
author string "Anonymous" Name or SteamID64 of the module's author.
discord string "" Discord tag or support channel.
version number 0 Version number for compatibility checks.
desc string "No Description" Short description of module functionality.
WorkshopContent table nil Steam Workshop add-on IDs required.
enabled boolean or function true Controls whether the module loads.
Dependencies table nil Files or directories included before the module loads.
folder string "" Filesystem path where the module resides.
path string "" Absolute path to the module's root directory.
uniqueID string "" Internal identifier for the module list. Prefix with public_ or private_ to opt into version checks.
loading boolean false True while the module is in the process of loading.
ModuleLoaded function nil Callback run after module finishes loading.
Privileges table nil CAMI privileges required by the module.
isSingleFile boolean false True if the module is loaded from a single file.
variable string "MODULE" Variable name used to access the module table.
CharacterInformation table nil Custom character information fields for the F1 menu.
ActiveTickets table nil Active support tickets in the ticket system.
adminStickCategories table nil Categories for admin stick tools.
adminStickCategoryOrder table nil Order of admin stick tool categories.
panel Panel nil Reference to the module's UI panel.
loadedData boolean false True when the module's data has been loaded.
versionID string nil Version identifier for update checking.
NetworkStrings table nil Network string identifiers used by the module.
WebImages table nil Web image URLs for caching.
WebSounds table nil Web sound URLs for caching.

Field Details

Identification & Metadata

name

Type:

string

Description:

Identifies the module in logs and UI elements.

Example Usage:

MODULE.name = "My Module"

author

Type:

string

Description:

Name or SteamID64 of the module's author.

Example Usage:

MODULE.author = "Samael"

discord

Type:

string

Description:

Discord tag or support channel for the module.

Example Usage:

MODULE.discord = "@liliaplayer"

desc

Type:

string

Description:

Detailed description of what the module provides and why it exists.

Example Usage:

MODULE.desc = "Adds an advanced chat system with channels and admin tools."

Version & Compatibility

version

Type:

number

Description:

Version number used for compatibility checks.

Example Usage:

MODULE.version = 1.0

Dependencies & Content

WorkshopContent

Type:

table

Description:

Steam Workshop add-on IDs required by this module.

Example Usage:

MODULE.WorkshopContent = {
    "1234567890", -- shared assets
    "0987654321"  -- map data
}

Privileges

Type:

table

Description:

CAMI privileges required by the module. These are automatically registered with the CAMI system when the module loads.

Example Usage:

MODULE.Privileges = {
    {
        Name = "Staff Permissions - Admin Chat",
        MinAccess = "admin"
    },
    {
        Name = "Moderation - Kick Players",
        MinAccess = "moderator"
    }
}

Dependencies

Type:

table

Description:

List of additional files or directories to include before the module itself

loads. Paths are relative to the module's folder. Each entry may specify a

File or Folder key along with an optional Realm value (server, client

or shared) to control where the code is executed.

Example Usage:

MODULE.Dependencies = {
    { File = "logs.lua", Realm = "server" },
    { Folder = "libs", Realm = "shared" },
}

Loading & Lifecycle

enabled

Type:

boolean or function

Description:

Controls whether the module loads. Can be a static boolean or a function returning a boolean.

When the function form is used, it may optionally return a second string

explaining why the module is disabled. This message is displayed through

lia.bootstrap when the loader skips the module.

When a module is disabled or skipped, you will see a console message in the format:

[Lilia] [Bootstrap] [Module Disabled/Skipped] <reason>.

Example Usage:

-- Enabled by default
MODULE.enabled = true

-- Or evaluate a configuration value
MODULE.enabled = function()
    return lia.config.get("EnableMyModule", true)
end

-- Provide a custom disable reason
MODULE.enabled = function()
    return false, "Disabled Temporarily"
end

loading

Type:

boolean

Description:

True while the module is in the process of loading.

Example Usage:

if MODULE.loading then return end

ModuleLoaded

Type:

function

Description:

Optional callback run after the module finishes loading.

Example Usage:

function MODULE:ModuleLoaded()
    print("Module fully initialized")
end

isSingleFile

Type:

boolean

Description:

True if the module is loaded from a single file rather than a directory structure.

Example Usage:

if MODULE.isSingleFile then
    -- Handle single-file module loading
end

variable

Type:

string

Description:

The variable name used to access the module table (usually "MODULE").

Example Usage:

print("Module variable:", MODULE.variable) -- Output: MODULE

CharacterInformation

Type:

table

Description:

Custom character information fields displayed in the F1 menu's character information panel.

Example Usage:

MODULE.CharacterInformation = {
    {
        name = "Health",
        data = function(client) return client:Health() end
    }
}

ActiveTickets

Type:

table

Description:

Active support tickets in the ticket system module, keyed by SteamID.

Example Usage:

local ticket = MODULE.ActiveTickets[client:SteamID()]
if ticket then
    -- Handle existing ticket
end

adminStickCategories

Type:

table

Description:

Categories for organizing admin stick tools, used by the admin stick module.

Example Usage:

MODULE.adminStickCategories = {
    playerInfo = {
        name = "Player Information",
        icon = "icon16/user.png"
    }
}

adminStickCategoryOrder

Type:

table

Description:

Defines the display order of admin stick tool categories.

Example Usage:

MODULE.adminStickCategoryOrder = {"playerInformation", "moderation", "characterManagement"}

panel

Type:

Panel

Description:

Reference to the module's main UI panel (e.g., chatbox panel).

Example Usage:

if IsValid(MODULE.panel) then
    MODULE.panel:Remove()
end

loadedData

Type:

boolean

Description:

Indicates whether the module's persistent data has been loaded from the database.

Example Usage:

if not MODULE.loadedData then return end
-- Safe to access module data

versionID

Type:

string

Description:

Unique version identifier for update checking. Prefix with public_ or private_ to enable automatic version checks.

Example Usage:

MODULE.versionID = "public_mymodule"
MODULE.version = 1.2

NetworkStrings

Type:

table

Description:

Network string identifiers used by the module for client-server communication.

Example Usage:

MODULE.NetworkStrings = {
    "MyModuleData",
    "MyModuleAction"
}

WebImages

Type:

table

Description:

URLs of web images to be cached by the framework for use in the module.

Example Usage:

MODULE.WebImages = {
    logo = "https://example.com/logo.png",
    icon = "https://example.com/icon.png"
}

WebSounds

Type:

table

Description:

URLs of web sounds to be cached by the framework for use in the module.

Example Usage:

MODULE.WebSounds = {
    notification = "https://example.com/sound.mp3",
    alert = "https://example.com/alert.wav"
}

Access & Visibility

folder

Type:

string

Description:

Relative directory of the module within the gamemode or add-on. Useful when including other files from this module.

Example Usage:

print(MODULE.folder)

path

Type:

string

Description:

Full filesystem path to the module's directory. Usually set automatically by the loader.

Example Usage:

print(MODULE.path)

uniqueID

Type:

string

Description:

Identifier used internally for the module list. Prefix with public_ or private_ to enable public or private version checks.

Example Usage:

print(MODULE.uniqueID)

Default Folder Load Order

When loading a module from a directory, Lilia automatically scans for common sub-folders and includes them in a specific sequence. Files in these folders run on the appropriate realm, letting you simply drop code into place. The loader processes the following paths in order:

  1. languages

  2. factions

  3. classes

  4. attributes

  5. pim.lua, client.lua, server.lua, config.lua and commands.lua

  6. config

  7. dependencies

  8. libs

  9. hooks

  10. libraries

  11. commands

  12. netcalls

  13. meta

  14. derma

  15. pim

  16. entities

  17. items

  18. submodules (each loaded as its own module)

Example module.lua

A complete example showing common fields in use:

-- example/gamemode/modules/public_myfeature/module.lua
MODULE.name = "My Feature"
MODULE.author = "76561198012345678"
MODULE.discord = "@example"
MODULE.version = 1.0
MODULE.desc = "Adds an example feature used to demonstrate module creation."

MODULE.enabled = true

MODULE.WorkshopContent = {
    "1234567890"
}

MODULE.Privileges = {
    { Name = "My Feature - Use", MinAccess = "admin" }
}

MODULE.Dependencies = {
    { File = "hooks.lua", Realm = "server" },
    { Folder = "libraries", Realm = "shared" }
}

function MODULE:ModuleLoaded()
    print("My Feature loaded!")
end
```