Dialog Library
Comprehensive NPC dialog management system for the Lilia framework.
Overview
The dialog library provides comprehensive functionality for managing NPC conversations and dialog systems in the Lilia framework. It handles NPC registration, conversation filtering, client synchronization, and provides both server-side data management and client-side UI interactions. The library supports complex conversation trees with conditional options, server-only callbacks, and dynamic NPC customization. It includes automatic data sanitization, conversation filtering based on player permissions, and seamless integration with the framework's networking system. The library ensures secure and efficient dialog handling across both server and client realms.
lia.dialog.isTableEqual(tbl1, tbl2, checked)
Performs a deep comparison of two tables to detect changes, avoiding infinite loops from circular references.
Before syncing dialog data to clients to prevent unnecessary network traffic.
Parameters:
table tbl1 First table to compare.table tbl2 Second table to compare.
table checked optional Internal table used to track visited references and prevent cycles.
Returns:
boolean True if tables are identical, false otherwise.Example Usage:
if not lia.dialog.isTableEqual(oldData, newData) then
lia.dialog.syncDialogs()
end
lia.dialog.registerConfiguration(uniqueID, data)
Registers or updates an NPC configuration entry for customization panels.
During gamemode initialization to define available NPC configuration options.
Parameters:
string uniqueID Unique identifier for the configuration.table data Configuration data containing fields like name, order, shouldShow, onOpen, onApply, etc.
Returns:
table The stored configuration table.Example Usage:
lia.dialog.registerConfiguration("shop_inventory", {
name = "Shop Inventory",
order = 5,
shouldShow = function(ply) return ply:IsAdmin() end,
onOpen = function(npc) OpenShopConfig(npc) end
})
lia.dialog.getConfiguration(uniqueID)
Retrieves a registered configuration entry by its unique identifier.
When accessing configuration menus or checking configuration availability.
Parameters:
string uniqueID The unique identifier of the configuration to retrieve.Returns:
table|nil The configuration table if found, nil otherwise.Example Usage:
local cfg = lia.dialog.getConfiguration("appearance")
if cfg and cfg.shouldShow(LocalPlayer()) then
cfg.onOpen(npc)
end
lia.dialog.getNPCData(npcID)
Retrieves sanitized NPC dialog data by unique identifier.
Server-side when preparing dialog data for clients or internal operations.
Parameters:
string npcID The unique identifier of the NPC dialog.Returns:
table|nil Sanitized NPC dialog data, or nil if not found.Example Usage:
local npcData = lia.dialog.getNPCData("tutorial_guide")
if npcData then PrintTable(npcData) end
lia.dialog.getOriginalNPCData(npcID)
Returns the original unsanitized NPC dialog definition including server-only callbacks.
Server-side when re-filtering conversation options per-player or rebuilding client payloads.
Parameters:
string npcID The unique identifier of the NPC dialog.Returns:
table|nil Original NPC dialog data, or nil if not found.Example Usage:
local raw = lia.dialog.getOriginalNPCData("tutorial_guide")
if raw and raw.Conversation then
-- inspect server-only callbacks before sanitizing
end
lia.dialog.syncToClients(client)
Sends sanitized dialog data to a specific client or all connected players.
After dialog registration, changes, or on-demand admin refreshes.
Parameters:
Player client optional Specific player to sync to, or nil to broadcast to all players.Example Usage:
concommand.Add("lia_dialog_resync", function(admin)
if IsValid(admin) and admin:IsAdmin() then
lia.dialog.syncToClients()
admin:notifyLocalized("dialogResynced")
end
end)
lia.dialog.syncDialogs()
Broadcasts all dialog data to all connected clients.
After bulk changes, during scheduled refreshes, or maintenance operations.
Example Usage:
timer.Create("ResyncDialogsHourly", 3600, 0, lia.dialog.syncDialogs)
lia.dialog.registerNPC(uniqueID, data, shouldSync)
Registers an NPC dialog definition and optionally synchronizes changes to clients.
During gamemode initialization or when hot-loading NPC dialog data.
Parameters:
string uniqueID Unique identifier for the NPC dialog.table data Complete NPC dialog definition including Conversation, PrintName, Greeting, etc.
boolean shouldSync optional Whether to sync changes to clients immediately (defaults to true).
Returns:
boolean True if successfully registered, false otherwise.Example Usage:
lia.dialog.registerNPC("quests_barkeep", {
PrintName = "Barkeep",
Greeting = "What'll it be?",
Conversation = {
["Got any work?"] = {
Response = "A few rats in the cellar. Interested?",
options = {
["I'm in."] = {serverOnly = true, Callback = function(client) StartQuest(client, "cellar_rats") end},
["No thanks."] = {Response = "Suit yourself."}
}
}
}
})
lia.dialog.openDialog(client, npc, npcID)
Opens an NPC dialog for a player, filtering conversation options based on player permissions.
When a player interacts with an NPC entity.
Parameters:
Player client The player to open the dialog for.Entity npc The NPC entity being interacted with.
string npcID The unique identifier of the NPC dialog type.
Example Usage:
hook.Add("PlayerUse", "HandleDialogNPCs", function(ply, ent)
if ent:GetClass() == "lia_npc" then
lia.dialog.openDialog(ply, ent, ent.uniqueID or "tutorial_guide")
return false
end
end)
lia.dialog.getNPCData(npcID)
Retrieves sanitized NPC dialog data on the client.
When client UI needs to render or access dialog information.
Parameters:
string npcID The unique identifier of the NPC dialog.Returns:
table|nil Sanitized NPC dialog data, or nil if not found.Example Usage:
local data = lia.dialog.getNPCData("tutorial_guide")
if data then print("Greeting:", data.Greeting) end
lia.dialog.submitConfiguration(configID, npc, payload)
Sends NPC customization data to the server for processing.
When submitting changes from NPC customization UI.
Parameters:
string configID The configuration identifier.Entity npc The NPC entity being customized.
table payload The customization data payload.
Example Usage:
lia.dialog.submitConfiguration("appearance", npc, {model = "models/barney.mdl"})
lia.dialog.openCustomizationUI(npc, configID)
Opens a comprehensive UI for customizing NPC appearance, animations, and dialog types.
From properties menu or configuration picker interfaces.
Parameters:
Entity npc The NPC entity to customize.string configID optional Configuration identifier, defaults to "appearance".
Example Usage:
properties.Add("CustomNPCConfig", {
Filter = function(_, ent) return ent:GetClass() == "lia_npc" end,
Action = function(_, ent) lia.dialog.openCustomizationUI(ent, "appearance") end
})
lia.dialog.getAvailableConfigurations(ply, npc, npcID)
Returns available NPC configurations for a player, sorted by order and name.
Before displaying configuration picker UI to filter accessible options.
Parameters:
Player ply The player to check permissions for.Entity npc optional The NPC entity being configured.
string npcID optional The NPC's unique identifier.
Returns:
table Array of accessible configuration tables.Example Usage:
local configs = lia.dialog.getAvailableConfigurations(LocalPlayer(), npc, npc.uniqueID)
for _, cfg in ipairs(configs) do print("Config:", cfg.id) end
lia.dialog.openConfigurationPicker(npc, npcID)
Opens the NPC configuration picker UI, prioritizing appearance configuration.
When a player selects "Configure NPC" from the properties menu.
Parameters:
Entity npc The NPC entity to configure.string npcID optional The NPC's unique identifier.
Example Usage:
lia.dialog.openConfigurationPicker(ent, ent.uniqueID)