Scripting

Script Structure

onEquipItem(player, item, slot)

Parameters:

• player: Player equipping the item.

• item: Item being equipped.

• slot: Slot where the item is being equipped.

• CONST_SLOT_HEAD

  CONST_SLOT_NECKLACE

  CONST_SLOT_BACKPACK

  CONST_SLOT_ARMOR

  CONST_SLOT_RIGHT

  CONST_SLOT_LEFT

  CONST_SLOT_LEGS

  CONST_SLOT_FEET

  CONST_SLOT_AMMO

  CONST_SLOT_RING

Return Value:

• true: Item will be equipped to the slot.

• false: Item will not be equipped to the slot, sends player the message "You cannot equip this item".

Example:

function onEquipItem(player, item, slot)
    -- Only allow myself to equip the item
    if player:getName() == "Delusion" then
        return true
    end
    return false
end

onDeEquipItem(player, item, slot)

Parameters:

• player: Player removing the item from their inventory.

• item: Item being removed.

• slot: Slot where the item is located (see onEquipItem slot for slot enums)

Return Value:

• true: Item will be de-equipped from the slot.

• false: Item will not be de-equipped from the slot.

Example:

function onDeEquipItem(player, item, slot)
    -- Disallow de-equip for some arbitrary condition met with a player's storage value
    if player:getStorageValue(123123) == 1 then
        return false
    end
    return true
end

onStepIn(creature, item, position, fromPosition)

Parameters:

• creature: Creature moving (includes Players / Monsters / NPCs).

• item: Item the creature is moved to.

• position: Position the creature is moving to.

• fromPosition: Position the creature is moving from.

Return Value:

• None

Example:

function onStepIn(creature, item, position, fromPosition)
    -- Push the creature back if they are not a player
    if not creature:isPlayer() then
        creature:teleportTo(fromPosition, true)
    end
end

onStepOut(creature, item, position, fromPosition)

Parameters:

• creature: Creature moving (includes Players / Monsters / NPCs).

• item: Item the creature is moved to.

• position: Position the creature is moving to.

• fromPosition: Position the creature is moving from.

Return Value:

• None

Example:

function onStepOut(creature, item, position, fromPosition)
    -- Send a simple magic effect trailing the creature
    fromPosition:sendMagicEffect(CONST_ME_MAGIC_RED)
end

onAddItem(moveitem, tileitem, pos)

Parameters:

• moveitem: Item being moved.

• tileitem: The item on top of the tile item stack where the item is being thrown to.

• pos: Position the item is being moved to.

Return Value:

• true: Item will be thrown at the destination.

• false: Item will not be moved to the destination.

Example:

local accepted_items = {2148, 2160}

function onAddItem(moveitem, tileitem, pos)
    -- Only allow gold & crystal coins to be thrown
    if table.contains(accepted_items, moveitem:getId()) then
        return true
    end
    return false
end

onRemoveItem(moveitem, tileitem, pos)

Parameters:

• moveitem: Item being moved.

• tileitem: The item on top of the tile item stack where the item is being thrown to.

• pos: Position the item is being moved to.

Return Value:

• true: Item will be removed from the tile.

• false: Item will not be removed from the tile.

Example:

function onRemoveItem(moveitem, tileitem, pos)
    local tile = Tile(pos)
    -- Allow item to be removed if there are no creatures on top of the tile
    if tile and tile:getCreatureCount() == 0 then
        return true
    end
    return false
end