CreatureEvent

There are many types of events for the CreatureEvent interface, here is a list.

<event type="logout" name="PlayerLogout" script="logout.lua" />

  • 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:

<event type="login" name="PlayerLogin" script="login.lua" />

You can then call the event in a script like so:

Example: login.lua

local firstItems = {2050, 2382} --- table with items for new player

function onLogin(player)
    if player:getLastLoginSaved() == 0 then --- player has never logged in before
        for i = 1, #firstItems do
            player:addItem(firstItems[i], 1) -- we give 1 of each item in table above to player
        end
        player:addItem(ITEM_BAG, 1) -- we give the player a bag too
    end
    return true --- we must return true to allow player to login, false or no return will keep player from logging in. 
end

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:

<event type="logout" name="PlayerLogout" script="logout.lua" />

You can then call the event in a script like so:

Example: logout.lua

function onLogout(player)
    if player:isPzLocked() then
        player:sendTextMessage(MESSAGE_INFO_DESCR,"You must not be pz-locked, in order to logout")
        return false --- here we block player from logging out
    end
    --- if we made it to this point, player must not be pzlocked, so lets let him logout
    return true --- player logs out successfully
end

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:

<event type="think" name="thinkEvent" script="think.lua" />

You can then call the event in a script like so:

Example: think.lua

function onThink(creature)
    if creature:isMonster() then
        creature:say("I'm hungry") --- if its a monster, says "I'm hungry"
        return -- we return now as we have done as we intended
    end

    return --- here we are returning incase creature wasn't a monster
end

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:

<event type="preparedeath" name="deathPrep" script="preparedeath.lua" />

You can then call the event in a script like so:

Example: preparedeath.lua

function onPrepareDeath(creature, killer)
    if creature:isMonster() and killer:isMonster() then
        return false -- returning false will prevent the monster from dieing to another monster, but not give it any hp back
    end

    return true --- it wasn't a monster, killing a monster, so we allow the death by returning true
end

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:

<event type="death" name="PkRevenge" script="pkdeath.lua" />

You can then call the event in a script like so:

Example: pkdeath.lua

function onDeath(creature, corpse, killer, mostDamageKiller, lastHitUnjustified, mostDamageUnjustified)
    if creature:isMonster() and killer:isMonster() then
        return -- returning false would serve as same result as return here, just exits the script. So if monster killed monster, do nothing.
    end

    if not lastHitUnjustified and not mostDamageUnjustified then
        return -- exits script if this wasn't an unjust kill
    end

    if killer and mostDamageKiller then -- makes sure neither are nil
        if killer:isPlayer() and mostDamageKiller:isPlayer() then -- checks if both are player class
            if killer:getGuid() == mostDamageKiller:getGuid() then -- if both are one in the same
                return -- exits script, because we are looking for multiple players in an unjust kill
            end
            --- here we now know it has to be at least two players who took part in the kill
            corpse:remove() -- we destroyed the corpse so those pker's don't get it!
            return -- scripts purpose is served, we exit
        end
    end
end

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:

<event type="kill" name="bossKill" script="bosskill.lua" />

You can then call the event in a script like so:

Example: bosskill.lua

function onKill(killer, victim)
    if not killer:isPlayer() then
        return -- killer is not a player, no need to execute any further.
    end
    if not victim:isMonster() and victim:getType():isBoss() then
        return -- victim is not a boss, no need to execute any further.
    end
    -- anything here, happens because the killer is a player, and the victim is a monsterType, that returns true with :isBoss()
    killer:sendTextMessage(MESSAGE_INFO_DESCR, "Congratulations you killed a Boss!")
end

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:

<event type="advance" name="fishingLevels" script="fishinglevels.lua" />

You can then call the event in a script like so:

Example: fishinglevels.lua

function onAdvance(player, skill, oldlevel, newlevel)
    if not skill == SKILL_FISHING then -- we only run this if the skill gained was fishing skill
        return true
    end
    if newlevel >= 100 then
        player:getPosition():sendMagicEffect(CONST_ME_PLUNGING_FISH)
        player:sendTextMessage(MESSAGE_EVENT_ADVANCE, "Congratulations you are officially a BIG FISHER!")
    end
    return true
end

: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:

<event type="modalwindow" name="coolMenu" script="modalwindow.lua" />

You can then call the event in a script like so:

Example: modalwindow.lua

function onModalWindow(player, modalWindowId, buttonId, choiceId)
    -- TODO
end

: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:

<event type="textedit" name="bookPassword" script="bookPassword.lua" />

You can then call the event in a script like so:

Example: bookPassword.lua

function onTextEdit(player, modalWindowId, buttonId, choiceId)
    -- TODO
end

: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:

<event type="healthchange" name="cursedhealth" script="cursedhealth.lua" />

You can then call the event in a script like so:

Example: cursedhealth.lua

function onHealthChange(creature, attacker, primaryDamage, primaryType, secondaryDamage, secondaryType, origin)
    -- TODO
end

: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:

<event type="manachange" name="buffedMana" script="buffedMana.lua" />

You can then call the event in a script like so:

Example: buffedMana.lua

function onManaChange(creature, attacker, primaryDamage, primaryType, secondaryDamage, secondaryType, origin)
    -- TODO
end

: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:

<event type="extendedopcode" name="opCode" script="opCode.lua" />

You can then call the event in a script like so:

Example: opCode.lua

function onExtendedOpCode(player, opcode, buffer)
    -- TODO
end

:TODO:

PreviousChatChannelNextGlobalEvents

Last updated