diff --git a/functions/Event/addEvent.yaml b/functions/Event/addEvent.yaml index 6babf7f6..8f1f45b7 100644 --- a/functions/Event/addEvent.yaml +++ b/functions/Event/addEvent.yaml @@ -1,8 +1,8 @@ # Scraped from: https://wiki.multitheftauto.com/wiki/AddEvent shared: name: addEvent - description: This function allows you to register a custom [event](/wiki/Event "Event"). - Custom events function exactly like the built\-in events. See [event system](/wiki/Event_system + description: This function allows you to register a custom [event](/reference/Event_System "Event"). + Custom events function exactly like the built\-in events. See [event system](/reference/Event_System "Event system") for more information on the event system. parameters: - name: eventName @@ -11,19 +11,14 @@ shared: - name: allowRemoteTrigger type: bool description: A boolean specifying whether this event can be called remotely using - triggerClientEvent / triggerServerEvent or not. + [triggerClientEvent](/reference/triggerClientEvent "TriggerClientEvent") / [triggerServerEvent](/reference/triggerServerEvent "TriggerServerEvent") or not. default: 'false' examples: - path: examples/addEvent-1.lua description: This example will define a new event calledonSpecialEvent. - side: server - - path: examples/addEvent-2.lua - description: 'You can then trigger this event later on using:' - side: server returns: values: - type: bool name: value description: Returns true if the event was added successfully, false if the event was already added. - requires_review: true diff --git a/functions/Event/addEventHandler.yaml b/functions/Event/addEventHandler.yaml index c3a77f5a..039615f1 100644 --- a/functions/Event/addEventHandler.yaml +++ b/functions/Event/addEventHandler.yaml @@ -1,22 +1,22 @@ # Scraped from: https://wiki.multitheftauto.com/wiki/AddEventHandler shared: name: addEventHandler - description: This function will add an [event](/wiki/Event "Event") handler. An + description: This function will add an [event](/reference/Event_System "Event System") handler. An event handler is a function that will be called when the event it's attached to - is triggered. See [event system](/wiki/Event_system "Event system") for more information + is triggered. See [event system](/reference/Event_System "Event System") for more information on how the event system works. parameters: - name: eventName type: string - description: 'The name of the event you want to attach the handler function to. - Note: The maximum allowed length is 100 ASCII characters (that is, English letters - and numerals)' + description: 'The name of the [event](/reference/Event_System "Event System") you want to attach the handler function to. + **Note: The maximum allowed length is 100 ASCII characters (that is, English letters + and numerals)**' - name: attachedTo type: element - description: The element you wish to attach the handler to. The handler will only + description: The [element](/reference/Element "Element") you wish to attach the handler to. The handler will only be called when the event it is attached to is triggered for this element, or one of its children. Often, this can be the root element (meaning the handler - will be called when the event is triggered for any element). + will be called when the event is triggered for *any* element). - name: handlerFunction type: function description: The handler function you wish to call when the event is triggered. @@ -25,14 +25,19 @@ shared: - name: propagate type: bool description: A boolean representing whether the handler will be triggered if the - event was propagated down or up the element tree (starting from the source), + event was propagated down or up the [element tree](/reference/Element_tree "Element tree") (starting from the source), and not triggered directly on attachedTo (that is, handlers attached with this argument set to false will only be triggered if source == this ). In GUI events you will probably want to set this to false . default: 'true' - name: priority type: string - description: MISSING_PARAM_DESC + description: | + A string representing the trigger order priority relative to other event handlers of the same name. Possible values are: + + "high" + "normal" + "low" default: '"normal"' examples: - path: examples/addEventHandler-1.lua @@ -52,15 +57,15 @@ shared: On the same note, for multiple reasons, it isn't a good idea to export the same functions that you use locally as remote event handlers. - type: info - content: See Event Source Element for a descriptive visualization of the event + content: See [Event Source Element](/reference/Event_Source_Element "Event Source Element") for a descriptive visualization of the event system handling an event trigger. - type: important - content: See Script security for how-to prevent cheaters from abusing event system - and element data . + content: See [Script security](/Script_security "Script security") for how-to prevent cheaters from abusing [event system](/reference/Event_System "Event system") + and [element data](/reference/Element_data "Element data"). - type: important content: Anything bound to a specific element will be run before other handlers that are bound to something higher in the element tree (like root) This means - that "high+10" bound to root won't trigger before "normal" bound directly to + that "high+10" bound to root **won't** trigger before "normal" bound directly to an element. - type: info content: Due to the additional set of global variables, the event-trigger specific @@ -73,4 +78,3 @@ shared: the same issues. It is recommended to adapt a good-natured distancing principle between code meant to run from local logic in separation to code meant to run from remote logic. - requires_review: true diff --git a/functions/Event/cancelEvent.yaml b/functions/Event/cancelEvent.yaml index 6edaa521..ef0b78c0 100644 --- a/functions/Event/cancelEvent.yaml +++ b/functions/Event/cancelEvent.yaml @@ -1,22 +1,23 @@ # Scraped from: https://wiki.multitheftauto.com/wiki/CancelEvent -client: +shared: name: cancelEvent description: This function is used to stop the automatic internal handling of events, for example this can be used to prevent an item being given to a player when they - walk over a pickup, by canceling the [onPickupUse](/wiki/OnPickupUse "OnPickupUse") + walk over a pickup, by canceling the [onPickupUse](/reference/onPickupUse "OnPickupUse") event. parameters: [] - examples: - - path: examples/cancelEvent-2.lua - description: This example prevents any damage to a player clientside by makingcancelEventan - event handler for theonClientPlayerDamageevent. - side: client returns: values: - type: bool name: value description: Always returns true . - requires_review: true + +client: + examples: + - path: examples/cancelEvent-2.lua + description: This example prevents any damage to a player clientside by making **cancelEvent** an + event handler for the [onClientPlayerDamage](/reference/onClientPlayerDamage "OnClientPlayerDamage") event. + server: name: cancelEvent description: This function is used to stop the automatic internal handling of events, @@ -26,19 +27,17 @@ server: parameters: - name: cancel type: bool - description: MISSING_PARAM_DESC + description: True to cancel, false to uncancel. default: 'true' - name: reason type: string - description: MISSING_PARAM_DESC + description: The reason for cancelling the event. default: '""' examples: - path: examples/cancelEvent-1.lua description: This example stops the player from entering a vehicle. - side: server returns: values: - type: bool name: value description: Always returns true . - requires_review: true diff --git a/functions/Event/cancelLatentEvent.yaml b/functions/Event/cancelLatentEvent.yaml index bf10f1d2..2ecbc645 100644 --- a/functions/Event/cancelLatentEvent.yaml +++ b/functions/Event/cancelLatentEvent.yaml @@ -1,11 +1,11 @@ # Scraped from: https://wiki.multitheftauto.com/wiki/CancelLatentEvent -client: +shared: name: cancelLatentEvent description: Stops a latent event from completing parameters: - name: handle type: int - description: A handle previous got from getLatentEventHandles . + description: A handle previous got from [getLatentEventHandles](/reference/getLatentEventHandles "GetLatentEventHandles"). examples: - path: examples/cancelLatentEvent-1.lua description: '' @@ -19,7 +19,7 @@ client: name: value description: Returns a true if the latent event was successfully cancelled, or false if it was not - requires_review: true + server: name: cancelLatentEvent description: Stops a latent event from completing @@ -29,7 +29,7 @@ server: description: The player who is receiving the event. - name: handle type: int - description: A handle previous got from getLatentEventHandles . + description: A handle previous got from [getLatentEventHandles](/reference/getLatentEventHandles "GetLatentEventHandles"). examples: - path: examples/cancelLatentEvent-2.lua description: '' @@ -43,4 +43,3 @@ server: name: value description: Returns a true if the latent event was successfully cancelled, or false if it was not - requires_review: true diff --git a/functions/Event/examples/addEvent-1.lua b/functions/Event/examples/addEvent-1.lua index 623ea382..60517704 100644 --- a/functions/Event/examples/addEvent-1.lua +++ b/functions/Event/examples/addEvent-1.lua @@ -7,4 +7,8 @@ function specialEventHandler ( text ) end -- Add it as a handler for our event -addEventHandler ( "onSpecialEvent", root, specialEventHandler ) \ No newline at end of file +addEventHandler ( "onSpecialEvent", root, specialEventHandler ) + +-- You can then trigger this event later on using: +triggerEvent ( "onSpecialEvent", root, "test" ) +-- This will cause the handler to be triggered, so "test" will be output to the chatbox. \ No newline at end of file diff --git a/functions/Event/examples/addEvent-2.lua b/functions/Event/examples/addEvent-2.lua deleted file mode 100644 index 59de24ab..00000000 --- a/functions/Event/examples/addEvent-2.lua +++ /dev/null @@ -1 +0,0 @@ -triggerEvent ( "onSpecialEvent", root, "test" ) \ No newline at end of file diff --git a/functions/Event/examples/cancelEvent-1.lua b/functions/Event/examples/cancelEvent-1.lua index 0c7b9f9c..21dbffb1 100644 --- a/functions/Event/examples/cancelEvent-1.lua +++ b/functions/Event/examples/cancelEvent-1.lua @@ -1,4 +1,4 @@ function onVehicleStartEnter() - cancelEvent() + cancelEvent() end addEventHandler("onVehicleStartEnter", root, onVehicleStartEnter) \ No newline at end of file diff --git a/functions/Event/examples/getLatentEventHandles-1.lua b/functions/Event/examples/getLatentEventHandles-1.lua index 01c2bbb5..f7671e68 100644 --- a/functions/Event/examples/getLatentEventHandles-1.lua +++ b/functions/Event/examples/getLatentEventHandles-1.lua @@ -1,5 +1,5 @@ --- CLIENT SIDE: - +-- ***************************************************************************** +-- CLIENT CODE local lastTriggerd = false addCommandHandler("trigger",function() @@ -12,8 +12,8 @@ addCommandHandler("trigger",function() lastTriggerd = #getLatentEventHandles() -- set the lastTriggerd with the id for last event triggerd end) --- SERVER SIDE: - +-- ***************************************************************************** +-- SERVER CODE addEvent("LatentEventsCheck",true) addEventHandler("LatentEventsCheck",root,function (thePlayer) outputChatBox("Latent trigger done from: " .. getPlayerName(thePlayer), root,math.random(255),0,0) diff --git a/functions/Event/examples/triggerClientEvent-1.lua b/functions/Event/examples/triggerClientEvent-1.lua index 5ec985c2..04be57c3 100644 --- a/functions/Event/examples/triggerClientEvent-1.lua +++ b/functions/Event/examples/triggerClientEvent-1.lua @@ -1,3 +1,12 @@ +-- ***************************************************************************** +-- SERVER CODE + greetingCommand ( playerSource, commandName ) + triggerClientEvent ( playerSource, "onGreeting", playerSource, "Hello World!" ) +end +addCommandHandler ( "greet", greetingCommand ) + +-- ***************************************************************************** +-- CLIENT CODE function greetingHandler ( message ) outputChatBox ( "The server says: " .. message ) end diff --git a/functions/Event/examples/triggerClientEvent-2.lua b/functions/Event/examples/triggerClientEvent-2.lua index 77559d51..e40c918f 100644 --- a/functions/Event/examples/triggerClientEvent-2.lua +++ b/functions/Event/examples/triggerClientEvent-2.lua @@ -1,4 +1,23 @@ -function greetingCommand ( playerSource, commandName ) - triggerClientEvent ( playerSource, "onGreeting", playerSource, "Hello World!" ) +-- ***************************************************************************** +-- SERVER CODE +function greetingCommandOne ( playerSource, commandName, playerName ) + if playerName then + local thePlayer = getPlayerFromName ( playerName ) + if thePlayer then + triggerClientEvent ( thePlayer, "onGreeting", thePlayer, "Hello World!" ) + else + -- invalid player name specified + end + else + -- No player name specified + end end -addCommandHandler ( "greet", greetingCommand ) \ No newline at end of file +addCommandHandler ( "greet_one", greetingCommandOne ) + +-- ***************************************************************************** +-- CLIENT CODE +function greetingHandler ( message ) + outputChatBox ( "The server says: " .. message ) +end +addEvent( "onGreeting", true ) +addEventHandler( "onGreeting", localPlayer, greetingHandler ) \ No newline at end of file diff --git a/functions/Event/examples/triggerClientEvent-3.lua b/functions/Event/examples/triggerClientEvent-3.lua index 5ec985c2..f31d43df 100644 --- a/functions/Event/examples/triggerClientEvent-3.lua +++ b/functions/Event/examples/triggerClientEvent-3.lua @@ -1,5 +1,16 @@ -function greetingHandler ( message ) - outputChatBox ( "The server says: " .. message ) +-- ***************************************************************************** +-- SERVER CODE +function commandFunction(source) + triggerClientEvent(source, "toClientSide", resourceRoot, "Hello World!") end -addEvent( "onGreeting", true ) -addEventHandler( "onGreeting", localPlayer, greetingHandler ) \ No newline at end of file +addCommandHandler("cool", commandFunction) + +-- ***************************************************************************** +-- CLIENT CODE +function nameFunction(message) + if source == resourceRoot then + outputChatBox(message) + end +end +addEvent("toClientSide", true ) +addEventHandler("toClientSide", resourceRoot, nameFunction) \ No newline at end of file diff --git a/functions/Event/examples/triggerClientEvent-4.lua b/functions/Event/examples/triggerClientEvent-4.lua deleted file mode 100644 index 1935a536..00000000 --- a/functions/Event/examples/triggerClientEvent-4.lua +++ /dev/null @@ -1,13 +0,0 @@ -function greetingCommandOne ( playerSource, commandName, playerName ) - if playerName then - local thePlayer = getPlayerFromName ( playerName ) - if thePlayer then - triggerClientEvent ( thePlayer, "onGreeting", thePlayer, "Hello World!" ) - else - -- invalid player name specified - end - else - -- No player name specified - end -end -addCommandHandler ( "greet_one", greetingCommandOne ) \ No newline at end of file diff --git a/functions/Event/examples/triggerClientEvent-5.lua b/functions/Event/examples/triggerClientEvent-5.lua deleted file mode 100644 index dad883e2..00000000 --- a/functions/Event/examples/triggerClientEvent-5.lua +++ /dev/null @@ -1,7 +0,0 @@ -function nameFunction(message) - if source == resourceRoot then - outputChatBox(message) - end -end -addEvent("toClientSide", true ) -addEventHandler("toClientSide", resourceRoot, nameFunction) \ No newline at end of file diff --git a/functions/Event/examples/triggerClientEvent-6.lua b/functions/Event/examples/triggerClientEvent-6.lua deleted file mode 100644 index 1f039ccf..00000000 --- a/functions/Event/examples/triggerClientEvent-6.lua +++ /dev/null @@ -1,4 +0,0 @@ -function commandFunction(source) - triggerClientEvent(source, "toClientSide", resourceRoot, "Hello World!") -end -addCommandHandler("cool", commandFunction) \ No newline at end of file diff --git a/functions/Event/examples/triggerEvent-1.lua b/functions/Event/examples/triggerEvent-1.lua index b6035d7e..338c059d 100644 --- a/functions/Event/examples/triggerEvent-1.lua +++ b/functions/Event/examples/triggerEvent-1.lua @@ -2,4 +2,7 @@ function onCustomEvent(chatMessage) outputChatBox(chatMessage) end addEvent("onCustomEvent", false) -- set to false, so this event won't be called from counter side - important security measure -addEventHandler("onCustomEvent", root, onCustomEvent) \ No newline at end of file +addEventHandler("onCustomEvent", root, onCustomEvent) + +--You can then trigger this event later on using: +triggerEvent("onCustomEvent", resourceRoot, "Hello, world!") \ No newline at end of file diff --git a/functions/Event/examples/triggerEvent-2.lua b/functions/Event/examples/triggerEvent-2.lua deleted file mode 100644 index 38aae111..00000000 --- a/functions/Event/examples/triggerEvent-2.lua +++ /dev/null @@ -1 +0,0 @@ -triggerEvent("onCustomEvent", resourceRoot, "Hello, world!") \ No newline at end of file diff --git a/functions/Event/examples/triggerLatentClientEvent-1.lua b/functions/Event/examples/triggerLatentClientEvent-1.lua index eccacc9c..7aa9d0ec 100644 --- a/functions/Event/examples/triggerLatentClientEvent-1.lua +++ b/functions/Event/examples/triggerLatentClientEvent-1.lua @@ -1,3 +1,14 @@ +-- ***************************************************************************** +-- SERVER CODE +if fileExists("text.txt") then + file = fileOpen("test.txt") --Open a file (you can create it yourself). + local data = fileRead(file,100*1024*1024) --Max 100 MB + fileClose(file) --Close File + triggerLatentClientEvent("onClientReadFile",5000,false,root,data) --trigger - Avoid triggering to root element (Read note above) +end + +-- ***************************************************************************** +-- CLIENT CODE addEvent("onClientReadFile",true) addEventHandler("onClientReadFile",root,function(data) local file = fileCreate("text.txt") --Save "data" into "text.txt" diff --git a/functions/Event/examples/triggerLatentClientEvent-2.lua b/functions/Event/examples/triggerLatentClientEvent-2.lua deleted file mode 100644 index ce43aad7..00000000 --- a/functions/Event/examples/triggerLatentClientEvent-2.lua +++ /dev/null @@ -1,6 +0,0 @@ -if fileExists("text.txt") then - file = fileOpen("test.txt") --Open a file (you can create it yourself). - local data = fileRead(file,100*1024*1024) --Max 100 MB - fileClose(file) --Close File - triggerLatentClientEvent("onClientReadFile",5000,false,root,data) --trigger - Avoid triggering to root element (Read note above) -end \ No newline at end of file diff --git a/functions/Event/examples/triggerLatentServerEvent-1.lua b/functions/Event/examples/triggerLatentServerEvent-1.lua index 4ce389ec..5c861203 100644 --- a/functions/Event/examples/triggerLatentServerEvent-1.lua +++ b/functions/Event/examples/triggerLatentServerEvent-1.lua @@ -1,6 +1,17 @@ +-- ***************************************************************************** +-- CLIENT CODE if fileExists("text.txt") file = fileOpen("test.txt") --Open a file (you can create it yourself). local data = fileRead(file,100*1024*1024) --Max 100 MB fileClose(file) --Close File triggerLatentServerEvent("onReadFile",5000,false,root,data) --trigger -end \ No newline at end of file +end + +-- ***************************************************************************** +-- SERVER CODE +addEvent("onReadFile",true) +addEventHandler("onReadFile",root,function(data) + local file = fileCreate("text.txt") --Save "data" into "text.txt" + fileWrite(file,data) + fileClose(file) +end) \ No newline at end of file diff --git a/functions/Event/examples/triggerLatentServerEvent-2.lua b/functions/Event/examples/triggerLatentServerEvent-2.lua deleted file mode 100644 index 539fc3dd..00000000 --- a/functions/Event/examples/triggerLatentServerEvent-2.lua +++ /dev/null @@ -1,6 +0,0 @@ -addEvent("onReadFile",true) -addEventHandler("onReadFile",root,function(data) - local file = fileCreate("text.txt") --Save "data" into "text.txt" - fileWrite(file,data) - fileClose(file) -end) \ No newline at end of file diff --git a/functions/Event/examples/triggerServerEvent-1.lua b/functions/Event/examples/triggerServerEvent-1.lua index 88735dd5..19f9245d 100644 --- a/functions/Event/examples/triggerServerEvent-1.lua +++ b/functions/Event/examples/triggerServerEvent-1.lua @@ -1,6 +1,47 @@ +-- ***************************************************************************** +-- CLIENT CODE function sendMessageToServer() local messageToSend = "Hello, world!" -- this string would be passed to server triggerServerEvent("onServerSendMessage", localPlayer, messageToSend) -- refer to the note on wiki page (under theElement), for understanding which element you should use as 2nd argument end -addCommandHandler("message", sendMessageToServer) \ No newline at end of file +addCommandHandler("message", sendMessageToServer) + +-- ***************************************************************************** +-- SERVER CODE +function onServerSendMessage(sentMessage) + if (not client) then -- 'client' points to the player who triggered the event, and should be used as security measure (in order to prevent player faking) + return false -- if this variable doesn't exists at the moment (for unknown reason, or it was the server who triggered this event), stop code execution + end + + local matchingSource = (source == client) -- check whether source element (2nd argument in triggerServerEvent) passed from client was the exact same player + + if (not matchingSource) then -- apparently it wasn't + return false -- so do not process this event + end + + local dataType = type(sentMessage) -- check type of data coming from client + local dataString = (dataType == "string") -- check whether it's string + + if (not dataString) then -- if it isn't string + return false -- stop our code here + end + + local minStringLength = 1 -- min allowed length of string + local maxStringLength = 64 -- max allowed length of string + local stringLength = utf8.len(sentMessage) -- get string length + local allowedStringLength = (stringLength >= minStringLength and stringLength <= maxStringLength) -- verify whether length is allowed + + if (not allowedStringLength) then -- if string length was exceeded + return false -- tell server to stop here + end + + local playerName = getPlayerName(client) -- get name of player who sent message + local chatMessage = playerName.." sent message from client: "..sentMessage + + outputChatBox(chatMessage, root, 255, 255, 255, false) -- output text sent from client-side for everyone on server + + -- useful utility for checking event data: https://wiki.multitheftauto.com/wiki/Script_security +end +addEvent("onServerSendMessage", true) -- 2nd argument should be set to true, in order to be triggered from counter side (in this case client-side) +addEventHandler("onServerSendMessage", root, onServerSendMessage) \ No newline at end of file diff --git a/functions/Event/examples/triggerServerEvent-2.lua b/functions/Event/examples/triggerServerEvent-2.lua index d4a7517a..4bb3f90b 100644 --- a/functions/Event/examples/triggerServerEvent-2.lua +++ b/functions/Event/examples/triggerServerEvent-2.lua @@ -1,36 +1,64 @@ -function onServerSendMessage(sentMessage) +-- ***************************************************************************** +-- CLIENT CODE +function sendTableToServer() + local tableToSent = {1, 2, 3} -- this table would be passed to server + + triggerServerEvent("onServerSendTable", resourceRoot, tableToSent) -- refer to the note on wiki page (under theElement), for understanding which element you should use as 2nd argument +end +addCommandHandler("table", sendTableToServer) + +-- ***************************************************************************** +-- SERVER CODE +function onServerSendTable(sentTable) if (not client) then -- 'client' points to the player who triggered the event, and should be used as security measure (in order to prevent player faking) return false -- if this variable doesn't exists at the moment (for unknown reason, or it was the server who triggered this event), stop code execution end - local matchingSource = (source == client) -- check whether source element (2nd argument in triggerServerEvent) passed from client was the exact same player + local matchingSource = (source == resourceRoot) -- check whether source element (2nd argument in triggerServerEvent) passed from client was resourceRoot if (not matchingSource) then -- apparently it wasn't return false -- so do not process this event end - local dataType = type(sentMessage) -- check type of data coming from client - local dataString = (dataType == "string") -- check whether it's string + local dataType = type(sentTable) -- check type of data coming from client + local dataTable = (dataType == "table") -- check whether it's table - if (not dataString) then -- if it isn't string + if (not dataTable) then -- if it isn't table return false -- stop our code here end - local minStringLength = 1 -- min allowed length of string - local maxStringLength = 64 -- max allowed length of string - local stringLength = utf8.len(sentMessage) -- get string length - local allowedStringLength = (stringLength >= minStringLength and stringLength <= maxStringLength) -- verify whether length is allowed + local minTableLength = 1 -- min allowed length of table + local maxTableLength = 3 -- max allowed length of table + local tableLength = (#sentTable) -- get table length + local matchingTableLength = (tableLength >= minTableLength and tableLength <= maxTableLength) -- verify whether length is allowed - if (not allowedStringLength) then -- if string length was exceeded + if (not matchingTableLength) then -- if table length was exceeded return false -- tell server to stop here end + local numbersOnly = true -- variable which will hold whether numbers only were in the table + + for _, numberValue in pairs(sentTable) do -- iterate through table + local valueType = type(numberValue) -- check type of each data + local numberType = (valueType == "number") -- check whether it's a number + + if (not numberType) then -- it isn't a number + numbersOnly = false -- since at least one of data inside isn't number, set it to false + break -- break the loop, no need to check further + end + end + + if (not numbersOnly) then -- it isn't numbers only table + return false -- stop code execution + end + local playerName = getPlayerName(client) -- get name of player who sent message - local chatMessage = playerName.." sent message from client: "..sentMessage + local sentNumbers = table.concat(sentTable, ", ") -- convert our table into list of numbers separated by comma + local chatMessage = playerName.." sent table with numbers from client: "..sentNumbers - outputChatBox(chatMessage, root, 255, 255, 255, false) -- output text sent from client-side for everyone on server + outputChatBox(chatMessage, root, 255, 255, 255, false) -- output numbers sent from client-side for everyone on server -- useful utility for checking event data: https://wiki.multitheftauto.com/wiki/Script_security end -addEvent("onServerSendMessage", true) -- 2nd argument should be set to true, in order to be triggered from counter side (in this case client-side) -addEventHandler("onServerSendMessage", root, onServerSendMessage) \ No newline at end of file +addEvent("onServerSendTable", true) -- 2nd argument should be set to true, in order to be triggered from counter side (in this case client-side) +addEventHandler("onServerSendTable", resourceRoot, onServerSendTable) \ No newline at end of file diff --git a/functions/Event/examples/triggerServerEvent-3.lua b/functions/Event/examples/triggerServerEvent-3.lua deleted file mode 100644 index d4a8b573..00000000 --- a/functions/Event/examples/triggerServerEvent-3.lua +++ /dev/null @@ -1,6 +0,0 @@ -function sendTableToServer() - local tableToSent = {1, 2, 3} -- this table would be passed to server - - triggerServerEvent("onServerSendTable", resourceRoot, tableToSent) -- refer to the note on wiki page (under theElement), for understanding which element you should use as 2nd argument -end -addCommandHandler("table", sendTableToServer) \ No newline at end of file diff --git a/functions/Event/examples/triggerServerEvent-4.lua b/functions/Event/examples/triggerServerEvent-4.lua deleted file mode 100644 index 1a8cc449..00000000 --- a/functions/Event/examples/triggerServerEvent-4.lua +++ /dev/null @@ -1,53 +0,0 @@ -function onServerSendTable(sentTable) - if (not client) then -- 'client' points to the player who triggered the event, and should be used as security measure (in order to prevent player faking) - return false -- if this variable doesn't exists at the moment (for unknown reason, or it was the server who triggered this event), stop code execution - end - - local matchingSource = (source == resourceRoot) -- check whether source element (2nd argument in triggerServerEvent) passed from client was resourceRoot - - if (not matchingSource) then -- apparently it wasn't - return false -- so do not process this event - end - - local dataType = type(sentTable) -- check type of data coming from client - local dataTable = (dataType == "table") -- check whether it's table - - if (not dataTable) then -- if it isn't table - return false -- stop our code here - end - - local minTableLength = 1 -- min allowed length of table - local maxTableLength = 3 -- max allowed length of table - local tableLength = (#sentTable) -- get table length - local matchingTableLength = (tableLength >= minTableLength and tableLength <= maxTableLength) -- verify whether length is allowed - - if (not matchingTableLength) then -- if table length was exceeded - return false -- tell server to stop here - end - - local numbersOnly = true -- variable which will hold whether numbers only were in the table - - for _, numberValue in pairs(sentTable) do -- iterate through table - local valueType = type(numberValue) -- check type of each data - local numberType = (valueType == "number") -- check whether it's a number - - if (not numberType) then -- it isn't a number - numbersOnly = false -- since at least one of data inside isn't number, set it to false - break -- break the loop, no need to check further - end - end - - if (not numbersOnly) then -- it isn't numbers only table - return false -- stop code execution - end - - local playerName = getPlayerName(client) -- get name of player who sent message - local sentNumbers = table.concat(sentTable, ", ") -- convert our table into list of numbers separated by comma - local chatMessage = playerName.." sent table with numbers from client: "..sentNumbers - - outputChatBox(chatMessage, root, 255, 255, 255, false) -- output numbers sent from client-side for everyone on server - - -- useful utility for checking event data: https://wiki.multitheftauto.com/wiki/Script_security -end -addEvent("onServerSendTable", true) -- 2nd argument should be set to true, in order to be triggered from counter side (in this case client-side) -addEventHandler("onServerSendTable", resourceRoot, onServerSendTable) \ No newline at end of file diff --git a/functions/Event/getCancelReason.yaml b/functions/Event/getCancelReason.yaml index 4383016f..85678a66 100644 --- a/functions/Event/getCancelReason.yaml +++ b/functions/Event/getCancelReason.yaml @@ -1,5 +1,5 @@ # Scraped from: https://wiki.multitheftauto.com/wiki/GetCancelReason -shared: +server: name: getCancelReason description: Gets the reason for cancelling an event. parameters: [] @@ -12,5 +12,4 @@ shared: values: - type: string name: value - description: Returns the reason that was given with cancelEvent - requires_review: true + description: Returns the reason that was given with [cancelEvent](/reference/cancelEvent "CancelEvent") diff --git a/functions/Event/getEventHandlers.yaml b/functions/Event/getEventHandlers.yaml index d6709c7f..a3141e43 100644 --- a/functions/Event/getEventHandlers.yaml +++ b/functions/Event/getEventHandlers.yaml @@ -6,20 +6,21 @@ shared: parameters: - name: eventName type: string - description: The name of the event. For example ( "onPlayerWasted" ). + description: The name of the event. - name: attachedTo type: element - description: The element attached to. - examples: - - path: examples/getEventHandlers-1.lua - description: '' - side: server - - path: examples/getEventHandlers-2.lua - description: This example removes all onClientMarkerHit event in current script. - side: client + description: The [element](/reference/Element "Element") attached to. returns: values: - type: table name: value description: Returns table with attached functions, empty table otherwise. - requires_review: true + +server: + examples: + - path: examples/getEventHandlers-1.lua + description: '' +client: + examples: + - path: examples/getEventHandlers-2.lua + description: This example removes all [onClientMarkerHit](/reference/onClientMarkerHit "onClientMarkerHit") event in current script. diff --git a/functions/Event/getLatentEventHandles.yaml b/functions/Event/getLatentEventHandles.yaml index ff72ff18..4bc2262d 100644 --- a/functions/Event/getLatentEventHandles.yaml +++ b/functions/Event/getLatentEventHandles.yaml @@ -1,17 +1,20 @@ # Scraped from: https://wiki.multitheftauto.com/wiki/GetLatentEventHandles -client: +shared: name: getLatentEventHandles description: Gets the currently queued latent events. The last one in the table - is always the latest event queued. Each returned handle can be used with [getLatentEventStatus](/wiki/GetLatentEventStatus - "GetLatentEventStatus") or [cancelLatentEvent](/wiki/CancelLatentEvent "CancelLatentEvent") + is always the latest event queued. Each returned handle can be used with [getLatentEventStatus](/reference/GetLatentEventStatus + "GetLatentEventStatus") or [cancelLatentEvent](/reference/CancelLatentEvent "CancelLatentEvent") parameters: [] - examples: [] + examples: + - path: examples/getLatentEventHandles-1.lua + description: This command is triggering an latent-event to server, and if you + write the command again and the trigger still didn't end then you have to wait. returns: values: - type: table name: value description: Returns a table of handles or false if invalid arguments were passed. - requires_review: true + server: name: getLatentEventHandles description: Gets the currently queued latent events. The last one in the table @@ -21,14 +24,8 @@ server: - name: thePlayer type: player description: The player who is receiving the events. - examples: - - path: examples/getLatentEventHandles-1.lua - description: This command is triggering an latent-event to server, and if you - write the command again and the trigger still didn't end then you have to wait. - side: server returns: values: - type: table name: value description: Returns a table of handles or false if invalid arguments were passed. - requires_review: true diff --git a/functions/Event/getLatentEventStatus.yaml b/functions/Event/getLatentEventStatus.yaml index d8e9c5bf..eb6dad79 100644 --- a/functions/Event/getLatentEventStatus.yaml +++ b/functions/Event/getLatentEventStatus.yaml @@ -1,23 +1,18 @@ # Scraped from: https://wiki.multitheftauto.com/wiki/GetLatentEventStatus -client: +shared: name: getLatentEventStatus description: Gets the status of one queued latent event. parameters: - name: handle type: int - description: A handle previous got from getLatentEventHandles . - examples: - - path: examples/getLatentEventStatus-1.lua - description: The example starts a latent event and outputs the status of the transfer - to the client console - side: client + description: A handle previous got from [getLatentEventHandles](/reference/GetLatentEventHandles "GetLatentEventHandles") . returns: values: - type: table name: value description: 'Returns a table with the following info or false if invalid arguments were passed:' - requires_review: true + server: name: getLatentEventStatus description: Gets the status of one queued latent event. @@ -27,7 +22,7 @@ server: description: The player who is receiving the event. - name: handle type: int - description: A handle previous got from getLatentEventHandles . + description: A handle previous got from [getLatentEventHandles](/reference/GetLatentEventHandles "GetLatentEventHandles") . examples: [] returns: values: @@ -35,4 +30,9 @@ server: name: value description: 'Returns a table with the following info or false if invalid arguments were passed:' - requires_review: true + +client: + examples: + - path: examples/getLatentEventStatus-1.lua + description: The example starts a latent event and outputs the status of the transfer + to the client console diff --git a/functions/Event/removeEventHandler.yaml b/functions/Event/removeEventHandler.yaml index d1b75ab7..55331ce1 100644 --- a/functions/Event/removeEventHandler.yaml +++ b/functions/Event/removeEventHandler.yaml @@ -1,25 +1,20 @@ # Scraped from: https://wiki.multitheftauto.com/wiki/RemoveEventHandler shared: name: removeEventHandler - description: This functions removes a handler function from an [event](/wiki/Event + description: This functions removes a handler function from an [event](/reference/Event_System "Event"), so that the function is not called anymore when the event is triggered. - See [event system](/wiki/Event_system "Event system") for more information on + See [event system](/reference/Event_System "Event system") for more information on how the event system works. parameters: - name: eventName type: string - description: The name of the event you want to detach the handler function from. + description: The name of the [event](/reference/Event_System "Event") you want to detach the handler function from. - name: attachedTo type: element - description: The element the handler was attached to. + description: The [element](/reference/Element "Element") the handler was attached to. - name: functionVar type: function description: The handler function that was attached. - examples: - - path: examples/removeEventHandler-1.lua - description: This example shows how to toggle a message on/off a screen with a - command. - side: client returns: values: - type: bool @@ -27,4 +22,9 @@ shared: description: Returns true if the event handler was removed successfully. Returns false if the specified event handler could not be found or invalid parameters were passed. - requires_review: true + +client: + examples: + - path: examples/removeEventHandler-1.lua + description: This example shows how to toggle a message on/off a screen with a + command. diff --git a/functions/Event/triggerClientEvent.yaml b/functions/Event/triggerClientEvent.yaml index 86abfa5d..3f57465e 100644 --- a/functions/Event/triggerClientEvent.yaml +++ b/functions/Event/triggerClientEvent.yaml @@ -1,36 +1,42 @@ # Scraped from: https://wiki.multitheftauto.com/wiki/TriggerClientEvent -shared: +server: name: triggerClientEvent - description: This function triggers an event previously registered on a client. + description: | + This function triggers an event previously registered on a client. This is the primary means of passing information between the server and the client. - Clients have a similar [triggerServerEvent](/wiki/TriggerServerEvent "TriggerServerEvent") + Clients have a similar [triggerServerEvent](/reference/triggerServerEvent "TriggerServerEvent") function that can do the reverse. You can treat this function as if it was an - asynchronous function call, using [triggerServerEvent](/wiki/TriggerServerEvent + asynchronous function call, using [triggerServerEvent](/reference/triggerServerEvent "TriggerServerEvent") to pass back any returned information if necessary. + + Almost any data types can be passed as expected, including [elements](/reference/Element "Element") and complex nested [tables](/reference/table "Table"). Non-element MTA data types like [xmlNodes](/reference/xmlnode "XML Node") or resource pointers will not be able to be passed as they do not necessarily have a valid representation on the client. + + Events are sent reliably, so clients will receive them, but there may be (but shouldn't be) a significant delay before they are received. You should take this into account when using them. + + Keep in mind the bandwidth issues when using events - don't pass a large list of arguments unless you really need to. It is marginally more efficient to pass one large event than two smaller ones. parameters: - - name: table/element sendTo - type: '[' - description: MISSING_PARAM_DESC + - name: sendTo + type: 'table/element' + description: The event will be sent to all [players](/reference/player "Player") that are children of the specified element. By default this is the [root](/reference/root "Root") element, and hence the event is sent to all players. If you specify a single player it will just be sent to that player. This argument can also be a table of player elements. default: getRootElement( + - name: name + type: string + description: The name of the event to trigger client side. You should register this event with [addEvent](/reference/addEvent "AddEvent") and add at least one event handler using [addEventHandler](/reference/addEventHandler "AddEventHandler"). + - name: sourceElement + type: element + description: The element that is the [source](/reference/Event_System "Event System") of the event. + - name: arguments + type: 'mixed' + description: A list of arguments to trigger with the event. You can pass any lua data type (except functions). You can also pass [elements](/reference/Element "Element"). + default: 'nil' + examples: - path: examples/triggerClientEvent-1.lua description: '' - side: client - path: examples/triggerClientEvent-2.lua description: '' - side: server - path: examples/triggerClientEvent-3.lua description: '' - side: client - - path: examples/triggerClientEvent-4.lua - description: '' - side: server - - path: examples/triggerClientEvent-5.lua - description: '' - side: client - - path: examples/triggerClientEvent-6.lua - description: '' - side: server returns: values: - type: bool @@ -42,15 +48,14 @@ shared: content: It is marginally more efficient to pass one large event than two smaller ones. - type: important - content: Non-element MTA data types like xmlNodes or resource pointers will not + content: Non-element MTA data types like [xmlNodes](/reference/xmlnode "XML Node") or resource pointers will not be able to be passed as they do not necessarily have a valid representation on the client. - type: important - content: To save client CPU, you should avoid setting theElement to the root element + content: To save client CPU, you should avoid setting theElement to the [root](/reference/root "Root") element where possible - it should be used as a last resort (rather questionable thing - to do, limited to very specific tasks, if any). Using target element ( player + to do, limited to very specific tasks, if any). Using target element ( [player](/reference/player "Player") who should receive event, if expected to be delivered to particular one) is - preferred and highly advisable. resourceRoot can also be used as alternative - choice, if addEventHandler is bound to root element, or to resourceRoot when + preferred and highly advisable. [resourceRoot](/reference/resourceRoot "ResourceRoot") can also be used as alternative + choice, if [addEventHandler](/reference/addEventHandler "addEventHandler") is bound to [root](/reference/root "Root") element, or to [resourceRoot](/reference/resourceRoot "ResourceRoot") when there is need to restrict event to single certain resource. - requires_review: true diff --git a/functions/Event/triggerEvent.yaml b/functions/Event/triggerEvent.yaml index cca3b0c9..88b184b7 100644 --- a/functions/Event/triggerEvent.yaml +++ b/functions/Event/triggerEvent.yaml @@ -1,45 +1,44 @@ # Scraped from: https://wiki.multitheftauto.com/wiki/TriggerEvent shared: name: triggerEvent - description: This function will trigger a named [event](/wiki/Event "Event") on - a specific [element](/wiki/Element "Element") in the [element tree](/wiki/Element_tree - "Element tree"). See [event system](/wiki/Event_system "Event system") for more + description: This function will trigger a named [event](/reference/Event_System "Event") on + a specific [element](/reference/Element "Element") in the [element tree](/reference/Element_tree + "Element tree"). See [event system](/reference/Event_System "Event System") for more information on how the event system works. + You can use the value returned from this function to determine if the event was cancelled by one of the event handlers. You should determine what your response (if any) to this should be based on the event's purpose. Generally, cancelling an event should prevent any further code being run that is dependent on whatever triggered that event. For example, if you have an onFlagCapture event, cancelling it would be expected to prevent the flag being able to be captured. Similarly, if you have onPlayerKill as an event you trigger, canceling it would either be expected to prevent the player being killed from dying or at least prevent the player from getting a score for it. parameters: - name: eventName type: string description: The name of the event you wish to trigger - name: baseElement type: element - description: The element you wish to trigger the event on. See event system for + description: The element you wish to trigger the event on. See [event system](/reference/Event_System "Event System") for information on how this works. - - name: argument1 - type: var + - name: arguments + type: mixed description: 'The first argument that the event handler expects should be added after the baseElement variable. NOTE: This function can have more than one of these arguments specified, once for each argument the event handler is expecting.' - - name: '...' - type: unknown - description: MISSING_PARAM_DESC + default: "nil" examples: - path: examples/triggerEvent-1.lua description: 'If you define a new custom event as follows:' - side: server - - path: examples/triggerEvent-2.lua - description: 'You can then trigger this event later on using:' - side: server returns: values: - type: bool name: value - description: 'If you define a new custom event as follows:' + description: | + Returns **nil** if the arguments are invalid or the event could not be found. + + Returns **true** if the event was triggered successfully, and was not cancelled using [cancelEvent](/reference/cancelEvent "CancelEvent"). + + Returns **false** if the event was triggered successfully, and was cancelled using [cancelEvent](/reference/cancelEvent "CancelEvent"). notes: - type: info - content: You should avoid triggering events on the root element unless you really + content: You should avoid triggering events on the [root](/reference/root "Root") element unless you really need to. Doing this triggers the event on every element in the element tree, which is potentially very CPU intensive. Use as specific (i.e. low down the tree) element as you can. - type: info - content: See Event Source Element for a descriptive visualization of the event + content: See [Event Source Element](/reference/Event_Source_Element "Event Source Element") for a descriptive visualization of the event system handling an event trigger. - requires_review: true diff --git a/functions/Event/triggerLatentClientEvent.yaml b/functions/Event/triggerLatentClientEvent.yaml index 869686e5..062a93bb 100644 --- a/functions/Event/triggerLatentClientEvent.yaml +++ b/functions/Event/triggerLatentClientEvent.yaml @@ -1,26 +1,40 @@ # Scraped from: https://wiki.multitheftauto.com/wiki/TriggerLatentClientEvent -shared: +server: name: triggerLatentClientEvent - description: 'This function is the same as [triggerClientEvent](/wiki/TriggerClientEvent + description: 'This function is the same as [triggerClientEvent](/reference/triggerClientEvent "TriggerClientEvent") except the transmission rate of the data contained in the arguments can be limited and other network traffic is not blocked while the data is being transferred.' parameters: - name: sendTo - type: '[table/element' + type: 'table/element' description: The event will be sent to all players that are children of the specified - element. By default this is the root element, and hence the event is sent to + element. By default this is the [root](/reference/root "Root") element, and hence the event is sent to all players. If you specify a single player it will just be sent to that player. This argument can also be a table of player elements. - default: getRootElement( + default: getRootElement() + - name: name + type: string + description: The name of the event to trigger client side. You should register this event with [addEvent](/reference/addEvent "AddEvent") and add at least one event handler using [addEventHandler](/reference/addEventHandler "AddEventHandler"). + - name: bandwidth + type: int + description: The bytes per second rate to send the data contained in the arguments. + default: 50000 + - name: persist + type: bool + description: A bool indicating whether the transmission should be allowed to continue even after the resource that triggered it has since stopped. + default: 'false' + - name: theElement + type: element + description: The element that is the [source](/reference/Event_System "Event System") of the event. This could be another player, or if this isn't relevant, use the [root](/reference/root "Root") element. + - name: arguments + type: mixed + description: A list of arguments to trigger with the event. You can pass any Lua data type (except functions). You can also pass [elements](/reference/Element "Element"). The total amount of data should not exceed 100MB. + default: 'nil' examples: - path: examples/triggerLatentClientEvent-1.lua description: '' - side: client - - path: examples/triggerLatentClientEvent-2.lua - description: '' - side: server returns: values: - type: bool @@ -29,15 +43,7 @@ shared: arguments were specified. notes: - type: info - content: You should avoid triggering events on the root element unless you really - need to. Doing this triggers the event on every element in the element tree + content: You should avoid triggering events on the [root](/reference/root "Root") element unless you really + need to. Doing this triggers the event on every element in the [element tree](/reference/Element_tree "Element Tree") , which is potentially very CPU intensive. Use as specific (i.e. low down the tree) element as you can. - meta: - - needs_checking: 'This function was partially migrated from the old wiki. Please - review manually: - - - Missing section: triggerClientEvent vs triggerLatentClientEvent test by DreTaX - - ' - requires_review: true diff --git a/functions/Event/triggerLatentServerEvent.yaml b/functions/Event/triggerLatentServerEvent.yaml index 3828bd36..21db1210 100644 --- a/functions/Event/triggerLatentServerEvent.yaml +++ b/functions/Event/triggerLatentServerEvent.yaml @@ -1,7 +1,7 @@ # Scraped from: https://wiki.multitheftauto.com/wiki/TriggerLatentServerEvent -shared: +client: name: triggerLatentServerEvent - description: This function is the same as [triggerServerEvent](/wiki/TriggerServerEvent + description: This function is the same as [triggerServerEvent](/reference/triggerServerEvent "TriggerServerEvent") except the transmission rate of the data contained in the arguments can be limited and other network traffic is not blocked while the data is being transferred. @@ -9,7 +9,7 @@ shared: - name: event type: string description: The name of the event to trigger server-side. You should register - this event with addEvent and add at least one event handler using addEventHandler + this event with [addEvent](/reference/addEvent "AddEvent") and add at least one event handler using [addEventHandler](/reference/addEventHandler "AddEventHandler") . - name: bandwidth type: int @@ -22,24 +22,20 @@ shared: default: 'false' - name: theElement type: element - description: The element that is the source of the event. This could be another - player, or if this isn't relevant, use the root element. - - name: arguments... - type: unknown + description: The element that is the [source](/reference/Event_System "Event System") of the event. This could be another + player, or if this isn't relevant, use the [root](/reference/root "Root") element. + - name: arguments + type: mixed description: A list of arguments to trigger with the event. You can pass any Lua - data type (except functions). You can also pass elements . The total amount + data type (except functions). You can also pass [elements](/reference/Element "Element") . The total amount of data should not exceed 100MB. + default: 'nil' examples: - path: examples/triggerLatentServerEvent-1.lua description: '' - side: client - - path: examples/triggerLatentServerEvent-2.lua - description: '' - side: server returns: values: - type: bool name: value description: Returns true if the event trigger has been sent, false if invalid arguments were specified. - requires_review: true diff --git a/functions/Event/triggerServerEvent.yaml b/functions/Event/triggerServerEvent.yaml index bc5507cd..7cf15463 100644 --- a/functions/Event/triggerServerEvent.yaml +++ b/functions/Event/triggerServerEvent.yaml @@ -1,60 +1,59 @@ # Scraped from: https://wiki.multitheftauto.com/wiki/TriggerServerEvent -shared: +client: name: triggerServerEvent - description: This function triggers an event previously registered on the server. + description: | + This function triggers an event previously registered on the server. This is the primary means of passing information between the client and the server. - Servers have a similar [triggerClientEvent](/wiki/TriggerClientEvent "TriggerClientEvent") + Servers have a similar [triggerClientEvent](/reference/triggerClientEvent "TriggerClientEvent") function that can do the reverse. You can treat this function as if it was an - asynchronous function call, using [triggerClientEvent](/wiki/TriggerClientEvent + asynchronous function call, using [triggerClientEvent](/reference/triggerClientEvent "TriggerClientEvent") to pass back any returned information if necessary. + + Almost any data types can be passed as expected, including [elements](/reference/Element "Element") and complex nested [tables](/reference/table "Tables"). Non-element MTA data types like xmlNodes or resource pointers will not be able to be passed as they do not necessarily have a valid representation on the client. **Elements of the Vector or Matrix classes cannot be passed!** + + Events are sent reliably, so the server will receive them, but there may be (but shouldn't be) a significant delay before they are received. You should take this into account when using them. + + Keep in mind the bandwidth issues when using events - don't pass a large list of arguments unless you really need to. It **is marginally more efficient to pass one large event than two smaller ones.** parameters: - name: event type: string description: The name of the event to trigger server-side. You should register - this event with addEvent and add at least one event handler using addEventHandler + this event with [addEvent](/reference/addEvent "AddEvent") and add at least one event handler using [addEventHandler](/reference/addEventHandler "AddEventHandler") . - name: theElement type: element - description: The element that is the source of the event. - - name: arguments... - type: unknown + description: The element that is the [source](/reference/Event_System "Event System") of the event. + - name: arguments + type: mixed description: A list of arguments to trigger with the event. You can pass any lua - data type (except functions). You can also pass elements . + data type (except functions). You can also pass [elements](/reference/Element "Element"). + default: 'nil' examples: - path: examples/triggerServerEvent-1.lua description: '' - side: client - path: examples/triggerServerEvent-2.lua description: '' - side: server - - path: examples/triggerServerEvent-3.lua - description: '' - side: client - - path: examples/triggerServerEvent-4.lua - description: '' - side: server returns: values: - type: bool name: value - description: Returns true if the event trigger has been sent, false if invalid + description: Returns **true** if the event trigger has been sent, **false** if invalid arguments were specified or a client side element was a parameter. notes: - type: info content: It is marginally more efficient to pass one large event than two smaller ones. - type: important - content: 'You should use the global variable client server-side instead of passing + content: 'You should use the global variable [client](/reference/Predefined_variables) server-side instead of passing the localPlayer by parameter or source. Otherwise event faking (passing another player instead of the localPlayer ) would be possible. For more information - see: Script security article.' + see: [Script security](/Script_security) article.' - type: important - content: To save server CPU, you should avoid setting theElement to the root element + content: To save server CPU, you should avoid setting **theElement** to the [root](/reference/root "Root") element where possible - it should be used as a last resort (rather questionable thing to do, limited to very specific tasks, if any). Using localPlayer is preferred - and highly advisable. resourceRoot can also be used as alternative choice, if - addEventHandler is bound to root element, or to resourceRoot when there is need + and highly advisable. [resourceRoot](/reference/resourceRoot "ResourceRoot") can also be used as alternative choice, if + [addEventHandler](/reference/addEventHandler "addEventHandler") is bound to [root](/reference/root "Root") element, or to [resourceRoot](/reference/resourceRoot "ResourceRoot") when there is need to restrict event to single certain resource (although cheater could still trigger - it from different resource, by using getResourceRootElement and passing respective + it from different resource, by using [getResourceRootElement](/reference/getResourceRootElement "getResourceRootElement") and passing respective resource root element) - requires_review: true diff --git a/functions/Event/wasEventCancelled.yaml b/functions/Event/wasEventCancelled.yaml index e40a1ff5..caf3dedc 100644 --- a/functions/Event/wasEventCancelled.yaml +++ b/functions/Event/wasEventCancelled.yaml @@ -1,8 +1,10 @@ # Scraped from: https://wiki.multitheftauto.com/wiki/WasEventCancelled shared: name: wasEventCancelled - description: This function checks if the last completed event was cancelled. This - is mainly useful for custom events created by scripts. + description: | + This function checks if the last completed event was cancelled. This is mainly useful for custom events created by scripts. + + Events can be cancelled using [cancelEvent](/reference/cancelEvent "CancelEvent"), this indicates that the resource which triggered the event should do whatever it can to reverse any changes made by whatever caused the event. See [triggerEvent](/reference/triggerEvent "TriggerEvent") for a more detailed explanation of this. parameters: [] examples: - path: examples/wasEventCancelled-1.lua @@ -16,4 +18,3 @@ shared: name: value description: Returns true if the event was cancelled, false if it wasn't or doesn't exist. - requires_review: true