Loader Library

Core initialization and module loading system for the Lilia framework.

---

Overview

The loader library is the core initialization system for the Lilia framework, responsible for managing the loading sequence of all framework components, modules, and dependencies. It handles file inclusion with proper realm detection (client, server, shared), manages module loading order, provides compatibility layer support for third-party addons, and includes update checking functionality. The library ensures that all framework components are loaded in the correct order and context, handles hot-reloading during development, and provides comprehensive logging and error handling throughout the initialization process. It also manages entity registration for weapons, tools, effects, and custom entities, and provides Discord webhook integration for logging and notifications.

---

lia.loader.include(path, realm)

Include a Lua file with realm auto-detection and AddCSLuaFile handling.

Throughout bootstrap to load framework, module, and compatibility files.

Parameters:

string path File path.

string realm optional "server" | "client" | "shared". Auto-detected from filename if nil.

Example Usage:

    -- Force client-only include for a UI helper.
    lia.loader.include("lilia/gamemode/core/ui/cl_helper.lua", "client")
    -- Auto-detect realm from prefix (sv_/cl_/sh_).
    lia.loader.include("schema/plugins/sv_custom.lua")

---

lia.loader.includeDir(dir, raw, deep, realm)

Include every Lua file in a directory; optionally recurse subfolders.

To load plugin folders or schema-specific directories.

Parameters:

string dir Directory relative to gamemode root unless raw=true.

boolean raw optional If true, treat dir as absolute (no schema/gamemode prefix).

boolean deep optional If true, recurse into subfolders.

string realm optional Force realm for all files; auto-detect when nil.

Example Usage:

    -- Load all schema hooks recursively.
    lia.loader.includeDir("schema/hooks", false, true)

---

lia.loader.includeGroupedDir(dir, raw, recursive, forceRealm)

Include a directory grouping files by realm (sv_/cl_/sh_) with optional recursion.

Loading modular folders (e.g., plugins, languages, meta) with mixed realms.

Parameters:

string dir Directory relative to gamemode root unless raw=true.

boolean raw optional If true, treat dir as absolute.

boolean recursive optional Recurse into subfolders when true.

string forceRealm optional Override realm detection for all files.

Example Usage:

    -- Load all plugin folders, respecting sv_/cl_/sh_ prefixes.
    lia.loader.includeGroupedDir("schema/plugins", false, true)

---

lia.loader.checkForUpdates()

Check framework and module versions against remote manifests.

During startup or by admin command to report outdated modules.

Example Usage:

    concommand.Add("lia_check_updates", function(ply)
        if not IsValid(ply) or ply:IsAdmin() then
            lia.loader.checkForUpdates()
        end
    end)

---

lia.error(msg)

Logs an error message to the console with proper formatting and color coding.

Called throughout the framework when errors occur that need to be logged to the console for debugging purposes.

Parameters:

string msg The error message to display in the console.

Example Usage:

    -- Log an error when a required file fails to load
    lia.error("Failed to load configuration file: config.json not found")

---

lia.warning(msg)

Logs a warning message to the console with proper formatting and color coding.

Called throughout the framework when non-critical issues occur that should be brought to attention but don't stop execution.

Parameters:

string msg The warning message to display in the console.

Example Usage:

    -- Log a warning when an optional dependency is missing
    lia.warning("Optional addon 'advanced_logging' not found, using basic logging instead")

---

lia.information(msg)

Logs an informational message to the console with proper formatting and color coding.

Called throughout the framework to provide general information about system status, initialization progress, or important events.

Parameters:

string msg The informational message to display in the console.

Example Usage:

    -- Log information during system initialization
    lia.information("Database connection established successfully")

---

lia.bootstrap(section, msg)

Logs bootstrap/initialization messages to the console with section categorization and color coding.

Called during the framework initialization process to log progress and status of different loading sections.

Parameters:

string section The name of the bootstrap section being initialized (e.g., "Core", "Modules", "Database").

string msg The message describing what is being initialized or loaded.

Example Usage:

    -- Log bootstrap progress during initialization
    lia.bootstrap("Database", "Connecting to MySQL server...")
    lia.bootstrap("Modules", "Loading character system...")

---

lia.relaydiscordMessage(embed)

Sends formatted messages to a Discord webhook for logging and notifications.

Called when important events need to be relayed to Discord, such as server status updates, errors, or administrative actions.

Parameters:

table embed A Discord embed object containing message details. Supports fields like title, description, color, timestamp, footer, etc.

Example Usage:

    -- Send a notification when a player achieves something special
    lia.relaydiscordMessage({
        title = "Achievement Unlocked!",
        description = player:Name() .. " unlocked the 'Master Trader' achievement",
        color = 16776960, -- Yellow
        timestamp = os.date("!%Y-%m-%dT%H:%M:%SZ")
    })

---

lia.loader.includeEntities(path)

Include and register scripted entities, weapons, and effects under a path.

During initialization to load custom entities from addons/schema.

Parameters:

string path Base path containing entities/weapons/effects subfolders.

Example Usage:

    -- Load schema-specific entities.
    lia.loader.includeEntities("schema/entities")

---

lia.loader.initializeGamemode(isReload)

Initialize modules, apply reload syncs, and announce hot reloads.

On gamemode initialize and OnReloaded; supports hot-reload flow.

Parameters:

boolean isReload true when called from OnReloaded.

Example Usage:

    -- Called automatically from GM:Initialize / GM:OnReloaded.
    lia.loader.initializeGamemode(false)

---