Scripting

Script Structure

onLogin(player)

Parameters:

• player: Player logging in.

Return Value:

• true: Player will be allowed to log in.

• false: Player will not be allowed to log in, they will be kicked back to the character selection screen.

Example

local allowed_ips = {"127.0.0.1"}

function onLogin(player)
    -- Whitelisted IP system
    local ip = player:getIp()
    if table.contains(allowed_ips, ip) then
        return true
    end
    return false
end

onLogout(player)

Parameters:

• player: Player logging out.

Return Value:

• true: Allows the player to log out, returning them to the character selection screen.

• false: Will not allow the player to log out.

Example

function onLogout(player)
    -- Custom message for players attempting to log out in a fight
    if player:hasCondition(CONDITION_INFIGHT, CONDITIONID_DEFAULT) then
        player:sendCancelMessage("You may not log out in the middle of a fight.")
        return false
    end
    return true
end

onThink(creature, interval)

Parameters:

• creature: Creature that is "thinking".

• interval: Interval at which the creature "thinks" (1000 milliseconds).

Return Value:

• None

Example

function onThink(creature, interval)
    -- Remove 1 health from creature at each think interval
    creature:addHealth(-1)
end

onPrepareDeath(creature, killer)

Parameters:

• creature: Creature who is preparing to die.

• killer: Creature userdata of the killer.

Return Value:

• true: Creature will die.

• false: Creature will stay alive and in-game.

Example

function onPrepareDeath(creature, killer)
    -- If creature name is Delusion, teleport to 1000, 1000, 7, heal back to full health, and take no death penalty
    if creature:getName() == "Delusion" then
        creature:teleportTo(Position(1000, 1000, 7))
        creature:addHealth(creature:getMaxHealth())
        return false
    end
    return true
end

onDeath(creature, corpse, lasthitkiller, mostdamagekiller, lasthitunjustified, mostdamageunjustified)

Parameters:

• creature: Creature that just died.

• corpse: Item of the creature's corpse.

• lastHitKiller: Creature that dealt the killing blow.

• mostDamageKiller: Creature who did the most damage.

• lastHitUnjustified:

• true: The last hit killer was dealt an unjustified frag.

  false: The last hit killer was not dealt an unjustified frag.

• mostDamageUnjustified:

• true: The most damage killer was dealt an unjustified frag.

  false: The most damage killer was not dealt an unjustified frag.

Return Value:

• None

Example

function onDeath(creature, corpse, lasthitkiller, mostdamagekiller, lasthitunjustified, mostdamageunjustified)
    -- Increment the number of deaths the player has
    if creature:isPlayer() then
        local deaths = creature:getStorageValue(12345)
        creature:setStorageValue(12345, (deaths == -1 and 0 or deaths) + 1)
    end
end

onKill(creature, target)

Parameters:

• creature: Creature that is killing the target.

• target: Target being killed.

Return Value:

• true: The target will die.

• false: The target will not die.

Example

function onKill(creature, target)
    -- Increment the number of creature kills the player has
    if creature:isPlayer() then
        local kills = creature:getStorageValue(123123)
        creature:setStorageValue(123123, (kills == -1 and 0 or kills) + 1)
    end    
    return true
end

onAdvance(player, skill, oldLevel, newLevel)

Parameters:

• player: Player who's advancing in a skill.

• skill: Skill enum (skills_t in enums.h)

• SKILL_FIST

  SKILL_CLUB

  SKILL_SWORD

  SKILL_AXE

  SKILL_DISTANCE

  SKILL_SHIELD

  SKILL_FISHING

  SKILL_MAGLEVEL

  SKILL_LEVEL

• oldLevel: Previous skill level before advancing.

• newLevel: New skill level after advancing.

Return Value:

• true: Player will be allowed to advance to that new skill level.

• false: Player will stay at their old skill level.

Example

function onAdvance(player, skill, oldLevel, newLevel)
    if skill == SKILL_LEVEL then
        player:sendTextMessage(MESSAGE_STATUS_CONSOLE_BLUE, "You have advanced to level " .. newLevel .. "!")
    end
    return true
end

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

Parameters:

• creature: Creature who's health is changing.

• attacker: Creature who's attacking.

• primaryDamage: Primary damage value dealt to creature.

• primaryType: Primary damage type (CombatType_t in enums.h)

• COMBAT_NONE

  COMBAT_PHYSICALDAMAGE

  COMBAT_ENERGYDAMAGE

  COMBAT_EARTHDAMAGE

  COMBAT_FIREDAMAGE

  COMBAT_UNDEFINEDDAMAGE

  COMBAT_LIFEDRAIN

  COMBAT_MANADRAIN

  COMBAT_HEALING

  COMBAT_DROWNDAMAGE

  COMBAT_ICEDAMAGE

  COMBAT_HOLYDAMAGE

  COMBAT_DEATHDAMAGE

• secondaryDamage: Secondary damage value dealt to creature.

• secondaryType: Secondary damage type (CombatType_t in enums.h, same values as primaryType)

• origin: Where the damage originated from (CombatOrigin in enums.h)

• ORIGIN_NONE

  ORIGIN_CONDITION

  ORIGIN_SPELL

  ORIGIN_MELEE

  ORIGIN_RANGED

Return Value:

• primaryDamage, primaryType, secondaryDamage, secondaryType

• primaryDamage: Changed primary damage value to be used as the real damage given to the creature.

  primaryType: Changed primary damage type to be used as the real primary damage type given to the creature.

  secondaryDamage: Changed secondary damage value to be used as the real damage given to the creature.

  secondaryType: Changed secondary damage type to be used as the real secondary damage type given to the creature.

Example

function onHealthChange(creature, attacker, primaryDamage, primaryType, secondaryDamage, secondaryType, origin)
    -- Creature with the name Delusion will take zero damage from health
    if creature:getName() == "Delusion" then
        primaryDamage = 0
        secondaryDamage = 0
    end
    return primaryDamage, primaryType, secondaryDamage, secondaryType
end

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

Parameters:

• creature: Creature who's health is changing.

• attacker: Creature who's attacking.

• primaryDamage: Primary damage value dealt to creature.

• primaryType: Primary damage type (CombatType_t in enums.h)

• secondaryDamage: Secondary damage value dealt to creature.

• secondaryType: Secondary damage type (CombatType_t in enums.h, same values as primaryType)

• origin: Where the damage originated from (CombatOrigin in enums.h)

Return Value:

• primaryDamage, primaryType, secondaryDamage, secondaryType

• primaryDamage: Changed primary damage value to be used as the real damage given to the creature.

  primaryType: Changed primary damage type to be used as the real primary damage type given to the creature.

  secondaryDamage: Changed secondary damage value to be used as the real damage given to the creature.

  secondaryType: Changed secondary damage type to be used as the real primary damage type

  given to the creature.

Example

function onManaChange(creature, attacker, primaryDamage, primaryType, secondaryDamage, secondaryType, origin)
    -- Creature with the name Delusion will take zero damage from mana
    if creature:getName() == "Delusion" then
        primaryDamage = 0
        secondaryDamage = 0
    end
    return primaryDamage, primaryType, secondaryDamage, secondaryType
end

onTextEdit(player, item, text)

Parameters:

• player: Player altering the text attribute of an item (i.e. a book).

• item: Item being edited.

• text: New text being written to the item.

Return Value:

• true: Saves the text to the item.

• false: Does not save the text to the item.

Example

function onTextEdit(player, item, text)
    -- Allow the item's text to be edited if I'm writing it
    if player:getName() == "Delusion" then
        return true
    end
    return false
end

onModalWindow(player, modalWindowId, buttonId, choiceId)

Parameters:

• player: Player receiving the modal window.

• modalWindowId: Reference ID of the modal window.

• buttonId: Button ID pressed.

• choiceId: Choice ID selected.

Return Value:

• None

Example

function onModalWindow(player, modalWindowId, buttonId, choiceId)
    -- Simply log user selection from the modal window
    print(player:getName() .. " selected Button ID " .. buttonId .. " with choice " .. choiceId)
end

onExtendedOpcode(player, opcode, buffer)

Parameters:

• player: Player receiving the opcode.

• opcode: Opcode sent from OTClient.

• buffer: Data sent (type: string)

Return Value:

• None

Example

function onExtendedOpcode(player, opcode, buffer)
    -- Log the opcode + data received
    print(player:getName() .. " received opcode " .. opcode .. " with data containing: " .. buffer)
end

Notes

When a creature dies, the event order is onPrepareDeath -> onKill -> onDeath, assuming they each return true (besides onDeath, at that point the death is decided to go through).