====== Mini API Custom event creation ======

In mini world, we already have a series of pre-defined events, but what if we want another level of complexity, another level of depth to our scripts? There is a way to create custom events and [[wp>Listener_(computing)|Listen]] to them, that can add a greater level of complexity to our scripts that can't be achieve without the use of custom events, it also can make our lives really easier because if there wasn't any way to handle these events, we would have to divide our script with extensive and overcomplicated logics, but if we create custom events, we can no longer worry about this, as we can just listen for events in other scripts and handle them there, making the code simpler to read, modularing the code, which is most of the time a good practice, this is especially useful if you are scripting with other persons, as it's no longer required to have all your variables, and all your functions in one script this makes scripting with others, a whole lot easier

===== How to create the custom events ======

To create these custom events, there is a method, the **Game:dispatchEvent(msg: string, customdata: any )**, in this method:
  * msg means the name of the custom event we would like to create
  * customdata is the data that we will pass along with the custom event, those are the args that the function that is executed when the event happens it will receive the data we passed **important: we must pass the data encoded in json**((wikipedia json page: [[wp>JSON|JSON]]))

==== Use example (without passing data) ====

Let's say that we want to create a custom event, but we dont want to pass any data, we take the **dispatchEvent** method, we replace msg, for the name of our custom event, for this example, i will call my event "myEvent", but you can call it whatever you want, we create a function that will get called whenever our event happens and then we add the listener function, the code should look like this.

<code>

function myEventFunction() 

    Chat:sendSystemMsg("My event was triggered!", 0)
    
end

ScriptSupportEvent:registerEvent("myEvent", myEventFunction)

</code>

And in another script, we will create this event, we will do it so this event gets called when 5 seconds have passed since game started, for this we create a function in this same script

our code should look like this

<code>
function GameStart()

Game:dispatchEvent("myEvent", {})
threadpool:wait(5)

end

ScriptSupportEvent:registerEvent([=[Game.Start]=], GameStart)

function myEventFunction() 

    Chat:sendSystemMsg("My event was triggered!", 0)
    
end

ScriptSupportEvent:registerEvent("myEvent", myEventFunction)

</code>

==== Use example (passing data) ====

Now, let's say that you want to create a custom event, but you want to pass variables, for this we will create two scripts, the first one will be the sender and the second one will be the receiver script

=== Sender scripts ===

In the sender script, we first create a function and after that, we add the listener function in the Game.Start event, the data that we want to send we will store it in a table, like this

**example: **
**local data = {Sent = "Yes", myData = 123456789}**

**Our code should look like this**
<code>

function GameStart() 

    local data = {Sent = "Yes", Uid = 123456789}
    
end

ScriptSupportEvent:registerEvent([=[Game.Start]=], GameStart)

</code>

After this, we use a [[developer_center:developer_editor:script:miniapi_tutorialerrorhandling|PCALL]], the function that we are going to call is called JSON.encode, and we also pass this: JSON, ourDataTable

Code should look like this:

<code>

function GameStart() 

    local data = {Sent = "Yes", Uid = 123456789}
    local sucess, result = pcall(JSON.encode, JSON, data)
   
end

ScriptSupportEvent:registerEvent([=[Game.Start]=], GameStart)

</code>

We then handle for errors, because errors are uncommon, but they can happen, and we want our script to print whenever an error happens (([[developer_center:developer_editor:script:miniapi_tutorialerrorhandling|Error handling]] tutorial))

so we add an if statement that if not sucess, we print there was an error and the error status and we leave the else statement empty to use it after this

Code should look like this:

<code>
function GameStart() 

    print("CustomEvent Test")
    local data = {Sent = "Yes", Uid = 123456789}
    local sucess, result = pcall(JSON.encode, JSON, data)
    
    if not sucess then
        
        print("There was an error.")
        print(result)
        
    else
        
    end    

end

ScriptSupportEvent:registerEvent([=[Game.Start]=], GameStart)
</code>

After that, we add to the else, we add the method we discussed before, to the first argument, we put the name, and the first argument we do this {customdata = result}

<WRAP center round tip 60%>

This is how it looks if you didn't understand

Game:dispatchEvent("myEvent", {customdata = result})

</WRAP>

Code should look like this:

<code>

function GameStart() 

    print("CustomEvent Test")
    local data = {Sent = "Yes", Uid = 123456789}
    local sucess, result = pcall(JSON.encode, JSON, data)
    
    if not sucess then
        
        print("There was an error.")
        print(result)
        
    else
        
        print("Encoded without errors.")
        local ret = Game:dispatchEvent("myEvent", {customdata = result})
        
    end    

end

ScriptSupportEvent:registerEvent([=[Game.Start]=], GameStart)

</code>

Now, let's go to the receiver script

=== Receiver script ===

In this script its a lot simpler, as we just need to make a funtion that takes params and put it in our listener function with the name of our function

**code should look like this:**

<code>

function myEventFunction(params) 

ScriptSupportEvent:registerEvent("myEvent", myEventFunction)

</code>

Now, if we want to retrieve a variable, we can retrieve it this way.

**params.CurEventParam.CloudValue.NameOfYourVal**

So, for example, if i want to get the "Sent" variable, i can do this

**params.CurEventParam.CloudValue.Sent**

Code example:

<code>

function myEventFunction(params) 

    Chat:sendSystemMsg("My event was triggered!", 0)
    Chat:sendSystemMsg("Is NotSoPr17  Cool: ".. params.CurEventParam.CloudValue.Sent,0)
end

ScriptSupportEvent:registerEvent("myEvent", myEventFunction)

</code>

**And just like that we can retrieve the values!!**