Loader

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)

Purpose

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

When Called

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("modules/sv_custom.lua")

---

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

Purpose

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

When Called

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)

Purpose

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

When Called

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("modules", false, true)

---

lia.loader.checkForUpdates()

Purpose

Check framework and module versions against remote manifests.

When Called

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)

Purpose

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

When Called

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)

Purpose

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

When Called

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)

Purpose

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

When Called

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)

Purpose

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

When Called

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)

Purpose

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

When Called

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)

Purpose

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

When Called

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)

Purpose

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

When Called

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)

---