SetElementPosition: Difference between revisions

Latest revision as of 18:59, 11 July 2024

This function sets the position of an element to the specified coordinates.

[[\|link=\|]]	Warning: Do not use this function to spawn a player. It will cause problems with other functions like warpPedIntoVehicle. Use spawnPlayer instead.

Syntax

bool setElementPosition ( element theElement, float x, float y, float z [, bool warp = true ] )

OOP Syntax Help! I don't understand this!

Method: element:setPosition(...)

Variable: .position

Counterpart: getElementPosition

Required Arguments

theElement: A valid element to be moved.
x: The x coordinate of the destination.
y: The y coordinate of the destination.
z: The z coordinate of the destination.

Optional Arguments

warp: teleports players, resetting any animations they were doing. Setting this to false preserves the current animation.

Returns

Returns true if the function was successful, false otherwise.

Example

Click to collapse [-]

Server

This example lets admins teleport 5 random players to themselves

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

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.

Issues

Issue ID	Description
#539	Changing player position when he/she has a jetpack will remove the jetpack and bug when skin is changed
#529	Player falls from his bike when its teleported by setElementPosition

@@ Line 1: / Line 1: @@
 __NOTOC__
-This function sets the position of an element to the co-ordinates specified.
+{{Shared function}}
+This function sets the position of an element to the specified coordinates.
+{{Warning|Do not use this function to spawn a [[player]]. It will cause problems with other functions like [[warpPedIntoVehicle]]. Use [[spawnPlayer]] instead.}}
 ==Syntax==
 <syntaxhighlight lang="lua">
-bool setElementPosition ( element theElement, float x, float y, float z )
+bool setElementPosition ( element theElement, float x, float y, float z [, bool warp = true ] )
 </syntaxhighlight>
+{{OOP||[[element]]:setPosition|position|getElementPosition}}
 ===Required Arguments===
 *'''theElement:''' A valid [[element]] to be moved.
-*'''x:''' The x co-ordinate of the destination.
+*'''x:''' The x coordinate of the destination.
-*'''y:''' The y co-ordinate of the destination.
+*'''y:''' The y coordinate of the destination.
-*'''z:''' The z co-ordinate of the destination.
+*'''z:''' The z coordinate of the destination.
+===Optional Arguments===
+*'''warp:''' teleports players, resetting any animations they were doing. Setting this to ''false'' preserves the current animation.
 ===Returns===
 Returns ''true'' if the function was successful, ''false'' otherwise.
 ==Example==
-This example does...
+<section name="Server" class="server" show="true">
+This example lets admins teleport 5 random players to themselves
 <syntaxhighlight lang="lua">
---This line does...
+function randomPlayersToLocation(p)
-blabhalbalhb --abababa
+    if not isPlayerStaff(p) then return end
---This line does this...
-mooo
+	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
 </syntaxhighlight>
+</section>
+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 [https://forum.mtasa.com/topic/132891-important-helprespawn-vehicle/?do=findComment&comment=1003198 this MTA forums post] for steps in the right direction.
+==Issues==
+{{Issues|
+{{Issue|539|Changing player position when he/she has a jetpack will remove the jetpack and bug when skin is changed}}
+{{Issue|529|Player falls from his bike when its teleported by setElementPosition}}
+}}
 ==See Also==
 {{Element functions}}
-[[Category:Incomplete]]
+[[hu:setElementPosition]]
+[[ru:setElementPosition]]