====== Mini API Events usage ======

==== What are the API events ====

You have probably used triggers if you are learning scripts and you may say "Script is so hard." but in reality, it is really similar to triggers, there are functions that **listen** for **events**, what **listening** or [[wp>Event_(computing)#Event_handler|Listeners]] are in programming, they are programs or specific functions within a program that waits for and responds to specific events or messages. In other words. It's a function that waits for an event and does something when that event happens.

That's why script and triggers are similar, because they both follow the structure

**Event:** Listener function

**Condition:** Conditionals, relational operators, logical operators, etc

**Action:** Executing the code


==== How to use the API events ====

To use the events one must call the function in the script

<code lua> ScriptSupportEvent:registerEvent([=[EventName]=],FunctionToExecute) </code>

Where we change **EventName** to the name of the event that we would like to listen, you can find the event list in [[developer_center:developer_editor|Script page]] on the Classes and the **FunctionToExecute** parameter is the function we would like to execute when that event happens (More info about functions [[https://www.lua.org/pil/5.html|Lua functions chapter]])

The function will return a table with all the important information such as

  * The id of the player or actor who triggered the event (**eventobjid**)
  * The id of the player or actor directly affected by the event (**toobjid**) __Not applicable to most events__
  * Parameters of the event 
	
===  Example ===

In this example when the player gets any buff the player who got the buff will send to chat "I got a buff!"
for this, we can use the event **Player.AddBuff** that returns the **eventobjid**, the parameter **buffid**

We first define a function and make it so it takes args that were returned
<code lua>

function GetBuff(params)
end
</code>

and we take the listener function and replace EventName with our event which is **Player.AddBuff**

<code lua> ScriptSupportEvent:registerEvent([=[Player.AddBuff]=], FunctionToExecute) </code>

and we replace **FunctionToExecute** with our function's name which is **GetBuff**

<code lua>ScriptSupportEvent:registerEvent([=[Player.AddBuff]=], GetBuff) </code>

**The code should look something like this:**
<code lua>

    function GetBuff(params) 
        
    end
    
    ScriptSupportEvent:registerEvent([=[Player.AddBuff]=], GetBuff)

</code>

But if we execute it right now it will do nothing, we need to add more functionality, and to make the player send a message to the chat we can use the **Chat:sendChat(content, targetuin)** method, it makes the player send a chat, the **content** argument is what we want the player to write, for this example we will use "I just got a buff" but you can change it to whatever you want, as long as its a string (More info about strings in [[https://www.lua.org/pil/2.4.html| Lua string page]] and the **targetuin** is the uid of the player that will send the message, but how do we get it?

The answer is that we need to use the function arguments variable name (in this case **params**) and we can retrieve them with **params.paramname** or **params['paramname']** we know that **Player.AddBuff** gives us the **eventobjid** and **buffid**. We want the eventobjid so we retrieve it as **params.eventobjid** or **params['eventobjid']**.

**The code now should look like this:**
<code lua>

    function GetBuff(params) 
        Chat:sendChat("I just got a buff!", params.eventobjid)
    end
    
    ScriptSupportEvent:registerEvent([=[Player.AddBuff]=], GetBuff)

</code>	

Now, if we execute it, our character should send a message when we get any buff!

That's great, but what if we want that when the player gets a specific buff the player send a message, and when the player gets another buff that is not the one that we want, we send another message, we can do it using the **if** and **else** conditional, we get the id of the buff we want using the id library, we get two ids when we select any buff, the first is the **buffid** and the second the **bufflv** but this is not important, so we add to our **GetBuff** function an if statement that checks if params.buffid == 40 (If the player got the buff with the id 40 then execute this code) and an else statement which sends our original message
<code lua>

    function GetBuff(params)
	if params.buffid == 40 then
            Chat:sendChat("I'm big now!", params.eventobjid)
	else
	    Chat:sendChat("I just got a buff!", params.eventobjid)
	end
    end

</code>	

Now, when we execute the game and get any buff we will get the original message, but if we get the buff we want, we will send "I'm big now!", now, you may ask if there's a more efficient way to get the params, and the answer is YES! We can declare a variable and then use it, the code would look like this and work the same, but we can use the variable name instead of the "params.paramname" or "params['paramname']

**Code:**

<code lua>
    function GetBuff(params)
        local curid = params.buffid
        local playerid = params.eventobjid
        
	    if CurId == 40 then
        	Chat:sendChat("I'm big now!", playerid)
	    else
		    Chat:sendChat("I just got a buff!", playerid)
	    end
    end
</code>