Documentation Update for TeleportService

Hello Developers,

We’ve noticed recently that there was a discrepancy between our developer documentation, examples, and the TeleportService:GetPlayerPlaceInstanceAsync API. This specific function is used in conjunction with TeleportService:TeleportToPlaceInstance, and we’ve seen that there was a lot of confusion on the forums in various posts by several developers. We want to clear up that confusion in this announcement, and also let you know how we plan on addressing this particular discrepancy.

If you’ve tried to use this function in the past, you may have seen that in the documentation and the examples that there is already a discrepancy on what is supposed to be returned from the API:

The documentation describes 3 return values (currentInstance, placeId, jobId)

And the example below it makes it appear that there are different return values on a successful pcall (errorMessage, placeId, jobId - a successful pcall will not return a second parameter by default https://www.lua.org/pil/8.4.html).

However, neither of these are correct. What’s actually returned from the TeleportService:GetPlayerPlaceInstanceAsync API is the following:

  1. currentInstance
  2. a blank string
  3. placeId
  4. instanceId

The correct way to use this method would be to do something similar to the code snippet below:

local success, errorMessage = pcall(function()
    -- followId is the user ID of the player that you want to retrieve the place and job ID for
	currentInstance, _, placeId, jobId = TeleportService:GetPlayerPlaceInstanceAsync(followId)
end)
if success then
	-- Teleport player
	TeleportService:TeleportToPlaceInstance(placeId, jobId, player)
end

We apologize that it took this long to recognize this issue. We also understand that some developers may have found workarounds for this problem, so we plan on keeping the functionality the same; we’ll instead be updating the documentation and examples to reflect the current behavior of the TeleportService:GetPlayerPlaceInstanceAsync API.

The TeleportService:TeleportToPlaceInstance API will also be updated to throw an error if an empty instanceId is provided, which would be the scenario that occurs if the developer followed the developer documentation.

Thank you.

97 Likes

Is there a reason why the second argument is a blank string?

36 Likes

Has TeleportService been fixed so you are able to join your friends in game via by a GUI?

Hey @ThomasMGardiner, no other reason than that it’s a bug in the code that we missed.

7 Likes

Hey @UniversalGravity - TeleportService:TeleportToPlaceInstance does work as intended. A way to check is to add some print statements to verify that the function is being invoked with the right parameters, ie. instanceId/jobId is a UUID string, placeId is an integer, etc.

If you’ve followed the developer documentation previously, you’ll have to update your code with something similar to the code snippet in the main post above. We are planning to update the developer documentation soon.

4 Likes

Ah that’s fine, I can’t say I don’t run into bugs myself when I’m coding :sob: Good luck! :slight_smile:

3 Likes

Yeah, this was one of the most annoying things I found with TeleportService haha… Thankfully its looking like there’s going to be a unification of all TeleportService methods sometime soon here like was done with WorldRoot:RayCast(), that’s for sure exciting.

I’m glad to see this get updated! I noticed this a super long time ago, and completely forgot about it… This will definitely help some developers.

1 Like

Awesome thanks for the information!

This post was flagged by the community and is temporarily hidden.