EQ2Emu
Discord Log in

Lua function reference / Script modules

DialogModule

NPC conversations, response callbacks, voiceovers, emotes, and player requirements.

Lua script module · Reviewed October 7, 2026.

DialogModule builds NPC conversations from Lua: dialogue text, selectable responses, callback names, voiceovers, emotes, and requirements based on the player or NPC. Load it explicitly alongside NPCModule when an NPC needs both initialization and dialogue.

Loading and calling

local Dialog = require "SpawnScripts/Generic/DialogModule"

The module returns a Dialog table and also defines it globally. Call its methods with a dot, for example Dialog.New(NPC, Player). A colon call inserts an extra self argument and changes the argument positions. There is no DialogModule(NPC) initializer.

Dialogue belongs in a player interaction such as hailed(NPC, Player). Here Player names the interacting player supplied by the server. The separate spawn callback is lowercase function spawn(NPC) and receives only the NPC.

These methods are defined in a Lua script; their underlying engine operations are separately registered Lua functions.

Evidence: server/SpawnScripts/Generic/DialogModule.lua:1–28, :141–145, :296; WorldServer/Zone/zoneserver.cpp:6031–6054.

Conversation lifecycle

Build and send one conversation during the same callback:

  1. Dialog.New(NPC, Player) selects the speaking NPC and receiving player.
  2. Dialog.AddDialog(text) creates a dialogue entry.
  3. Add that entry's requirements, voiceover, emote, and options. Add an option before attaching an option requirement.
  4. Dialog.Start() evaluates requirements and sends the selected entry.

Dialog.New sets the handles; it does not clear queued entries or return a separate conversation object. Dialog.Start clears the queued dialogue list at its normal end, including when no entry qualifies. If either handle is nil, it returns early without clearing the list. Supply valid NPC/player handles and finish each build with Dialog.Start.

All public methods below have no explicit return value. They mutate the shared Dialog state or call an engine function. The private CheckRequirements and PrintOptions helpers are internal implementation details.

Evidence: DialogModule.lua:141–145, :154–177, :230–296.

Dialog methods

Call Arguments and purpose Ordering or status
Dialog.New(NPC, Player) Required NPC handle and player handle; selects the participants. Call before starting the conversation.
Dialog.AddDialog(text) Required dialogue string; appends an entry with an empty options list. Call before entry-specific methods.
Dialog.AddRequirement(type, value1, value2, value3) Requirement constant and its values, described below. Attaches to the most recently added dialogue entry.
Dialog.AddOption(text, callback) Response text and optional callback name string in the NPC's script. Attaches to the most recent dialogue entry; omit the callback for a closing response.
Dialog.AddOptionRequirement(type, value1, value2, value3) Requirement constant and its values. Attaches to the most recently added option.
Dialog.AddVoiceover(file, key1, key2) Voiceover filename and two engine voiceover keys. Attaches to the latest entry; provide keys such as 0, 0 where appropriate for the asset.
Dialog.AddEmote(emote) Engine emote name string. Attaches to the latest entry.
Dialog.Start() No arguments; chooses a qualifying entry and sends it. Requires the participants set by Dialog.New.
Dialog.Test(message) Message string; calls Say if the selected NPC is non-nil. Diagnostic speech helper; does not build a dialogue entry.
Dialog.AddLanguage(languageID) Declared language argument. Placeholder: empty body; has no effect.
Dialog.SetIsSignature(enabled) Declared signature-style argument. Placeholder: empty body; has no effect.

Adding requirements, voiceovers, emotes, or options before Dialog.AddDialog can index a missing entry and raise a Lua error. Dialog.AddOptionRequirement also requires an existing option. Callbacks are global functions in the NPC's spawn script, not function objects passed to AddOption.

Evidence: DialogModule.lua:141–227; WorldServer/Lua/LuaFunctions.cpp:1042–1056.

Requirements

Both dialogue and option requirements use the same checker. Every attached requirement must pass (AND). value1, value2, and value3 correspond to the following table; unused values may be omitted.

Constant ID Values Passing condition
REQ_RACE 1 value1 = race ID Player's race equals the ID.
REQ_CLASS 2 value1 = class ID Player's class equals the ID.
REQ_LEVEL 3 value1 = level Player's adventure level equals the value.
REQ_LEVEL_GREATER_OR_EQUAL 4 value1 = minimum level Player's adventure level is at least the value.
REQ_LEVEL_LESS_OR_EQUAL 5 value1 = maximum level Player's adventure level is at most the value.
REQ_QUEST_ELIGIBLE 6 value1 = quest ID CanReceiveQuest succeeds.
REQ_QUEST_ON_STEP 7 value1 = quest ID, value2 = step Current quest step equals the value.
REQ_QUEST_BEFORE_STEP 8 Quest ID, step Current quest step is less than the value.
REQ_QUEST_PAST_STEP 9 Quest ID, step Current quest step is greater than the value.
REQ_QUEST_HAS_QUEST 10 Quest ID Player has the quest.
REQ_QUEST_DOESNT_HAVE_QUEST 11 Quest ID Player does not have the quest.
REQ_QUEST_NOT_ON_STEP 12 Quest ID, step Current quest step differs from the value.
REQ_QUEST_HAS_COMPLETED_QUEST 13 Quest ID Player has completed the quest.
REQ_QUEST_NOT_HAS_COMPLETED_QUEST 14 Quest ID Player has not completed the quest.
REQ_TEMP_VAR_NOT_SET 15 Variable name, comparison value Stored value differs from value2; despite the name, this is a comparison, not a standalone existence check.
REQ_TEMP_VAR_SET 16 Variable name, comparison value Stored value equals value2.
REQ_LUA_HISTORY_SET 17 History event ID, first expected value, optional second expected value First history value matches value2; if supplied, second matches value3.
REQ_LUA_HISTORY_NOT_SET 18 History event ID, first comparison value, optional second comparison value First history value differs from value2; if supplied, second must also differ from value3.
REQ_LOCATION_ID 19 value1 = spawn location ID The NPC's spawn location ID equals the value.

Use constants declared by this module and correctly typed values. Unknown requirement types are not rejected by the checker. The current file references REQ_TSLEVEL, REQ_TSLEVEL_GREATER_OR_EQUAL, and REQ_TSLEVEL_LESS_OR_EQUAL but does not define them. The separate DialogModuleTest.lua defines those constants; importing the main module alone does not make those tradeskill requirements usable as documented constants.

Evidence: DialogModule.lua:4–22, :33–124; server/SpawnScripts/Generic/DialogModuleTest.lua:23–25.

Conversation example

This authored example follows the Dialog.New → entry/options → Dialog.Start pattern used by Commonwealth/FarriKoude.lua. It includes a real callback and a level-gated option:

local Dialog = require "SpawnScripts/Generic/DialogModule"

function hailed(NPC, Player)
    FaceTarget(NPC, Player)
    Dialog.New(NPC, Player)
    Dialog.AddDialog("Welcome. What would you like to know?")
    Dialog.AddOption("Tell me about the patrol.", "ExplainPatrol")
    Dialog.AddOptionRequirement(REQ_LEVEL_GREATER_OR_EQUAL, 5)
    Dialog.AddOption("Goodbye.")
    Dialog.Start()
end

function ExplainPatrol(NPC, Player)
    Dialog.New(NPC, Player)
    Dialog.AddDialog("The patrol keeps watch along the road.")
    Dialog.AddOption("Thank you.")
    Dialog.Start()
end

The first option is shown only to players at adventure level 5 or higher. The closing option remains available. Every selected response with a callback names a function defined in this same script.

To add audio or an emote to the current entry, put these calls after Dialog.AddDialog and before Dialog.Start:

Dialog.AddVoiceover("voiceover/english/voice_emotes/greetings/greetings_1_1038.mp3", 0, 0)
Dialog.AddEmote("hello")

The voiceover path is used by the reviewed FarriKoude script. Choose assets and emotes supported by the intended client. Example text is illustrative; examples were checked against source rather than run in a live world.

Evidence: server/SpawnScripts/Commonwealth/FarriKoude.lua:9–32; WorldServer/Zone/zoneserver.cpp:6048–6054, :6075–6080.

Behavior and limitations

Dialog.Start walks entries with pairs and sends the first qualifying entry it encounters. The code does not explicitly sort entries or options. Prefer mutually exclusive requirements when ordering would change which dialogue is chosen.

When options qualify, it normally uses StartConversation. Without options, the intended branch uses Say, or PlayFlavor when a voiceover is present. An emote is sent through PlayFlavor. Plain Say is NPC speech and is not a private conversation window.

The current PrintOptions helper sets a global ret to true when an option passes, but never initializes it for each invocation. HadOptions is also global. A previous dialogue with options can therefore leave the next options-free dialogue taking the conversation branch; the engine rejects an empty conversation. Include an explicit closing option in normal conversation examples, as above. This documentation records the issue without changing the module.

These helpers create runtime dialogue and do not save NPC definitions, grant quests, or persist player progression by themselves. Requirements control which text/options appear; perform any quest or gameplay action explicitly inside the selected callback.

Evidence: DialogModule.lua:127–137, :230–296; WorldServer/Lua/LuaFunctions.cpp:1139–1174.

Definitions come from the reviewed Lua scripts and engine handlers. Server scripts and bindings are unchanged by this documentation update.