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).

PreviousRegistrationNextRevscriptsys

Last updated