update function pages and examples

ffsPLASMA · ffsPLASMA · commit 41c72989fdae · 2025-01-25T19:37:49.000+01:00
diff --git a/functions/Cursor/examples/getCursorAlpha.lua b/functions/Cursor/examples/getCursorAlpha.lua
@@ -1,6 +1,6 @@
--- Simple command to test the getCursorAlpha function
-addCommandHandler( "cursorAlpha", 
+addCommandHandler( "cursoralpha", 
     function ()
+        -- check if cursor is showing
         if ( isCursorShowing ( ) ) then
             outputChatBox( "The cursor alpha: "..getCursorAlpha( ) )
         else
diff --git a/functions/Cursor/examples/getCursorPosition-1.lua b/functions/Cursor/examples/getCursorPosition-1.lua
@@ -1,9 +1,12 @@
 function cursorInfo()
-    if isCursorShowing() then -- if the cursor is showing
+    -- is the cursor showing?
+    if isCursorShowing() then
+        -- get the cursor postion
         local screenx, screeny, worldx, worldy, worldz = getCursorPosition()
 
-        outputChatBox( string.format( "Cursor screen position (relative): X=%.4f Y=%.4f", screenx, screeny ) ) -- make the accuracy of floats 4 decimals
-        outputChatBox( string.format( "Cursor world position: X=%.4f Y=%.4f Z=%.4f", worldx, worldy, worldz ) ) -- make the accuracy of floats 4 decimals accurate
+        -- make the accuracy of floats 4 decimals and print to chatbox
+        outputChatBox( string.format( "Cursor screen position (relative): X=%.4f Y=%.4f", screenx, screeny ) )
+        outputChatBox( string.format( "Cursor world position: X=%.4f Y=%.4f Z=%.4f", worldx, worldy, worldz ) )
     else
         outputChatBox( "Your cursor is not showing." )
     end
diff --git a/functions/Cursor/examples/getCursorPosition-2.lua b/functions/Cursor/examples/getCursorPosition-2.lua
@@ -1,15 +1,22 @@
 addEventHandler( "onClientRender", root,
     function()
+        -- is cursor showing?
         if isCursorShowing() then
+            -- get cursor position
             local screenx, screeny, worldx, worldy, worldz = getCursorPosition()
+
+            -- get our camera matrix/position
             local px, py, pz = getCameraMatrix()
+
+            -- calculate the exact distance between cursor and camera
             local hit, x, y, z, elementHit = processLineOfSight ( px, py, pz, worldx, worldy, worldz )
 
-            if hit then
-                dxDrawText( "Cursor at " .. x .. " " .. y .. " " ..  z, 200, 200 )
-                if elementHit then
-                    dxDrawText( "Hit element " .. getElementType(elementHit), 200, 220 )
-                end
+            -- draw the distance on screen
+            dxDrawText( "Cursor at X:" .. x .. " Y:" .. y .. " Z:" ..  z, 200, 200 )
+
+            -- if we got a collision detected and a valid element, draw it as well
+            if hit and elementHit then
+                dxDrawText( "Hit element " .. getElementType(elementHit), 200, 220 )
             end
         end
     end
diff --git a/functions/Cursor/examples/setCursorAlpha.lua b/functions/Cursor/examples/setCursorAlpha.lua
@@ -1,8 +1,8 @@
--- Simple command to test the setCursorAlpha function
-addCommandHandler( "cursorAlpha", 
+addCommandHandler( "cursoralpha", 
     function ()
         -- Show the cursor if it is not showing or hide the cursor if it is
         showCursor( not isCursorShowing ( ) )
+        
         -- Set the alpha to 100
         setCursorAlpha(100)
     end
diff --git a/functions/Cursor/examples/setCursorPosition.lua b/functions/Cursor/examples/setCursorPosition.lua
@@ -1,8 +1,11 @@
 function centerCursorFunction()
-    local showing = isCursorShowing ()
-    if showing then -- if the cursor is showing
-        local screenX, screenY = guiGetScreenSize () --get the screen size in pixels
-        setCursorPosition (screenX/2, screenY/2) --set the cursor position to the center of the screen
+    -- is cursor showing?
+    if showisCursorShowing ()ing then
+        --get the screen size in pixels
+        local screenX, screenY = guiGetScreenSize ()
+
+        --set the cursor position to the center of the screen
+        setCursorPosition (screenX/2, screenY/2)
     else
         outputChatBox( "Your cursor is not showing." )
     end
diff --git a/functions/Cursor/examples/showCursor-2.lua b/functions/Cursor/examples/showCursor-2.lua
@@ -1,2 +1,2 @@
-showCursor ( true ) -- Shows cursor
-showCursor ( false ) -- Doesnt Show Cursor
+showCursor ( true ) -- shows cursor
+showCursor ( false ) -- hides cursor
diff --git a/functions/Cursor/getCursorAlpha.yaml b/functions/Cursor/getCursorAlpha.yaml
@@ -5,16 +5,18 @@ client:
     This function is used to get the client's cursor alpha (transparency).
   preview_images:
   - path: '/assets/cursor-alpha.jpg'
-    description: 'Visual representation of the cursor alpha'
+    description: 'Visual representation of the cursor alpha:'
   returns:
     description: |
-      Returns a int between 0 and 255, where 255 is fully opaque and 0 is fully transparent. 
+      Returns a number between 0 and 255, where 255 is fully opaque and 0 is fully transparent. 
     values:
       - type: 'int'
         name: 'alpha'
   version:
     added: '1.3.2'
   examples:
     - path: 'examples/getCursorAlpha.lua'
+      description: |
+        This example prints the cursor alpha to chatbox using */cursoralpha* command:
   see_also:
     - 'category:Client element functions'
diff --git a/functions/Cursor/getCursorPosition.yaml b/functions/Cursor/getCursorPosition.yaml
@@ -4,13 +4,13 @@ client:
   description: |
     This function gets the current position of the mouse cursor.
     Note that for performance reasons, the world position returned is always 300 units away.
-    If you want the exact world point (similar to [[onClientClick]]), use [[processLineOfSight]] between the camera position and the worldX/Y/Z result of this function.
+    If you want the exact world point (similar to [onClientClick](/onClientClick)), use [processLineOfSight](/processLineOfSight) between the camera position and the world x/y/z result of this function.
     (See example below) 
   returns:
     description: |
       Returns 5 values: *cursorX*, *cursorY*, *worldX*, *worldY*, *worldZ*.
       The first two values are the 2D **relative** screen coordinates of the cursor.
-      The 3 values that follow are the 3D world map coordinates that the cursor points at.
+      The last 3 values are the 3D world map coordinates that the cursor points at.
       If the cursor isn't showing, returns *false* as the first value.
     values:
       - type: 'float'
@@ -29,7 +29,7 @@ client:
   examples:
     - path: 'examples/getCursorPosition-1.lua'
       description: |
-        This example prints your cursors current world coordinates and relative screen coordinates to chatbox after typing cursorpos.
+        This example prints your cursors current world coordinates and relative screen coordinates to chatbox after using */cursorpos* command.
     - path: 'examples/getCursorPosition-2.lua'
       description: |
-        This (untested) example uses processLineOfSight to calculate the exact world location: Warning, using the script down there will cause high CPU usage.
+        This (untested) example uses [processLineOfSight](/processLineOfSight) to calculate the exact world location: Warning, this script causes high CPU usage!
diff --git a/functions/Cursor/isCursorShowing.yaml b/functions/Cursor/isCursorShowing.yaml
@@ -1,13 +1,13 @@
 shared: &shared
   name: 'isCursorShowing'
   description: |
-    This function determines the state of a player's cursor.
+    This function determines the state of a [player](/player)'s cursor.
   notes:
-    - This function only handles the cursor state set by the [[showCursor]] function, ignoring it if the console, chatbox, or menu is open.
-    - If you use this function on the server-side, keep in mind that it only detects the [[showCursor]] function executed on the server-side and does not detect the function executed on the client-side.
+    - This function only handles the cursor state set by the [showCursor](/showCursor) function, ignoring it if the console, chatbox, or menu is opened.
+    - If you use this function on the server-side, keep in mind that it only detects the [showCursor](/showCursor) function executed on the server-side and not changes done by client-side.
   returns:
     description: |
-      Returns *true* if the player's cursor is visible, and *false* if it is not.
+      Returns *true* if the [player](/player)'s cursor is visible, and *false* if it is not.
     values:
       - type: 'bool'
         name: 'result'
@@ -17,28 +17,28 @@ server:
   parameters:
     - name: 'playerElement'
       type: 'player'
-      description: 'The [[player]] from whom we want to retrieve the cursor state.'
+      description: 'The [player](/player) from whom we want to retrieve the cursor state.'
   examples:
     - path: 'examples/isCursorShowing-1.lua'
       description: |
-        This example creates a function to set the state of the player's cursor using the [[showCursor]] function.
+        This example creates a function to set the state of the [player](/player)'s cursor using the [showCursor](/showCursor) function.
     - path: 'examples/isCursorShowing-2.lua'
       description: |
-        This example creates a function that gets the state of the player's cursor and outputs it to the chatbox using the [[outputChatBox]] function.
+        This example creates a function that gets the state of the [player](/player)'s cursor and outputs it to the chatbox using the [outputChatBox](/outputChatBox) function.
 
 client:
   <<: *shared
   examples:
     - path: 'examples/isCursorShowing-3.lua'
       description: |
-        This example creates a function to set the state of the player's cursor using the [[showCursor]] function. 
+        This example creates a function to set the state of the [player](/player)'s cursor using the [showCursor](/showCursor) function. 
     - path: 'examples/isCursorShowing-4.lua'
       description: |
         If you are already advanced in scripting, using this code is recommended, as it is much more compact:
       append: true
     - path: 'examples/isCursorShowing-5.lua'
       description: |
-        This example creates a function that allows the player to change the state of the cursor using the [[showCursor]] and [[bindKey]] functions. 
+        This example creates a function that allows the [player](/player) to change the state of the cursor using the [showCursor](/showCursor) and [bindKey](/bindKey) functions. 
     - path: 'examples/isCursorShowing-6.lua'
       description: |
         If you are already advanced in scripting, using this code is recommended, as it is much more compact:
diff --git a/functions/Cursor/setCursorAlpha.yaml b/functions/Cursor/setCursorAlpha.yaml
@@ -2,14 +2,14 @@ client:
   name: 'setCursorAlpha'
   pair: 'getCursorAlpha'
   description: |
-    This function is used to change alpha (transparency) from the client's cursor.
+    This function is used to change alpha (transparency) of the client's cursor.
   preview_images:
     - path: '/assets/cursor-alpha.jpg'
-      description: 'Visual representation of the cursor alpha'
+      description: 'Visual representation of the cursor alpha:'
   parameters:
     - name: 'alpha'
       type: 'int'
-      description: 'The alpha value to set. Value can be 0-255, where 255 is fully opaque and 0 is fully transparent.'
+      description: 'The alpha value to set. Value can be in between 0 and 255, where 255 is fully opaque and 0 is fully transparent.'
   returns:
     description: |
       Returns *true* if the new alpha value was set, or *false* otherwise.
@@ -20,5 +20,7 @@ client:
     added: '1.3.2'
   examples:
     - path: 'examples/setCursorAlpha.lua'
+      description: |
+        This example sets the cursor alpha to 100 using */cursoralpha* command:
   see_also:
     - 'category:Client GUI functions'
diff --git a/functions/Cursor/setCursorPosition.yaml b/functions/Cursor/setCursorPosition.yaml
@@ -5,10 +5,10 @@ client:
   parameters:
     - name: 'cursorX'
       type: 'int'
-      description: 'Position over the X axis'
+      description: 'Position for the X axis'
     - name: 'cursorY'
       type: 'int'
-      description: 'Position over the Y axis'
+      description: 'Position for the Y axis'
   returns:
     description: 'Returns *true* if the position has been successfully set, *false* otherwise.'
     values:
@@ -17,6 +17,6 @@ client:
   examples:
     - path: 'examples/setCursorPosition.lua'
       description: |
-        This example sets your cursor position to the center of your screen after using the command *cursorpos*.
+        This example sets your cursor position to the center of your screen after using the */cursorpos* command.
   see_also:
     - 'category:Client input functions'
diff --git a/functions/Cursor/showCursor.yaml b/functions/Cursor/showCursor.yaml
@@ -1,14 +1,14 @@
 shared: &shared
   name: 'showCursor'
   description: |
-    This function is used to show or hide a [[player]]'s cursor. 
+    This function is used to show or hide a [player](/player)'s cursor. 
   notes:
     - Regardless of the cursor state you set using this function, the cursor will always be visible while the menu, the chatbox input line or the console are active, or if another resource has called this function.
-    - Be aware of that if showCursor enbaled by a resource you can't disabled it from a different ressource showCursor(false) will not works, in order to make it works, disable it from the original resource that enabled it or use export.
+    - Be aware of that if showCursor is enabled by a resource, you can't disabled it from a different ressource! showCursor(false) will not work, in order to make it work, disable it from the original resource that enabled it or use an export.
   parameters:
     - name: 'thePlayer'
       type: 'player'
-      description: 'The [[player]] you want to show or hide the cursor of.'
+      description: 'The [player](/player) you want to show or hide the cursor of.'
     - name: 'show'
       type: 'bool'
       description: 'A boolean value determining whether to show (*true*) or hide (*false*) the cursor.'
@@ -38,4 +38,4 @@ client:
   examples:
     - path: 'examples/showCursor-2.lua'
       description: |
-        This example shows the cursor all the time 
+        This example shows/hides the cursor:
diff --git a/functions/Element/examples/getElementPosition-1.lua b/functions/Element/examples/getElementPosition-1.lua
@@ -0,0 +1,8 @@
+function whatsMyPosition()
+    -- get the position of local player
+    local fX, fY, fZ = getElementPosition(localPlayer);
+
+    -- output it to chat
+    outputChatBox("My current position is X: "..fX.." Y: "..fY.." Z: "..fZ);
+end
+addCommandHandler("pos", whatsMyPosition);
diff --git a/functions/Element/examples/getElementPosition-2.lua b/functions/Element/examples/getElementPosition-2.lua
@@ -0,0 +1,8 @@
+function teleportMePlease(uPlayer)
+    -- get the position from the player executing the command
+    local fX, fY, fZ = getElementPosition(uPlayer);
+
+    -- set player position 50 units higher
+    setElementPosition(uPlayer, fX, fY, fZ + 50);
+end
+addCommandHandler("tpme", teleportMePlease);
diff --git a/functions/Element/examples/getElementPosition.lua b/functions/Element/examples/getElementPosition.lua
diff --git a/functions/Element/examples/setElementPosition-1.lua b/functions/Element/examples/setElementPosition-1.lua
@@ -0,0 +1,5 @@
+function teleportPlayerToMapCenter()
+    -- teleport player to 0,0,0 coordinates (map origin/center)
+    setElementPosition(localPlayer, 0, 0, 0 + 3);	-- add +3 to z coordinate to not fall below map!
+end
+addCommandHandler("zero", teleportPlayerToMapCenter);
diff --git a/functions/Element/examples/setElementPosition-2.lua b/functions/Element/examples/setElementPosition-2.lua
@@ -0,0 +1,11 @@
+function teleportToRandomPlayer(uPlayer)
+    -- get a random player (does not exclude the player executing this command!)
+    local uRandomPlayer = getRandomPlayer();
+
+    -- get the position of the random player
+    local fX, fY, fZ = getElementPosition(uRandomPlayer);
+
+    -- teleport the player to random one with slight offset to not get stuck
+    setElementPosition(uPlayer, fX + 2, fY + 2, fZ);
+end
+addCommandHandler("tprandom", teleportToRandomPlayer);
diff --git a/functions/Element/examples/setElementPosition.lua b/functions/Element/examples/setElementPosition.lua
diff --git a/functions/Element/getElementHealth.yaml b/functions/Element/getElementHealth.yaml
@@ -6,11 +6,11 @@ shared: &shared
     variable: health
   pair: 'setElementHealth'
   description: |
-    This function returns the current health for the specified element. This can be a [[player]], [[ped]], [[vehicle]], or [[object]]. 
+    This function returns the current health for the specified element. This can be a [player](/player), [ped](/ped), [vehicle](/vehicle), or [object](/object). 
   parameters:
     - name: 'theElement'
       type: 'element'
-      description: "The [[player]] or [[vehicle]] whose health you want to check."
+      description: "The [player](/player), [ped](/ped), [vehicle](/vehicle), or [object](/object) whose health you want to get."
   returns:
     description: |
       Returns a *float* indicating the element's health, *false* otherwise.
@@ -33,7 +33,7 @@ client:
   examples:
     - path: 'examples/getElementHealth-1.lua'
       description: |
-        This example outputs the player and vehicle health (if player is in a vehicle) to chatbox using /health command:
+        This example outputs the player and vehicle health (if player is in a vehicle) to chatbox using */health* command:
     - path: 'examples/getElementHealth-2.lua'
       description: |
-        This example heals the player to 100 HP using /healme command if he's at 50 HP or lower:
+        This example heals the player to 100 HP using */healme* command if he's at 50 HP or lower:
diff --git a/functions/Element/getElementPosition.yaml b/functions/Element/getElementPosition.yaml
diff --git a/functions/Element/setElementHealth.yaml b/functions/Element/setElementHealth.yaml
diff --git a/functions/Element/setElementPosition.yaml b/functions/Element/setElementPosition.yaml
