Add client Cursor functions

This is a first draft for functions and the schema.

Author: botder

.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+    "recommendations": [
+        "redhat.vscode-yaml"
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "yaml.schemas": {
+        "schemas/function.yaml": "/functions/**/*"
+    }
+}

articles/.gitkeep

@@ -0,0 +1,10 @@
+-- Simple command to test the getCursorAlpha function
+addCommandHandler( "cursorAlpha", 
+    function ()
+        if ( isCursorShowing ( ) ) then
+            outputChatBox( "The cursor alpha: "..getCursorAlpha( ) )
+        else
+            outputChatBox( "The cursor is not showing!" )
+        end
+    end
+)

assets/setCursorAlpha.jpg

@@ -0,0 +1,11 @@
+function cursorInfo()
+    if isCursorShowing() then -- if the cursor is showing
+        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
+    else
+        outputChatBox( "Your cursor is not showing." )
+    end
+end
+addCommandHandler( "cursorpos", cursorInfo )

elements/.gitkeep

@@ -0,0 +1,16 @@
+addEventHandler( "onClientRender", root,
+    function()
+        if isCursorShowing() then
+            local screenx, screeny, worldx, worldy, worldz = getCursorPosition()
+            local px, py, pz = getCameraMatrix()
+            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
+            end
+        end
+    end
+)

events/.gitkeep

@@ -0,0 +1,8 @@
+function toggleCursor(playerElement)
+    if playerElement and isElement(playerElement) then -- Check whether the given element exists
+        local cursorState = isCursorShowing(playerElement) -- Retrieve the state of the player's cursor
+        local cursorStateOpposite = not cursorState -- The logical opposite of the cursor state
+
+        showCursor(playerElement, cursorStateOpposite) -- Setting the new cursor state
+    end
+end

functions/.gitkeep

@@ -0,0 +1,8 @@
+function outputCursor(playerElement)
+    if playerElement and isElement(playerElement) then -- Check whether the given element exists
+        local cursorState = isCursorShowing(playerElement) -- Retrieve the state of the player's cursor
+        local cursorStateText = cursorState and "visible" or "hidden" -- Calculate the context from the boolean variable.
+
+        outputChatBox("Your cursor is " .. cursorStateText .. ".", playerElement) -- Output the text in the chatbox according to the cursor state.
+    end
+end

functions/Cursor/examples/getCursorAlpha.lua

@@ -0,0 +1,6 @@
+function toggleCursor()
+    local cursorState = isCursorShowing() -- Retrieve the state of the player's cursor
+    local cursorStateOpposite = not cursorState -- The logical opposite of the cursor state
+
+    showCursor(cursorStateOpposite) -- Setting the new cursor state
+end

functions/Cursor/examples/getCursorPosition-1.lua

@@ -0,0 +1,3 @@
+function toggleCursor()
+    showCursor(not isCursorShowing())
+end

functions/Cursor/examples/getCursorPosition-2.lua

@@ -0,0 +1,8 @@
+function toggleCursor()
+    local cursorState = isCursorShowing() -- Retrieve the state of the player's cursor
+    local cursorStateOpposite = not cursorState -- The logical opposite of the cursor state
+
+    showCursor(cursorStateOpposite) -- Setting the new cursor state
+end
+
+bindKey("m", "down", toggleCursor) -- Assigning our toggleCursor function to the 'm' key press.

functions/Cursor/examples/isCursorShowing-1.lua

@@ -0,0 +1,5 @@
+bindKey("m", "down",
+    function()
+        showCursor(not isCursorShowing())
+    end
+)

functions/Cursor/examples/isCursorShowing-2.lua

@@ -0,0 +1,9 @@
+-- Simple command to test the setCursorAlpha function
+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
+)

functions/Cursor/examples/isCursorShowing-3.lua

@@ -0,0 +1,10 @@
+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
+    else
+        outputChatBox( "Your cursor is not showing." )
+    end
+end
+addCommandHandler( "cursorpos", centerCursorFunction )

functions/Cursor/examples/isCursorShowing-4.lua

@@ -0,0 +1,7 @@
+local thePlayer = getPlayerFromName ( "Dave" )              -- get the player named Dave
+if thePlayer then                                           -- if we got him
+    showCursor ( thePlayer, true )                          -- make his cursor show
+    if isCursorShowing ( thePlayer ) then                   -- did it show?
+        outputChatBox ( "Cursor is now showing for Dave." ) -- print a message to the chat box
+    end
+end

functions/Cursor/examples/isCursorShowing-5.lua

@@ -0,0 +1,2 @@
+showCursor ( true ) -- Shows cursor
+showCursor ( false ) -- Doesnt Show Cursor

functions/Cursor/examples/isCursorShowing-6.lua

@@ -0,0 +1,17 @@
+client:
+  name: 'getCursorAlpha'
+  pair: 'setCursorAlpha'
+  description: |
+    This function is used to get the client's cursor alpha (transparency). 
+  returns:
+    description: |
+      Returns a int 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'
+  see_also:
+    - 'category:GUI functions'

functions/Cursor/examples/setCursorAlpha.lua

@@ -0,0 +1,35 @@
+client:
+  name: 'getCursorPosition'
+  pair: 'setCursorPosition'
+  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.
+    (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.
+      If the cursor isn't showing, returns *false* as the first value.
+    values:
+      - type: 'float'
+        name: 'cursorX'
+      - type: 'float'
+        name: 'cursorY'
+      - type: 'float'
+        name: 'worldX'
+      - type: 'float'
+        name: 'worldY'
+      - type: 'float'
+        name: 'worldZ'
+  issues:
+    - id: 1166
+      description: 'getCursorPosition() returns false even when cursor is showing due to opened console'
+  examples:
+    - path: 'examples/getCursorPosition-1.lua'
+      description: |
+        This example prints your cursors current world coordinates and relative screen coordinates to chatbox after typing cursorpos.
+    - 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.

functions/Cursor/examples/setCursorPosition.lua

@@ -0,0 +1,45 @@
+shared: &shared
+  name: 'isCursorShowing'
+  description: |
+    This function determines the state of a 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.
+  returns:
+    description: |
+      Returns *true* if the player's cursor is visible, and *false* if it is not.
+    values:
+      - type: 'bool'
+        name: 'result'
+
+server:
+  <<: *shared
+  parameters:
+    - name: 'playerElement'
+      type: 'player'
+      description: 'The [[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.
+    - 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.
+
+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. 
+    - 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. 
+    - path: 'examples/isCursorShowing-6.lua'
+      description: |
+        If you are already advanced in scripting, using this code is recommended, as it is much more compact:
+      append: true

functions/Cursor/examples/showCursor-1.lua

@@ -0,0 +1,24 @@
+client:
+  name: 'setCursorAlpha'
+  pair: 'getCursorAlpha'
+  description: |
+    This function is used to change alpha (transparency) from the client's cursor.
+  preview:
+    - path: '/assets/setCursorAlpha.jpg'
+      description: 'Example for setCursorAlpha'
+  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.'
+  returns:
+    description: |
+      Returns *true* if the new alpha value was set, or *false* otherwise.
+    values:
+      - type: 'bool'
+        name: 'result'
+  version:
+    added: '1.3.2'
+  examples:
+    - path: 'examples/setCursorAlpha.lua'
+  see_also:
+    - 'category:GUI functions'

functions/Cursor/examples/showCursor-2.lua

@@ -0,0 +1,22 @@
+client:
+  name: 'setCursorPosition'
+  pair: 'getCursorPosition'
+  description: 'This function sets the current position of the mouse cursor.'
+  parameters:
+    - name: 'cursorX'
+      type: 'int'
+      description: 'Position over the X axis'
+    - name: 'cursorY'
+      type: 'int'
+      description: 'Position over the Y axis'
+  returns:
+    description: 'Returns *true* if the position has been successfully set, *false* otherwise.'
+    values:
+      - type: 'bool'
+        name: 'result'
+  examples:
+    - path: 'examples/setCursorPosition.lua'
+      description: |
+        This example sets your cursor position to the center of your screen after using the command *cursorpos*.
+  see_also:
+    - 'tag:Client input functions'

functions/Cursor/getCursorAlpha.yaml

@@ -0,0 +1,40 @@
+shared: &shared
+  name: 'showCursor'
+  description: |
+    This function is used to show or hide a [[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.
+  parameters:
+    - name: 'thePlayer'
+      type: 'player'
+      description: 'The [[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.'
+    - name: 'toggleControls'
+      type: 'bool'
+      description: |
+        A boolean value determining whether to disable controls whilst the cursor is showing. *true* implies controls are disabled, *false* implies controls remain enabled.
+  returns:
+    description: |
+      Returns *true* if the player's cursor was shown or hidden successfully, *false* otherwise. 
+    values:
+      - type: 'bool'
+        name: 'result'
+
+server:
+  <<: *shared
+  examples:
+    - path: 'examples/showCursor-1.lua'
+      description: |
+        This example shows the cursor for a player named "Dave", then outputs a message if it was shown successfully. 
+
+client:
+  <<: *shared
+  ignore_parameters:
+    - 'thePlayer'
+  examples:
+    - path: 'examples/showCursor-2.lua'
+      description: |
+        This example shows the cursor all the time 

functions/Cursor/getCursorPosition.yaml

@@ -0,0 +1,68 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: /schemas/function
+title: Function schema
+type: object
+
+$defs:
+  common_properties:
+    type: object
+    required:
+      - name
+    properties:
+      name:
+        type: string
+        description: Name of the function.
+      pair:
+        type: string
+        description: Associates this function with another getter or setter function.
+      description:
+        type: string
+        description: Describes the functionality provided by the function.
+      version:
+        description: Version information when the function got added/deprecated/removed.
+        $ref: '#/$defs/version'
+      examples:
+        $ref: '#/$defs/examples'
+  
+  version:
+    type: object
+    properties:
+      added:
+        type: string
+        description: Version when this item was added to MTA.
+      removed:
+        type: string
+        description: Version when this item was removed from MTA.
+      deprecated:
+        type: string
+        description: Version when this item was deprecated in MTA.
+
+  examples:
+    description: A list of source code examples demonstrating the function.
+    type: array
+    items:
+      type: object
+      required:
+        - path
+      properties:
+        path:
+          type: string
+          description: A relative or repository-absolute path to an example source file.
+        description:
+          type: string
+          description: Description for this source code example.
+        append:
+          type: boolean
+          default: false
+          description: If set to true, this example will be appended to the previous example.
+
+properties:
+  shared:
+    description: A shared specification of a function.
+    $ref: '#/$defs/common_properties'
+  server:
+    description: A server-side specification of a function.
+    $ref: '#/$defs/common_properties'
+  client:
+    description: A client-side specification of a function.
+    $ref: '#/$defs/common_properties'