test add set & get element position funcs

Author: Fernando-A-Rocha

functions/Element/examples/getElementPosition.lua

@@ -0,0 +1,2 @@
+-- Find a player's position
+local x, y, z = getElementPosition(player)

functions/Element/examples/setElementPosition.lua

@@ -0,0 +1,12 @@
+function randomPlayersToLocation(p)
+	local playersOnline = getElementsByType("player")
+	local amount = #playersOnline
+
+	if amount == 0 then return end
+
+	for index = 1,(amount > 5 and 5 or amount) do
+		local player = playersOnline[index]
+		setElementPosition(player, getElementPosition(p))
+	end
+end
+addCommandHandler("tprandomplayers", randomPlayersToLocation)

functions/Element/getElementPosition.yaml

@@ -0,0 +1,30 @@
+shared:
+  name: 'getElementPosition'
+  pair: 'setElementPosition'
+  description: |
+    This function allows you to retrieve the position coordinates of an element. This can be any real world element, including:
+    - Players
+    - Vehicles
+    - Objects
+    - Pickups
+    - Markers
+    - Collision shapes
+    - Blips
+    - Radar areas
+    - Syntax
+  returns:
+    description: |
+      Returns three floats indicating the position of the element, x, y and z respectively.
+    values:
+      - type: 'float'
+        name: 'x'
+      - type: 'float'
+        name: 'y'
+      - type: 'float'
+        name: 'z'
+  examples:
+    - path: 'examples/getElementPosition.lua'
+      description: |
+        This example shows how to obtain the position of a player.
+  see_also:
+    - 'category:Element functions'

functions/Element/setElementPosition.yaml

@@ -0,0 +1,23 @@
+shared:
+  name: 'setElementPosition'
+  pair: 'getElementPosition'
+  description: |
+    This function sets the position of an element to the specified coordinates.
+  notes:
+    - |
+      Warning: Do not use this function to spawn a [[player]]. It will cause problems with other functions like [[warpPedIntoVehicle]]. Use [[spawnPlayer]] instead.
+    - |
+      If you want to put a vehicle or player out of the water or simulate the position-resetting behaviour if CJ goes below the ground too far, then you need to retrieve a recommended coordinate on ground to place the element at. Take a look at this MTA forums post for steps in the right direction.
+      https://forum.mtasa.com/topic/132891-important-helprespawn-vehicle/?do=findComment&comment=1003198
+  returns:
+    description: |
+      Returns *true* if the function was successful, *false* otherwise.
+    values:
+      - type: 'bool'
+        name: 'result'
+  examples:
+    - path: 'examples/setElementPosition.lua'
+      description: |
+        This example lets you teleport 5 random players to yourself
+  see_also:
+    - 'category:Element functions'