Event Subroutines
This is a listing of the Event Subroutines used in quest scripts. Each of these Events is triggered as an action occurs.
Please note that while every effort is made to keep this wiki up to date, some items may have been overlooked. A complete list can be found in GitHub at Server / zone / embparser.cpp.

ProTip: hit ctrl + f (Windows) or ⌘ + f (Mac) to FIND something on this page

EVENT_AGGRO

Trigger

    When a mob aggros a client.
Often used for flavor text--just remember that every NPC_Type has an EmoteID that can often handle this behavior.

Example

    In this example, the NPC will say "Time to die PlayerName." when the NPC is aggro'd by the player.
Perl
Lua
1
sub EVENT_AGGRO {
2
quest::say("Time to die!");
3
}
Copied!
1
function event_aggro(e)
2
e.self:Say("Time to die!");
3
end
Copied!

EVENT_AGGRO_SAY

Trigger

    When a mob is targeted, the player types something, and NPC is in combat.

Exports

Name
Type
Usage
data
int
quest::say($data); # returns int
text
int
quest::say($text); # returns int
langid
int
quest::say($langid); # returns int

Example

    In this example, the NPC, if in combat, would say the names of everyone on its hate list, and include both the amount of damage the entity has done, as well as the amount of hate the entity has generated.
Perl
Lua
1
sub EVENT_AGGRO_SAY {
2
#:: Match "fight", case insensitive, if the NPC aggro
3
if ($text=~/fight/i) {
4
quest::say("I am fighting!");
5
}
6
}
Copied!
1
function event_aggro_say(e)
2
if (e.message:findi("fight")) then
3
e.self:Say("I am fighting!");
4
end
5
end
Copied!

EVENT_ATTACK

Trigger

    When the NPC is attacked.
Note the subtle difference from EVENT_AGGRO, which is triggered when the NPC is aggro'd (which could occur through bad faction, for instance).

Example

    In this example, the NPC will say "Time to die PlayerName." when the NPC is attacked by the player.
Perl
Lua
1
sub EVENT_ATTACK {
2
quest::say("Time to die $name.");
3
}
Copied!
1
function event_attack(e)
2
e.self:Say("Time to die!");
3
end
Copied!

EVENT_AUGMENT_ITEM

Trigger

    When a client augments an item.
You would likely use this event in your global player.pl file.

Example

    In this example, a message in yellow text is displayed to the client when the player adds an augment to an item.
Perl
Lua
1
sub EVENT_AUGMENT_ITEM{
2
$client->Message(15, "Yay, it fit!");
3
}
Copied!
1
function event_augment_item(e)
2
e.owner:Message(15, "Yay, it fit!");
3
end
Copied!

EVENT_AUGMENT_INSERT

Trigger

    When a client inserts an augment into an item.
You would likely use this event in your global player.pl file.

Example

    In this example, a message in yellow text is displayed to the client when the player puts the augment into the augment slot of an item.
Perl
Lua
1
sub EVENT_AUGMENT_INSERT {
2
$client->Message(15, "Yay, it fit!");
3
}
Copied!
1
function event_augment_insert(e)
2
e.owner:Message(15, "Yay, it fit!");
3
end
Copied!

EVENT_AUGMENT_REMOVE

Trigger

    When a client removes an augment from an item. You would likely use this event in your global player.pl file.

Example

    In this example, a message in yellow text is displayed to the client when the player removes an augment from an item.
Perl
Lua
1
sub EVENT_AUGMENT_REMOVE {
2
$client->Message(15, "Yay, you pulled it out!");
3
}
Copied!
1
function event_augment_remove(e)
2
e.owner:Message(15, "Yay, you pulled it out!");
3
end
Copied!

EVENT_BOT_COMMAND

Trigger

    When a player says anything with the ^ command token preceding it that isn't handled by a system bot command.
    Exception: ^help will invoke a special call so that scripted bot commands may be included in search listing.
Used in player files to handle script-based bot command processing.

Exports

Name
Type
Details
bot_command
string
A single, de-tokenized bot command name
args (perl)
string
An unseparated text line of additional parameters
args (lua)
string array
An array of single-word text parameters

Example

    These examples are a working template for adding your own bot commands.
Note: The scripting apis do not fully support the Bot object and scripting options will be limited.
Perl
Lua
1
sub EVENT_BOT_COMMAND {
2
3
my %bot_command_data = (
4
"scriptbotcommand1" => [0, "perl script-based supplementation test bot command 1"],
5
"scriptbotcommand2" => [100, "perl script-based supplementation test bot command 2"],
6
"scriptbotcommand3" => [250, "perl script-based supplementation test bot command 3"]
7
);
8
9
if ($bot_command eq "help" || $bot_command eq "?") { # always a supplemental call from within the system bot_command_help handler
10
my $available_bot_commands = 0;
11
12
foreach my $bot_command_name (sort {$a cmp $b} keys %bot_command_data) {
13
if ($status >= $bot_command_data{$bot_command_name}[0] && ($args eq "0" || $bot_command_name=~/$args/i)) {
14
$client->Message(15, "^$bot_command_name - $bot_command_data{$bot_command_name}[1]");
15
$available_bot_commands = $available_bot_commands + 1;
16
}
17
}
18
19
return $available_bot_commands;
20
}
21
elsif (exists($bot_command_data{$bot_command}) && $status >= $bot_command_data{$bot_command}[0]) {
22
if ($bot_command eq "scriptbotcommand1") {
23
$client->Message(14, "doing '$bot_command'...");
24
return 1;
25
}
26
elsif ($bot_command eq "scriptbotcommand2") {
27
$client->Message(14, "doing '$bot_command'...");
28
return 1;
29
}
30
elsif ($bot_command eq "scriptbotcommand3") {
31
$client->Message(14, "doing '$bot_command'...");
32
return 1;
33
}
34
}
35
36
return 0;
37
}
Copied!
1
function event_bot_command(e)
2
3
local bot_command_data = {
4
["scriptbotcommand1"] = {0, "lua script-based supplementation test bot command 1"},
5
["scriptbotcommand2"] = {100, "lua script-based supplementation test bot command 2"},
6
["scriptbotcommand3"] = {250, "lua script-based supplementation test bot command 3"}
7
}
8
9
if (e.bot_command == "help" or e.bot_command == "?") then -- always a supplemental call from within the system bot_command_help handler
10
local available_bot_commands = 0;
11
12
local key_sort = {}
13
for key in pairs(bot_command_data) do
14
table.insert(key_sort, key);
15
end
16
table.sort(key_sort);
17
18
for index, key in ipairs(key_sort) do
19
if (e.self:Admin() >= bot_command_data[key][1] and (e.args[1] == nil or key:findi(e.args[1]))) then
20
e.self:Message(15, "^" .. key .. " - " .. bot_command_data[key][2]);
21
available_bot_commands = available_bot_commands + 1;
22
end
23
end
24
25
return available_bot_commands;
26
elseif (bot_command_data[e.bot_command] ~= nil and e.self:Admin() >= bot_command_data[e.bot_command][1]) then
27
if (e.bot_command == "scriptbotcommand1") then
28
e.self:Message(14, "doing '" .. e.bot_command .. "'...");
29
return 1;
30
elseif (e.bot_command == "scriptbotcommand2") then
31
e.self:Message(14, "doing '" .. e.bot_command .. "'...");
32
return 1;
33
elseif (e.bot_command == "scriptbotcommand3") then
34
e.self:Message(14, "doing '" .. e.bot_command .. "'...");
35
return 1;
36
end
37
end
38
39
return 0;
40
end
Copied!

EVENT_CAST

Trigger

    When a client casts a spell.

Exports

Name
Type
Usage
spell_id
int
quest::say($spell_id); # returns int

Example

    In this example, the player would emote upon a successful cast.
Perl
Lua
1
sub EVENT_CAST {
2
quest::me("regains his concentration and casts his spell.");
3
}
Copied!
1
function event_cast(e)
2
e.self:Emote("regains his concentration and casts his spell.");
3
end
Copied!

EVENT_CAST_BEGIN

Trigger

    When a client begins to cast a spell.

Exports

Name
Type
Usage
spell_id
int
quest::say($spell_id); # returns int

Example

    In this example, the player would emote if they begin casting the gate spell. You would likely place this particular snippet into your global player.pl file.
Perl
Lua
1
sub EVENT_CAST_BEGIN {
2
#:: Match if $spell_id is 36 - Gate
3
if ($spell_id == 36) {
4
quest::me("begins casting the Gate spell.");
5
}
6
}
Copied!
1
function event_cast_begin(e)
2
--:: Match if spell_id is 36 - Hate
3
local spell_id = e.spell:GetID();
4
if (spell_id == 36) then
5
e.self:Emote("begins casting the Gate spell.");
6
end
7
end
Copied!

EVENT_CAST_ON

Trigger

    When a player casts a spell on a player or NPC.

Exports

Name
Type
Usage
spell_id
int
quest::say($spell_id); # returns int

Example

    In this example, if the player casts Banish Summoned on an NPC with a Summoned body type, the NPC will be killed. If you were placing this snippet in an NPC's quest script, you likely wouldn't bother matching body type.
Perl
Lua
1
sub EVENT_CAST_ON {
2
#:: Match if $spell_id is 116 - Banish Summoned
3
if ($spell_id == 116) {
4
#:: Match if the NPC's body type is 28 - Summoned Creature
5
if ($mob->GetBodyType() == 28) {
6
$npc->Kill();
7
}
8
else {
9
$client->Message(13, "This spell only effects summoned creatures");
10
}
11
}
12
}
Copied!
1
function event_cast_on(e)
2
--:: Match if spell_id is 116 - Banish Summoned
3
local spell_id = e.spell:GetID();
4
if (spell_id == 116) then
5
--:: Match if the NPC's body type is 28 - Summoned Creature
6
local body_type = e.self:GetBodyType();
7
if (body_type == 28) then
8
e.self:Kill();
9
else
10
if (e.self:IsClient()) then
11
e.self:Message(13, "This spell only effects summoned creatures.");
12
end
13
end
14
end
15
end
Copied!

EVENT_CLICKDOOR

Trigger

    When the client clicks on a door object.
Note that you would likely use this event in the zone player.pl file. Since doors have open types and destination fields stored in the database, most "simple" doors do not require a separate quest script. An example of a "simple" door would be any door that requires a single keyitem (by Item ID) to open, like the door to the basement in Befallen.

Exports

Name
Type
Usage
doorid
int
quest::say($doorid); # returns int
version
int
quest::say($version); # returns int

Example

    In this example, a player who is part of a Deepest Guk Adventure would be teleported to Deepest Guk when they click the doorway found in the Hollow Log.
Perl
Lua
1
sub EVENT_CLICKDOOR {
2
#:: Match if doorID is 1 - the door found in the Hollow Log that leads to Deepest Guk Adventures
3
if ($doorid == 1) {
4
#:: Create a variable to store the player's adventure zone instance ID
5
$GukAInstance = quest::GetInstanceID("guka",50);
6
#:: Match if the player has an instance
7
if ($GukAInstance > 0) {
8
#:: Teleport the player to their instance in Deepest Guk at the safe spot
9
quest::MovePCInstance(229, $GukAInstance, 101, -841, 2.38);
10
}
11
else {
12
$client->Message(13, "You are not a part of a Deepest Guk adventure instance!");
13
}
14
}
15
}
Copied!
1
function event_click_door(e)
2
--:: Match if doorID is 1 - the door found in the Hollow Log that leads to Deepest Guk Adventures
3
local door_id = e.door:GetDoorID();
4
if (door_id == 1) then
5
--:: Create a variable to store the player's adventure zone instance ID
6
local guka_instance = eq.get_instance_id("guka", 50);
7
--:: Match if the player has an instance
8
if (guka_instance > 0) then
9
--:: Teleport the player to their instance in Deepest Guk at the safe spot
10
e.self:MovePCInstance(229, guka_instance, 101, -841, 2.38);
11
else
12
e.self:Message(13, "You are not a part of a Deepest Guk adventure instance!");
13
end
14
end
15
end
Copied!

EVENT_CLICK_OBJECT

Trigger

    When the client clicks on an object.
Note the similarity between this event and Perl EVENT_CLICKDOOR, since it is easy to confuse a door object (like a Plane of Knowledge Book) with Objects (IE Pottery wheels, Brew Barrels, etc.). You would likely use this event in the zone player.pl (or global_player.pl) files.

Exports

Name
Type
Usage
objectid
int
quest::say($objectid); # returns int
clicker_id
int
quest::say($clicker_id); # returns int

Example

    In this example, a message is displayed to a player when they open the Ogre Cultural Forge in Oggok.
Perl
Lua
1
sub EVENT_CLICK_OBJECT {
2
#:: Match to the ogre cultural forge in Oggok by object ID
3
if ($objectid == 1075) {
4
#:: Check to see if the player who clicked is a race other than Ogre
5
if ($race ne "Ogre") {
6
#:: Send the client a message in color 1 (gray)
7
$client->Message(1,"The foul stench of Ogre overwhelms you as you open the forge.");
8
} else {
9
$client->Message(1,"Mmmm--dis smells just like home.");
10
}
11
}
12
}
Copied!
1
function event_click_object(e)
2
--:: Match to the ogre cultural forge in Oggok by object ID
3
local object_id = e.object:GetID();
4
if (object_id == 1075) then
5
--:: Check to see if the player who clicked is a race other than Ogre
6
local race_id = e.self:GetRace();
7
if (race_id != 10) then
8
--:: Send the client a message in color 1 (gray)
9
e.self:Message(1,"The foul stench of Ogre overwhelms you as you open the forge.");
10
else
11
e.self:Message(1,"Mmmm--dis smells just like home.");
12
end
13
end
14
end
Copied!

EVENT_COMBAT

Trigger

    When an NPC enters or leaves combat.

Exports

Name
Type
Usage
combat_state
int
quest::say($combat_state); # returns int

Example

    In this example, the NPC will say some flavor text when entering combat.
Perl
Lua
1
sub EVENT_COMBAT {
2
#:: combat state 0 = False, 1 = True
3
if ($combat_state == 1) {
4
quest::say("Time to die!");
5
}
6
}
Copied!
1
function event_combat(e)
2
--:: e.joined is true/false
3
if (e.joined) then
4
e.self:Say("Time to die!");
5
end
6
end
Copied!

EVENT_COMBINE_FAILURE

Trigger

    When a combine is unsuccessful. You would likely use this event in your global / player.pl file.

Exports

Name
Type
Usage
recipe_id
int
quest::say($recipe_id); # returns int
recipe_name
int
quest::say($recipe_name); # returns int

Example

    In this example, we watch for a player failing the combine for a Hand Made Backpack and then tease them.
Perl
Lua
1
sub EVENT_COMBINE_FAILURE {
2
#:: Match Recipe 2686: "Hand Made Backpack" by ID
3
if ($recipe_id == 2686) {
4
#:: Send the client a message in color 15 (yellow)
5
$client->Message(15,"Awww...now where are you going to put all of your stuff?");
6
}
7
}
Copied!
1
function event_combine_failure(e)
2
--:: Match Recipe 2686: "Hand Made Backpack" by ID
3
if (e.recipe_id == 2686) then
4
--:: Send the client a message in color 15 (yellow)
5
e.self:Message(15, "Awww...now where are you going to put all of your stuff?");
6
end
7
end
Copied!

EVENT_COMBINE_SUCCESS

Trigger

    When a combine is successful.

Exports

Name
Type
Usage
recipe_id
int
quest::say($recipe_id); # returns int
recipe_name
int
quest::say($recipe_name); # returns int

Example

    In this example, we send the client a message when they successfully combine a Hand Made Backpack
Perl
Lua
1
sub EVENT_COMBINE_SUCCESS {
2
#:: Match Recipe 2686: "Hand Made Backpack" by ID
3
if ($recipe_id == 2686) {
4
#:: Send the client a message in color 15 (yellow)
5
$client->Message(15,"Yay, now you have a place to put all of your stuff!");
6
}
7
}
Copied!
1
function event_combine_success(e)
2
--:: Match Recipe 2686: "Hand Made Backpack" by ID
3
if (e.recipe_id == 2686) then
4
--:: Send the client a message in color 15 (yellow)
5
e.self:Message(15, "Yay, now you have a place to put all of your stuff!");
6
end
7
end
Copied!

EVENT_COMMAND

Trigger

    When a player says anything with the # command token preceding it that isn't handled by a system command.
    Exception: #help will invoke a special call so that scripted commands may be included in search listing.
Used in player files to handle script-based command processing.

Exports

Name
Type
Details
command
string
A single, de-tokenized command name
args (perl)
string
An unseparated text line of additional parameters
args (lua)
string array
An array of single-word text parameters

Example

    These examples are a working template for adding your own commands.
Perl
Lua
1
sub EVENT_COMMAND {
2
3
my %command_data = (
4
"scriptcommand1" => [0, "perl script-based supplementation test command 1"],
5
"scriptcommand2" => [100, "perl script-based supplementation test command 2"],
6
"scriptcommand3" => [250, "perl script-based supplementation test command 3"]
7
);
8
9
if ($command eq "help") { # always a supplemental call from within the system command_help handler
10
my $available_commands = 0;
11
12
foreach my $command_name (sort {$a cmp $b} keys %command_data) {
13
if ($status >= $command_data{$command_name}[0] && ($args eq "0" || $command_name=~/$args/i)) {
14
$client->Message(15, "#$command_name - $command_data{$command_name}[1]");
15
$available_commands = $available_commands + 1;
16
}
17
}
18
19
return $available_commands;
20
}
21
elsif (exists($command_data{$command}) && $status >= $command_data{$command}[0]) {
22
if ($command eq "scriptcommand1") {
23
$client->Message(14, "doing '$command'...");
24
return 1;
25
}
26
elsif ($command eq "scriptcommand2") {
27
$client->Message(14, "doing '$command'...");
28
return 1;
29
}
30
elsif ($command eq "scriptcommand3") {
31
$client->Message(14, "doing '$command'...");
32
return 1;
33
}
34
}
35
36
return 0;
37
}
Copied!
1
function event_command(e)
2
3
local command_data = {
4
["scriptcommand1"] = {0, "lua script-based supplementation test command 1"},
5
["scriptcommand2"] = {100,