CreatureEvent
There are many types of events for the CreatureEvent interface, here is a list.
  • onLogin(player)
  • onLogout(player)
  • onThink(creature, interval)
  • onPrepareDeath(creature, killer)
  • onDeath(creature, corpse, killer, mostDamageKiller, lastHitUnjustified, mostDamageUnjustified)
  • onKill(creature, target)
  • onAdvance(player, skill, oldLevel, newLevel)
  • onModalWindow(player, modalWindowId, buttonId, choiceId)
  • onTextEdit(player, item, text)
  • onHealthChange(creature, attacker, primaryDamage, primaryType, secondaryDamage, secondaryType, origin)
  • onManaChange(creature, attacker, primaryDamage, primaryType, secondaryDamage, secondaryType, origin)
  • onExtendedOpCode(player, opcode, buffer)
  • You can create a CreatureEvent script in data/creaturescripts/scripts folder, but
  • You must register CreatureEvents in data/creaturescripts/creaturescripts.xml, here is an example
1
<event type="logout" name="PlayerLogout" script="logout.lua" />
Copied!
  • Alternatively you can use revscript method to register via lua, by saving a .lua file in data/scripts folder.
  • Any CreatureEvent that is not onLogin, must be registered to the creature using the creature:registerEvent(name) method, where name is the name of the event in the xml file (unless is revscript, then name is created when event is created), our above example would be done like this : creature:registerEvent("PlayerLogout") before it will be used by the creature.
Please keep in mind you can name your script whatever you want as long as it ends in .lua, and its full name is in the xml, with script=""

onLogin(player)

  • player -- 1st arg/parameter /userdata/ = The player who is trying to login
onLogin is called whenever any player tries to log in, its a great spot to register other CreatureEvents to players.
You can register your event in creaturescripts.xml like so:
1
<event type="login" name="PlayerLogin" script="login.lua" />
Copied!
You can then call the event in a script like so:
Example: login.lua
1
local firstItems = {2050, 2382} --- table with items for new player
2
3
function onLogin(player)
4
if player:getLastLoginSaved() == 0 then --- player has never logged in before
5
for i = 1, #firstItems do
6
player:addItem(firstItems[i], 1) -- we give 1 of each item in table above to player
7
end
8
player:addItem(ITEM_BAG, 1) -- we give the player a bag too
9
end
10
return true --- we must return true to allow player to login, false or no return will keep player from logging in.
11
end
Copied!
Always remember to return true if you wish to allow player login, returning false or not returning true will block player from logging in!

onLogout(player)

  • player -- 1st arg/parameter /userdata/ = The player who is trying to logout
onLogout is called whenever any player tries to logout, its a great spot to unregister other CreatureEvents to players.
You can register your event in creaturescripts.xml like so:
1
<event type="logout" name="PlayerLogout" script="logout.lua" />
Copied!
You can then call the event in a script like so:
Example: logout.lua
1
function onLogout(player)
2
if player:isPzLocked() then
3
player:sendTextMessage(MESSAGE_INFO_DESCR,"You must not be pz-locked, in order to logout")
4
return false --- here we block player from logging out
5
end
6
--- if we made it to this point, player must not be pzlocked, so lets let him logout
7
return true --- player logs out successfully
8
end
Copied!
Always remember to return true if you wish to allow player logout, returning false or not returning true will block player from logging out!

onThink(creature, interval)

  • creature -- 1st arg/parameter /userdata/ = The creature whom the event is triggering on
  • interval -- 2nd arg/parameter /integer/ = The milliseconds interval at which every iteration of the event will take place
onThink is similar to an infinite loop, as it does not stop unless the event is unregistered. It occurs every 1000 milliseconds, so once every second.
You can register your event in creaturescripts.xml like so:
1
<event type="think" name="thinkEvent" script="think.lua" />
Copied!
You can then call the event in a script like so:
Example: think.lua
1
function onThink(creature)
2
if creature:isMonster() then
3
creature:say("I'm hungry") --- if its a monster, says "I'm hungry"
4
return -- we return now as we have done as we intended
5
end
6
7
return --- here we are returning incase creature wasn't a monster
8
end
Copied!
Returns strictly serve as a control mechanism when using this hook

onPrepareDeath(creature, killer)

  • creature -- 1st arg/parameter /userdata/ = The creature that is preparing to die
  • killer -- 2nd arg/parameter /userdata/ = The killer is who killed the creature
onPrepareDeath triggers before creature death, and so you can return false to prevent the death from happening. This is particularly useful for pvp arena and special event scenarios.
You can register your event in creaturescripts.xml like so:
1
<event type="preparedeath" name="deathPrep" script="preparedeath.lua" />
Copied!
You can then call the event in a script like so:
Example: preparedeath.lua
1
function onPrepareDeath(creature, killer)
2
if creature:isMonster() and killer:isMonster() then
3
return false -- returning false will prevent the monster from dieing to another monster, but not give it any hp back
4
end
5
6
return true --- it wasn't a monster, killing a monster, so we allow the death by returning true
7
end
Copied!
When returning false for onPrepareDeath , the creature will not die! Return true to continue with death of creature

onDeath(creature, corpse, killer, mostDamageKiller, lastHitUnjustified, mostDamageUnjustified)

  • creature -- 1st arg/parameter /userdata/ = The creature that has been killed
  • corpse -- 2nd arg/parameter /userdata/ = The corpse is a container object, inherits from item, contains items dropped by the creature
  • killer -- 3rd arg/parameter /userdata/ = The killer is who killed the creature
  • mostDamageKiller -- 4th arg/parameter /userdata/ = The mostDamageKiller dealt most damage to the creature
  • lastHitUnjustified -- 5th arg/parameter /boolean/ = is true if killer's last hit was unjustified, false if not.
  • mostDamageUnjustified -- 6th arg/parameter /boolean/ = is true if killer recieved unjustified from most damage to creature, false if not //: #
onDeath triggers after creature death and is uniquely suited for handling multiple killers, as well as determining if the death was unjustified or not.
You can register your event in creaturescripts.xml like so:
1
<event type="death" name="PkRevenge" script="pkdeath.lua" />
Copied!
You can then call the event in a script like so:
Example: pkdeath.lua
1
function onDeath(creature, corpse, killer, mostDamageKiller, lastHitUnjustified, mostDamageUnjustified)
2
if creature:isMonster() and killer:isMonster() then
3
return -- returning false would serve as same result as return here, just exits the script. So if monster killed monster, do nothing.
4
end
5
6
if not lastHitUnjustified and not mostDamageUnjustified then
7
return -- exits script if this wasn't an unjust kill
8
end
9
10
if killer and mostDamageKiller then -- makes sure neither are nil
11
if killer:isPlayer() and mostDamageKiller:isPlayer() then -- checks if both are player class
12
if killer:getGuid() == mostDamageKiller:getGuid() then -- if both are one in the same
13
return -- exits script, because we are looking for multiple players in an unjust kill
14
end
15
--- here we now know it has to be at least two players who took part in the kill
16
corpse:remove() -- we destroyed the corpse so those pker's don't get it!
17
return -- scripts purpose is served, we exit
18
end
19
end
20
end
Copied!
Returns strictly serve as a control mechanism when using this hook

onKill(killer, victim)

  • killer -- 1st arg/parameter /userdata/ = The creature that has killed
  • victim -- 2nd arg/parameter /userdata/ = The victim is a creature that died
onKill triggers after creature death and is great for handling specific kills, ie, killed a boss, a player of a certain guild, stuff like that, without having to register to each of the victims.
You can register your event in creaturescripts.xml like so:
1
<event type="kill" name="bossKill" script="bosskill.lua" />
Copied!
You can then call the event in a script like so:
Example: bosskill.lua
1
function onKill(killer, victim)
2
if not killer:isPlayer() then
3
return -- killer is not a player, no need to execute any further.
4
end
5
if not victim:isMonster() and victim:getType():isBoss() then
6
return -- victim is not a boss, no need to execute any further.
7
end
8
-- anything here, happens because the killer is a player, and the victim is a monsterType, that returns true with :isBoss()
9
killer:sendTextMessage(MESSAGE_INFO_DESCR, "Congratulations you killed a Boss!")
10
end
Copied!
Returns strictly serve as a control mechanism when using this hook

onAdvance(player, skill, oldlevel, newlevel)

  • player -- 1st arg/parameter /userdata/ = The player that gained a level!
  • skill -- 2nd arg/parameter /integer/ = The skill is an integer representing a constant value found here. -- insert link
  • oldlevel -- 3rd arg/parameter /integer/ = The oldlevel is an integer value of the level before the advancement.
  • newlevel -- 4th arg/parameter /integer/ = The newlevel is an integer value of the level after the advancement.
onAdvance triggers when a player gains a level, magic level, or skill level.
You can register your event in creaturescripts.xml like so:
1
<event type="advance" name="fishingLevels" script="fishinglevels.lua" />
Copied!
You can then call the event in a script like so:
Example: fishinglevels.lua
1
function onAdvance(player, skill, oldlevel, newlevel)
2
if not skill == SKILL_FISHING then -- we only run this if the skill gained was fishing skill
3
return true
4
end
5
if newlevel >= 100 then
6
player:getPosition():sendMagicEffect(CONST_ME_PLUNGING_FISH)
7
player:sendTextMessage(MESSAGE_EVENT_ADVANCE, "Congratulations you are officially a BIG FISHER!")
8
end
9
return true
10
end
Copied!
:TODO: Unsure atm if return true is necessary to advance or not.

onModalWindow(player, modalWindowId, buttonId, choiceId)

  • player -- 1st arg/parameter /userdata/ = The player the modal window is being called for, the player whom its registered to.
  • modalWindowId -- 2nd arg/parameter /integer/ = The modalWindowId is an integer representing the modalwindow's id.
  • buttonId -- 3rd arg/parameter /integer/ = The buttonId is an integer representing
  • choiceId -- 4th arg/parameter /integer/ = The newlevel is an integer value of the level after the advancement.
onModalWindow is called whenever any modalwindow is sent to the player
You can register your event in creaturescripts.xml like so:
1
<event type="modalwindow" name="coolMenu" script="modalwindow.lua" />
Copied!
You can then call the event in a script like so:
Example: modalwindow.lua
1
function onModalWindow(player, modalWindowId, buttonId, choiceId)
2
-- TODO
3
end
Copied!
:TODO:

onTextEdit(player, item, text)

  • player -- 1st arg/parameter /userdata/ = The player the modal window is being called for, the player whom its registered to.
  • item -- 2nd arg/parameter /userdata/ = The item that is being edited
  • text -- 3rd arg/parameter /string/ = The text is the string that the player writes.
onTextEdit is called whenever any writes text to any item
You can register your event in creaturescripts.xml like so:
1
<event type="textedit" name="bookPassword" script="bookPassword.lua" />
Copied!
You can then call the event in a script like so:
Example: bookPassword.lua
1
function onTextEdit(player, modalWindowId, buttonId, choiceId)
2
-- TODO
3
end
Copied!
:TODO:

onHealthChange(creature, attacker, primaryDamage, primaryType, secondaryDamage, secondaryType, origin)

  • creature -- 1st arg/parameter /userdata/ = The creature whom's health is changing, either up or down.
  • attacker -- 2nd arg/parameter /userdata/ = The attacker is the creature causing the healthchange.
  • primaryDamage -- 3rd arg/parameter /integer/ = The primaryDamage is the amount of health change for a primary damage type.
  • primaryType -- 4th arg/parameter /integer/ = The primaryType is a constant value found here. -- insert link
  • secondaryDamage -- 5th arg/parameter /integer/ = The secondaryDamage is the amount of health change for a secondary damage type.
  • secondaryType -- 6th arg/parameter /integer/ = The secondaryType is a constant value found here. -- insert link
  • origin -- 7th arg/parameter /integer/ = The origin is a constant value found here. -- insert link
onHealthChange is called when a creatures healh changes, up or down.
You can register your event in creaturescripts.xml like so:
1
<event type="healthchange" name="cursedhealth" script="cursedhealth.lua" />
Copied!
You can then call the event in a script like so:
Example: cursedhealth.lua
1
function onHealthChange(creature, attacker, primaryDamage, primaryType, secondaryDamage, secondaryType, origin)
2
-- TODO
3
end
Copied!
:TODO:

onManaChange(creature, attacker, primaryDamage, primaryType, secondaryDamage, secondaryType, origin)

  • creature -- 1st arg/parameter /userdata/ = The creature whom's health is changing, either up or down.
  • attacker -- 2nd arg/parameter /userdata/ = The attacker is the creature causing the healthchange.
  • primaryDamage -- 3rd arg/parameter /integer/ = The primaryDamage is the amount of health change for a primary damage type.
  • primaryType -- 4th arg/parameter /integer/ = The primaryType is a constant value found here. -- insert link
  • secondaryDamage -- 5th arg/parameter /integer/ = The secondaryDamage is the amount of health change for a secondary damage type.
  • secondaryType -- 6th arg/parameter /integer/ = The secondaryType is a constant value found here. -- insert link
  • origin -- 7th arg/parameter /integer/ = The origin is a constant value found here. -- insert link
onManaChange is called when a players mana changes, up or down.
You can register your event in creaturescripts.xml like so:
1
<event type="manachange" name="buffedMana" script="buffedMana.lua" />
Copied!
You can then call the event in a script like so:
Example: buffedMana.lua
1
function onManaChange(creature, attacker, primaryDamage, primaryType, secondaryDamage, secondaryType, origin)
2
-- TODO
3
end
Copied!
:TODO:

onExtendedOpCode(player, opcode, buffer)

  • player -- 1st arg/parameter /userdata/ = The player
  • opcode -- 2nd arg/parameter /userdata/ = The opcode
  • buffer -- 3rd arg/parameter /integer/ = The buffer
onExtendedOpCode is called when
You can register your event in creaturescripts.xml like so:
1
<event type="extendedopcode" name="opCode" script="opCode.lua" />
Copied!
You can then call the event in a script like so:
Example: opCode.lua
1
function onExtendedOpCode(player, opcode, buffer)
2
-- TODO
3
end
Copied!
:TODO: