diff --git a/functions/Event/addEvent.yaml b/functions/Event/addEvent.yaml index 6babf7f6..f9ce3f70 100644 --- a/functions/Event/addEvent.yaml +++ b/functions/Event/addEvent.yaml @@ -1,8 +1,7 @@ -# 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 +10,13 @@ shared: - name: allowRemoteTrigger type: bool description: A boolean specifying whether this event can be called remotely using - triggerClientEvent / triggerServerEvent or not. + [[triggerClientEvent]] / [[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 + description: This example will define a new event. 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 + name: result + description: Returns **true** if the event was added successfully, otherwise **false** if the event already exists **built-in game events** or if it fails for any other reason. diff --git a/functions/Event/addEventHandler.yaml b/functions/Event/addEventHandler.yaml index c3a77f5a..365ae9fe 100644 --- a/functions/Event/addEventHandler.yaml +++ b/functions/Event/addEventHandler.yaml @@ -1,22 +1,21 @@ -# 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]] 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,45 +24,35 @@ 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:' + templateList: 'event-priority' default: '"normal"' examples: - path: examples/addEventHandler-1.lua description: This serverside example sends a message to everyone in the server when a player spawns. - side: server returns: values: - type: bool - name: value - description: Returns true if the event handler was attached successfully. Returns - false if the specified event could not be found or any parameters were invalid. + name: result + description: Returns **true** if the event handler was attached successfully. otherwise **false** if the specified event could not be found or any parameters were invalid. notes: - type: info - content: You shouldn't re-use the same name for your handler function as the event + content: | + - You shouldn't re-use the same name for your handler function as the event name - if multiple handler functions are used, as this can lead to confusion. 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 + - 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 . - - 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 - an element. - - type: info - content: Due to the additional set of global variables, the event-trigger specific + - Due to the additional set of global variables, the event-trigger specific variables it is NOT a good idea to use the same function locally as well as directly as an event handler . Event handlers often make use of the source element variable which would often find no use in generic functions. Inside of server-side @@ -73,4 +62,10 @@ 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 + - type: important + content: | + - See [Script security](/Script_security "Script security") for how-to prevent cheaters from abusing [event system](/reference/Event_System "Event system"). + - 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 + an element. \ No newline at end of file diff --git a/functions/Event/cancelEvent.yaml b/functions/Event/cancelEvent.yaml index 6edaa521..02dbead5 100644 --- a/functions/Event/cancelEvent.yaml +++ b/functions/Event/cancelEvent.yaml @@ -1,44 +1,35 @@ -# 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") + description: This function is used to stop the automatic internal handling of events 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 + name: result + description: Always returns **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]] event. + server: - 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") - event. 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 + name: result + description: Returns **true**, otherwise **false** if parameters are invalid. diff --git a/functions/Event/cancelLatentEvent.yaml b/functions/Event/cancelLatentEvent.yaml index bf10f1d2..10e47742 100644 --- a/functions/Event/cancelLatentEvent.yaml +++ b/functions/Event/cancelLatentEvent.yaml @@ -1,46 +1,37 @@ -# 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]]. examples: - path: examples/cancelLatentEvent-1.lua description: '' - side: client - - path: examples/cancelLatentEvent-4.lua - description: '' - side: client returns: values: - type: bool - name: value - description: Returns a true if the latent event was successfully cancelled, or - false if it was not - requires_review: true + name: result + description: Returns a **true** if the latent event was successfully cancelled, otherwise **false**. + server: - name: cancelLatentEvent - description: Stops a latent event from completing parameters: - name: thePlayer type: player 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]]. examples: - - path: examples/cancelLatentEvent-2.lua - description: '' - side: server - path: examples/cancelLatentEvent-3.lua - description: '' - side: server + description: "Cancel all my triggerLatentClientEvent's" returns: values: - type: bool - name: value - description: Returns a true if the latent event was successfully cancelled, or - false if it was not - requires_review: true + name: result + description: Returns a **true** if the latent event was successfully cancelled, otherwise **false**. + +client: + examples: + - path: examples/cancelLatentEvent-2.lua + description: "Cancel all my triggerLatentServerEvent's" diff --git a/functions/Event/examples/addEvent-1.lua b/functions/Event/examples/addEvent-1.lua index 623ea382..1e3f136e 100644 --- a/functions/Event/examples/addEvent-1.lua +++ b/functions/Event/examples/addEvent-1.lua @@ -1,10 +1,6 @@ --- Add a new event called onSpecialEvent addEvent ( "onSpecialEvent", true ) --- Define our handler function, that takes a "text" parameter and outputs it to the chatbox function specialEventHandler ( text ) outputChatBox ( text ) end - --- Add it as a handler for our event addEventHandler ( "onSpecialEvent", root, specialEventHandler ) \ 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/addEventHandler-1.lua b/functions/Event/examples/addEventHandler-1.lua index f7e2b6ac..acc42bda 100644 --- a/functions/Event/examples/addEventHandler-1.lua +++ b/functions/Event/examples/addEventHandler-1.lua @@ -5,5 +5,4 @@ function onPlayerSpawnHandler ( ) -- output in the chat box that they've spawned outputChatBox ( playerName .. " has spawned!" ) end - addEventHandler( "onPlayerSpawn", root, onPlayerSpawnHandler ) -- root is a predefined global variable for getRootElement() \ 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/cancelLatentEvent-1.lua b/functions/Event/examples/cancelLatentEvent-1.lua index 75447471..0b2b23ed 100644 --- a/functions/Event/examples/cancelLatentEvent-1.lua +++ b/functions/Event/examples/cancelLatentEvent-1.lua @@ -1,14 +1,20 @@ --- Cancel triggerLatentServerEvent directly after execution. +-- ***************************************************************************** +-- CLIENT CODE addCommandHandler("cancelLatentEvent", function () triggerLatentServerEvent("exampleEvent",3000,false,localPlayer) - - -- Get all your active handles, when you executed the command: /cancelLatentEvent local handles = getLatentEventHandles() -- Returns a table. - local handle = handles[#handles] -- Get the latest handle. if cancelLatentEvent(handle) then -- Cancel it! outputChatBox("Successfully cancelled!",0,200,0) end +end) + +-- ***************************************************************************** +-- SERVER CODE +addEvent("exampleEvent",true) +addEventHandler("exampleEvent",root, +function () + outputChatBox("Warning! The triggerLatentServerEvent wasn't cancelled!",client,255,0,0) -- warn the user. end) \ No newline at end of file diff --git a/functions/Event/examples/cancelLatentEvent-2.lua b/functions/Event/examples/cancelLatentEvent-2.lua index ea1df48d..6241225a 100644 --- a/functions/Event/examples/cancelLatentEvent-2.lua +++ b/functions/Event/examples/cancelLatentEvent-2.lua @@ -1,5 +1,9 @@ -addEvent("exampleEvent",true) -addEventHandler("exampleEvent",root, -function () - outputChatBox("Warning! The triggerLatentServerEvent wasn't cancelled!",client,255,0,0) -- warn the user. +addCommandHandler("cancelLatentEvents", +function (player) + local handles = getLatentEventHandles (player) -- Returns a table. + + for index=1,#handles do -- Loop through the table. + local handle = handles[index] + cancelLatentEvent(player,handle) -- Cancel it! + end end) \ No newline at end of file diff --git a/functions/Event/examples/cancelLatentEvent-3.lua b/functions/Event/examples/cancelLatentEvent-3.lua index ad4d08a3..340f1182 100644 --- a/functions/Event/examples/cancelLatentEvent-3.lua +++ b/functions/Event/examples/cancelLatentEvent-3.lua @@ -1,12 +1,9 @@ --- Cancel all my triggerLatentClientEvent's. addCommandHandler("cancelLatentEvents", -function (player) - - -- Get all active handles from the player that executed the command: /cancelLatentEvents - local handles = getLatentEventHandles (player) -- Returns a table. +function () + local handles = getLatentEventHandles () -- Returns a table. for index=1,#handles do -- Loop through the table. - local handle = handles[index] - cancelLatentEvent(player,handle) -- Cancel it! + local handle = handles[index] + cancelLatentEvent(handle) -- Cancel it! end end) \ No newline at end of file diff --git a/functions/Event/examples/cancelLatentEvent-4.lua b/functions/Event/examples/cancelLatentEvent-4.lua deleted file mode 100644 index 3c52566b..00000000 --- a/functions/Event/examples/cancelLatentEvent-4.lua +++ /dev/null @@ -1,12 +0,0 @@ --- Cancel all my triggerLatentServerEvent's. -addCommandHandler("cancelLatentEvents", -function () - - -- Get all your active handles, when you executed the command: /cancelLatentEvents - local handles = getLatentEventHandles () -- Returns a table. - - for index=1,#handles do -- Loop through the table. - local handle = handles[index] - cancelLatentEvent(handle) -- Cancel it! - end -end) \ No newline at end of file diff --git a/functions/Event/examples/getCancelReason-1.lua b/functions/Event/examples/getCancelReason-1.lua index 9d5ed947..f3d27252 100644 --- a/functions/Event/examples/getCancelReason-1.lua +++ b/functions/Event/examples/getCancelReason-1.lua @@ -1,4 +1,3 @@ --- call 'stopVehicleEntry' whenever hunterPlayer is about to enter a vehicle: function stopVehicleEntry ( theplayer, seat, jacked ) cancelEvent (true, "You can't enter a vehicle during war.") -- stop the event from occuring and tell the player the reason. outputConsole("We told "..getPlayerName(theplayer).." : "..getCancelReason()) --Now tell everyone what the player tried to do diff --git a/functions/Event/examples/getLatentEventHandles-1.lua b/functions/Event/examples/getLatentEventHandles-1.lua index 01c2bbb5..72fc2164 100644 --- a/functions/Event/examples/getLatentEventHandles-1.lua +++ b/functions/Event/examples/getLatentEventHandles-1.lua @@ -1,7 +1,6 @@ --- CLIENT SIDE: - +-- ***************************************************************************** +-- CLIENT CODE local lastTriggerd = false - addCommandHandler("trigger",function() local triggers = getLatentEventHandles() -- get all latent events if triggers[lastTriggerd] then -- you can use (getLatentEventStatus) too! @@ -12,8 +11,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..bee28f8f 100644 --- a/functions/Event/getCancelReason.yaml +++ b/functions/Event/getCancelReason.yaml @@ -1,16 +1,12 @@ -# Scraped from: https://wiki.multitheftauto.com/wiki/GetCancelReason -shared: +server: name: getCancelReason description: Gets the reason for cancelling an event. parameters: [] examples: - path: examples/getCancelReason-1.lua - description: This example cancels when a hunterPlayer tries to enter a vehicle - and outputs to the world what the player tried to do. - side: server + description: This example cancels when a hunterPlayer tries to enter a vehicle. returns: values: - type: string - name: value - description: Returns the reason that was given with cancelEvent - requires_review: true + name: result + description: Returns the reason that was given with [[cancelEvent]] diff --git a/functions/Event/getEventHandlers.yaml b/functions/Event/getEventHandlers.yaml index d6709c7f..dc79fc78 100644 --- a/functions/Event/getEventHandlers.yaml +++ b/functions/Event/getEventHandlers.yaml @@ -1,4 +1,3 @@ -# Scraped from: https://wiki.multitheftauto.com/wiki/GetEventHandlers shared: name: getEventHandlers description: This function gets the attached functions from the event and attached @@ -6,20 +5,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]] attached to. returns: values: - type: table - name: value - description: Returns table with attached functions, empty table otherwise. - requires_review: true + name: result + description: Returns [[table]] with attached functions, otherwise empty [[table]]. + +server: + examples: + - path: examples/getEventHandlers-1.lua + description: '' +client: + examples: + - path: examples/getEventHandlers-2.lua + description: This example removes all [[onClientMarkerHit]] event. diff --git a/functions/Event/getLatentEventHandles.yaml b/functions/Event/getLatentEventHandles.yaml index ff72ff18..7d40327b 100644 --- a/functions/Event/getLatentEventHandles.yaml +++ b/functions/Event/getLatentEventHandles.yaml @@ -1,17 +1,18 @@ -# 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. 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 + name: result + description: Returns a [[table]] of handles, otherwise **false** if invalid arguments were passed. + server: name: getLatentEventHandles description: Gets the currently queued latent events. The last one in the table @@ -21,14 +22,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 + name: result + description: Returns a [[table]] of handles, otherwise **false** if invalid arguments were passed. diff --git a/functions/Event/getLatentEventStatus.yaml b/functions/Event/getLatentEventStatus.yaml index d8e9c5bf..91314e8a 100644 --- a/functions/Event/getLatentEventStatus.yaml +++ b/functions/Event/getLatentEventStatus.yaml @@ -1,23 +1,17 @@ -# 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]]. returns: values: - type: table - name: value - description: 'Returns a table with the following info or false if invalid arguments + name: result + description: 'Returns a [[table]] with the following info, otherwise **false** if invalid arguments were passed:' - requires_review: true + server: name: getLatentEventStatus description: Gets the status of one queued latent event. @@ -27,12 +21,16 @@ 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]]. examples: [] returns: values: - type: table - name: value - description: 'Returns a table with the following info or false if invalid arguments - were passed:' - requires_review: true + name: result + description: 'Returns a [[table]] with the following info, otherwise **false** if invalid arguments were passed:' + +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..d9ddc131 100644 --- a/functions/Event/removeEventHandler.yaml +++ b/functions/Event/removeEventHandler.yaml @@ -1,30 +1,29 @@ -# 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]] 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 - name: value - description: Returns true if the event handler was removed successfully. Returns - false if the specified event handler could not be found or invalid parameters + name: result + description: Returns **true** if the event handler was removed successfully, otherwise + **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..2642146d 100644 --- a/functions/Event/triggerClientEvent.yaml +++ b/functions/Event/triggerClientEvent.yaml @@ -1,56 +1,60 @@ -# 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]] and add at least one event handler using [[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 - name: value - description: Returns true if the event trigger has been sent, false if invalid + name: result + description: Returns **true** if the event trigger has been sent, otherwise **false** if invalid arguments were specified. notes: - type: info 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 + - 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 - there is need to restrict event to single certain resource. - requires_review: true + 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. \ No newline at end of file diff --git a/functions/Event/triggerEvent.yaml b/functions/Event/triggerEvent.yaml index cca3b0c9..da0672da 100644 --- a/functions/Event/triggerEvent.yaml +++ b/functions/Event/triggerEvent.yaml @@ -1,45 +1,39 @@ -# 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]] 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:' + name: result + description: Returns **true** if the event was triggered successfully, otherwise **false** if the event was cancelled using [[cancelEvent]], or **nil** if the arguments are invalid or the event could not be found. + 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 + - 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..17b9e6e0 100644 --- a/functions/Event/triggerLatentClientEvent.yaml +++ b/functions/Event/triggerLatentClientEvent.yaml @@ -1,43 +1,46 @@ -# Scraped from: https://wiki.multitheftauto.com/wiki/TriggerLatentClientEvent -shared: +server: name: triggerLatentClientEvent - description: 'This function is the same as [triggerClientEvent](/wiki/TriggerClientEvent - "TriggerClientEvent") except the transmission rate of the data contained in the + description: 'This function is the same as [[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]] and add at least one event handler using [[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 - name: value - description: Returns true if the event trigger has been sent, false if invalid - arguments were specified. + name: result + description: Returns **true** if the event trigger has been sent, otherwise **false** if invalid 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..21af0f7b 100644 --- a/functions/Event/triggerLatentServerEvent.yaml +++ b/functions/Event/triggerLatentServerEvent.yaml @@ -1,15 +1,13 @@ -# Scraped from: https://wiki.multitheftauto.com/wiki/TriggerLatentServerEvent -shared: +client: name: triggerLatentServerEvent - description: This function is the same as [triggerServerEvent](/wiki/TriggerServerEvent - "TriggerServerEvent") except the transmission rate of the data contained in the + description: This function is the same as [[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. 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]] and add at least one event handler using [[addEventHandler]] . - name: bandwidth type: int @@ -22,24 +20,19 @@ 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 + name: result + description: Returns **true** if the event trigger has been sent, otherwise **false** if invalid arguments were specified. diff --git a/functions/Event/triggerServerEvent.yaml b/functions/Event/triggerServerEvent.yaml index bc5507cd..83af9bc9 100644 --- a/functions/Event/triggerServerEvent.yaml +++ b/functions/Event/triggerServerEvent.yaml @@ -1,60 +1,56 @@ -# 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") - function that can do the reverse. You can treat this function as if it was an - asynchronous function call, using [triggerClientEvent](/wiki/TriggerClientEvent - "TriggerClientEvent") to pass back any returned information if necessary. + Servers have a similar [[triggerClientEvent]] function that can do the reverse. You can treat this function as if it was an + asynchronous function call, using [[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]] and add at least one event handler using [[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 + name: result + 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.' - - type: important - content: To save server CPU, you should avoid setting theElement to the root element + see: [Script security](/Script_security) article. + - 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..010c770d 100644 --- a/functions/Event/wasEventCancelled.yaml +++ b/functions/Event/wasEventCancelled.yaml @@ -1,19 +1,18 @@ -# 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]], 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]] for a more detailed explanation of this. parameters: [] examples: - path: examples/wasEventCancelled-1.lua - description: This example implements a custom eventonFlagPickupthat would be triggered - if anonMarkerHitevent was triggered on a marker whose parent was aflagelement. + description: This example implements a custom event onFlagPickup that would be triggered + if an onMarkerHit event was triggered on a marker whose parent was a flag element. If the event isn't canceled then an element data value is set on the player. side: server returns: values: - type: bool - name: value - description: Returns true if the event was cancelled, false if it wasn't or doesn't - exist. - requires_review: true + name: result + description: Returns **true** if the event was cancelled, otherwise **false** diff --git a/web/src/components/TemplateList.astro b/web/src/components/TemplateList.astro index 22eb6c22..7698f7a5 100644 --- a/web/src/components/TemplateList.astro +++ b/web/src/components/TemplateList.astro @@ -353,6 +353,12 @@ const lists: Record = { {id: 'reading', label: 'Model is being read.'}, {id: 'finishing', label: 'Second reading state for big models.'}, ], + + 'event-priority': [ + {id: "high"}, + {id: "normal"}, + {id: "low"} + ], }; const icons: Record = {