# Action

### onUse(player, item, fromPosition, itemEx, toPosition, isHotkey)

> * **player**  -- 1st arg/parameter /***userdata***/  =  The **player** who uses the item.
> * **item** -- 2nd arg/parameter/ ***userdata***/ = The first **item** player uses/use with.
> * **fromPosition** - 3rd arg/parameter/***userdata***/ = The **position** the first item is at.
> * **itemEx** -- 4th arg/parameter/***userdata***/ = The target of item's *Use With*, can be **item** or **creature**
> * **toPosition** - 5th arg/parameter/ ***userdata***/ = The **position** the first item is used on, with crosshairs.
> * **isHotkey** - 6th arg/parameter/ ***boolean***/ = Did the player use item via hot key? **True/False**.

1. **onUse** is called whenever an item registered to the action is used. 
2. You can register actions in data/actions/**actions.xml**

   ```markup
   <action itemid="4856" script="test.lua" />
   ```

   ```markup
   <action fromid="2146" toid="2147" script="other/enchanting.lua" />
   ```
3. Alternatively you can use [revscript](#revscript-action) method to register via *lua*, by saving a .lua file in data/scripts folder.

**After you have registered your action in actions.xml you can call the event in a script like so:**

```lua
function onUse(player, item, fromPosition, target, toPosition, isHotkey)  -- can name the arguments what you like.
    local SwordLevel = player:getSkillLevel(SKILL_SWORD)
    if SwordLevel < 70 then
        player:sendCancelMessage("This technique requires a sword fighting skill of 70 or higher.")
        return false
    end

    if not item:hasAttribute(ITEM_ATTRIBUTE_EXTRADEFENSE) then
        player:sendCancelMessage("Only swords known for their well balance and extra defense are suitable for this task.")
        return false
    end

    if fromPosition:isSightClear(toPosition) then 
        player:sendCancelMessage("You must have a clear path to your target")
        return false
    end

    if target:isPlayer() then 
        player:sendCancelMessage("To execute this technique properly, the target needs to be a player.")
        return false
    end

    if isHotkey then 
        player:sendCancelMessage("You can't use this item with a hotkey!")
        return false
    end
     -- Executing the technique

    -- Teleport to the position
    player:teleportTo(toPosition)

    -- Configure bleeding damage
    local bleed = {
        damage=50,
        rounds=10,
        interval=1
    }
    -- Apply deadly bleeding attack on target
    player:addDamageCondition(target, CONDITION_BLEEDING, DAMAGELIST_CONSTANT_PERIOD, bleed.damage, bleed.interval, bleed.rounds)

    -- Warn target that they just got slashed hard from player:getName and their blood is puring out!
    target:sendTextMessage(MESSAGE_STATUS_WARNING, "You just recieved a blood gushing wound from "..player:getName().."'s deadly sword technique!")
   return true
end
```

## Revscript Action

**Revscript** share the same event **onUse()** with the same arguments listed above.

To access any events through *revscripts*, you must create a variable first to access the interface

{% hint style="warning" %}

> you **must** have **one** variable **per event** callback no matter which type of interface you wish to access!
> {% endhint %}

Here is an example.

```lua
local swordTechnique = Action() -- we created a variable to access Action interface
```

**Action** has the available ***methods*** and ***event*** to use with ***revscripts***

> **Event**
>
> * [**onUse**](#action.onuse-player-item-fromposition-itemex-toposition-ishotkey)(player, item, fromPosition, itemEx, toPosition, isHotkey)
>
> **Methods**
>
> * action:**register**() -- Registers the action **event**.&#x20;
> * [action:**id**(***x***)](#action-id)    -- Registers items with **id** ***x*** for event
> * [action:**aid**(***x***)](#action-aid) -- Registers items with **action id** ***x*** for event
> * [action:**uid**(***x***)](#action-uid) -- Registers items with **unique id** ***x*** for event
> * [action:**allowFarUse**(t/f)](#action-allowfaruse) -- Allow far use? ***True/False***
> * [action:**blockWalls**(t/f)](#action-blockwalls) -- Do walls block item usage? ***True/False***
> * [action:**checkFloor**(t/f)](#action-checkfloor) -- Are we on same floor as target? ***True/False***

## Action:id()

```lua
local swordTechnique = Action() -- we created a variable to access Action interface

swordTechnique:id(2376) -- sword's itemId to register for event
```

## Action:aid()

```lua
local swordTechnique = Action() -- we created a variable to access Action interface

swordTechnique:aid(15428) -- an actionId to register for event
```

## Action:uid()

```lua
local swordTechnique = Action() -- we created a variable to access Action interface

swordTechnique:uid(1337) -- a uniqueId to register for event
```

## Action:allowFarUse()

```lua
local swordTechnique = Action() -- we created a variable to access Action interface

swordTechnique:allowFarUse(true) -- True/False. True we can be more than one square away to use
```

## Action:blockWalls()

```lua
local swordTechnique = Action() -- we created a variable to access Action interface

swordTechnique:blockWalls(true) -- True/false. True and walls will block usage of item.
```

## Action:checkFloor()

```lua
local swordTechnique = Action() -- we created a variable to access Action interface

swordTechnique:checkFloor(true) -- True/false. True and we can only use item on same floor as us.
```

**To register an Action script using the Revscript Method, please first ensure it is saved at proper directory location, inside you data/scripts folder, then you can see the same action as above demonstrated as a revscript like so:**

```lua
local swordTechnique = Action() -- we created a variable to access Action interface

-- Here we register items to use for action, using swordTechnique variable.
swordTechnique:id(2376) -- sword's itemId to register for event
swordTechnique:aid(15428) -- an actionId to register for event
swordTechnique:uid(1337) -- a uniqueId to register for event

-- Here we configure our other action methods, still using swordTechniqu variable.
swordTechnique:allowFarUse(true)
swordTechnique:checkFloors(true)
swordTechnique:blockWalls(true)

 --- Here we call the event using the same swordTechnique variable.
function swordTechnique.onUse(player, item, fromPosition, target, toPosition, isHotkey) -- can name the arguments what you like.

    local SwordLevel = player:getSkillLevel(SKILL_SWORD)
    if SwordLevel < 70 then
        player:sendCancelMessage("This technique requires a sword fighting skill of 70 or higher.")
        return false
    end


    if not item:hasAttribute(ITEM_ATTRIBUTE_EXTRADEFENSE) then
        player:sendCancelMessage("Only swords known for their well balance and extra defense are suitable for this task.")
        return false
    end


    if fromPosition:isSightClear(toPosition) then 
        player:sendCancelMessage("You must have a clear path to your target")
        return false
    end


    if target:isPlayer() then 
        player:sendCancelMessage("To execute this technique properly, the target needs to be a player.")
        return false
    end


    if isHotkey then 
        player:sendCancelMessage("You can't use this item with a hotkey!")
        return false
    end

    -- Executing the technique

    -- Teleport to the position
    player:teleportTo(toPosition)

    -- Configure bleeding damage
    local bleed = {
        damage=50,
        rounds=10,
        interval=1
    }
    -- Apply deadly bleeding attack on target
    player:addDamageCondition(target, CONDITION_BLEEDING, DAMAGELIST_CONSTANT_PERIOD, bleed.damage, bleed.interval, bleed.rounds)

    -- Warn target that they just got slashed hard from player:getName and their blood is puring out!
    target:sendTextMessage(MESSAGE_STATUS_WARNING, "You just recieved a blood gushing wound from "..player:getName().."'s deadly sword technique!")

    return true
end

-- Finally after all logic is completed, we register the event, still using swordTechnique
swordTechnique:register()
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.otland.net/ots-guide/tfs-documentation/luascript-interface/action.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.