diff --git a/functions/Element/examples/getElementPosition.lua b/functions/Element/examples/getElementPosition.lua new file mode 100644 index 0000000..3fa1a3f --- /dev/null +++ b/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) diff --git a/functions/Element/examples/setElementPosition.lua b/functions/Element/examples/setElementPosition.lua new file mode 100644 index 0000000..c3f0e0a --- /dev/null +++ b/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 diff --git a/functions/Element/getElementPosition.yaml b/functions/Element/getElementPosition.yaml new file mode 100644 index 0000000..3e31410 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/functions/Element/setElementPosition.yaml b/functions/Element/setElementPosition.yaml new file mode 100644 index 0000000..b100d31 --- /dev/null +++ b/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' \ No newline at end of file