Difference between revisions of "Global Command: getCursorPos"

Revision as of 15:57, 2 May 2023

Get the current position of the mouse cursor.

Note that the function returns the cursor position in relation to the screen instead of in relation to the scene. This difference matters if your scene is larger than your screen resolution and thus scrollable. Have a look at example 2 on how to deal with this.

Syntax

GetCursorPos()

Parameters

none

Return values

Type/Structure	Description
table {x,y}	The current mouse cursor position is returned as an associative array containing the elements x and y.

Examples

Example 1: Check if the current cursor position matches a defined position.

-- Store the current position into a variable
local curPos = getCursorPos()

-- Check if the stored cursor position equals another {x,y} value
if curPos.x == 200 and curPos.y == 400 then
  return true
else
  return false
end

Example 2: Function to get the cursor position in relation to the scene by taking the current scroll position into account.

function getAbsoluteCursorPos()
  -- Store the current position into a variable
  local curPos = getCursorPos()

  -- Empty table to store the absolute position
  local curAbsPos = {}

  -- Add the current scroll position to the cursor position
  curAbsPos.x = game.ScrollPosition.x + curPos.x
  curAbsPos.y = game.ScrollPosition.y + curPos.y

  return curAbsPos
end

@@ Line 1: / Line 1: @@
-{| class="toccolours mw-collapsible mw-collapsed ts"
+Get the current position of the mouse cursor.
-! Function History
-|-
+Note that the function returns the cursor position in relation to the screen instead of in relation to the scene. This difference matters if your scene is larger than your screen resolution and thus scrollable. Have a look at example 2 on how to deal with this.
-| Available since v3.3
-|}
+== Syntax ==
+<syntaxhighlight lang="lua">
+GetCursorPos()
+</syntaxhighlight>
+== Parameters ==
+none
-Stores the current position (absolute) of the mouse cursor into an x,y table, which can be used in a query to check if the current position is over an object/character or a certain part of the scene etc. ''Note: just noticed that it is actually returning coordinates based on current scroll position, as if: scroll position is always 0,0 instead of what it should be. You can counteract this by adding cursor position + scroll position together.''
+== Return values ==
+{| class="ts"
+|-
+! style="width:15%" | Type/Structure
+! Description
+|-
+| table {x,y}
+| The current mouse cursor position is returned as an associative array containing the elements ''x'' and ''y''.
+|}
-Syntax:
-<syntaxhighlight>
-getCursorPos()
-</syntaxhighlight>
+== Examples ==
-Example:
+'''Example 1:''' Check if the current cursor position matches a defined position.
-<syntaxhighlight>
+<syntaxhighlight lang ="lua">
--- let's store the current position into a variable!
+-- Store the current position into a variable
 local curPos = getCursorPos()
--- let's check if the stored cursor position equals another x,y value!
+-- Check if the stored cursor position equals another {x,y} value
 if curPos.x == 200 and curPos.y == 400 then
- -- do some action!
+  return true
 else
- -- do some other action!
+  return false
 end
 </syntaxhighlight>
-Example 2: Counteracting the scroll position issue. (''example below require vs 4.1'')
-<syntaxhighlight>
-local pos = {} -- empty table
-pos.x = game.ScrollPosition.x + getCursorPos().x -- absolute x position on entire scene
-pos.y = game.ScrollPosition.y + getCursorPos().y -- absolute y position on entire scene
-</syntaxhighlight>
+'''Example 2:''' Function to get the cursor position in relation to the scene by taking the current scroll position into account.
+<syntaxhighlight lang ="lua">
+function getAbsoluteCursorPos()
+  -- Store the current position into a variable
+  local curPos = getCursorPos()
-<span class="bold underline">Arguments</span>
+  -- Empty table to store the absolute position
+  local curAbsPos = {}
-none
+  -- Add the current scroll position to the cursor position
+  curAbsPos.x = game.ScrollPosition.x + curPos.x
+  curAbsPos.y = game.ScrollPosition.y + curPos.y
+  return curAbsPos
-<span class="bold underline">Flags</span>
+end
+</syntaxhighlight>
-none
+{{toc}}
-<span class="bold underline">Return</span>
-<span class="bold">pos</span> <br/>
-Table containing x,y values of current mouse cursor position