Add getElementPosition and setElementPosition (PR #1)

Author: botder

functions/Element/examples/getElementPosition.lua

@@ -0,0 +1,8 @@
+-- Create the elegy
+local myElegy = createVehicle(562, 1591.596680, -2495.323242, 18.098244)
+-- Get the vehicle's position
+local x, y, z = getElementPosition(myElegy)
+-- Create the samsite
+local samsite = createObject(3267, x, y, z + 3)
+-- Attach the samsite to the elegy
+attachElementToElement(samsite, myElegy, 0, 0, 0)

functions/Element/examples/setElementPosition.lua

@@ -0,0 +1,34 @@
+function randomPlayersToLocation(p)
+    if not isPlayerStaff(p) then return end
+
+	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("randomtp", randomPlayersToLocation)
+addCommandHandler("playershere", randomPlayersToLocation)
+
+-- Utility function
+local staffACLs = {
+    aclGetGroup("Admin"),
+    aclGetGroup("Moderator")
+}
+
+function isPlayerStaff(p)
+	if isElement(p) and getElementType(p) == "player" and not isGuestAccount(getPlayerAccount(p)) then
+		local object = getAccountName(getPlayerAccount(p))
+
+		for _, group in ipairs(staffACLs) do
+			if isObjectInACLGroup("user." .. object, group) then
+				return true
+			end
+		end
+	end
+	return false
+end

functions/Element/getElementPosition.yaml

@@ -0,0 +1,37 @@
+shared: &shared
+  name: 'getElementPosition'
+  oop:
+    entity: player
+    method: getPosition
+    variable: position
+  pair: 'setElementPosition'
+  description: |
+    This function allows you to retrieve the position coordinates of an element. This can be any real world element, including:
+    - [[player|Players]]
+    - [[vehicle|Vehicles]]
+    - [[object|Objects]]
+    - [[pickup|Pickups]]
+    - [[marker|Markers]]
+    - [[collision shape|Collision shapes]]
+    - [[blip|Blips]]
+    - [[radar area|Radar areas]]
+  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 attaches a samsite on the player's vehicle.
+
+server:
+  <<: *shared
+
+client:
+  <<: *shared

functions/Element/setElementPosition.yaml

@@ -0,0 +1,30 @@
+shared:
+  name: 'setElementPosition'
+  oop:
+    entity: player
+    method: setPosition
+    variable: position
+  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 admins teleport 5 random players to themselves
+  issues:
+    - id: 539
+      description: 'Changing player position when they have a jetpack will remove the jetpack and bug when skin is changed'
+    - id: 529
+      description: 'Player falls from bike when the bike is teleported using setElementPosition'