Описание и назначение

TeleportService — это критически важный сервис Roblox Engine, предоставляющий разработчикам возможность перемещать игроков (players) между различными местами (places) внутри одного игрового опыта, между разными серверами (server) одного места, а также в другие игры (game) на платформе. Данный сервис является основой для создания многокомпонентных игр, где лобби, игровые карты, миры и мини-игры существуют как отдельные места. Без TeleportService невозможно реализовать плавный переход из лобби в игру или между уровнями, что делает его незаменимым инструментом для разработчиков любого уровня.

Основное назначение сервиса — управление жизненным циклом игровой сессии. Он позволяет не только инициировать телепорт, но и передавать данные между местами, управлять приватными серверами и обрабатывать события, связанные с перемещением. Вся документация и примеры кода (code samples) для этого сервиса доступны в официальном API Reference, где подробно описаны все методы, свойства и события. Понимание работы TeleportService является обязательным условием для создания масштабируемых и увлекательных игровых миров.

Характеристики и параметры

TeleportService предоставляет широкий набор методов для различных сценариев телепортации. В таблице ниже приведены ключевые параметры и методы, которые вы (you) будете использовать в своей разработке.

Метод / Параметр Тип (type) Описание и назначение
TeleportAsync(placeId, players, teleportData) Метод Основной метод для телепортации. Принимает ID места (place), список игроков (players) и необязательные данные (variant).
TeleportToPlaceInstance(placeId, jobId, players) Метод Телепортирует игроков на конкретный сервер (server) по его JobId. Используется для присоединения к друзьям.
TeleportToPrivateServer(placeId, code, players) Метод Телепортирует игроков в приватный сервер, созданный с помощью ReserveServerAsync.
ReserveServerAsync(placeId) Метод Резервирует приватный сервер и возвращает уникальный код (string) для доступа.
GetPlayerPlaceInstanceAsync(userId) Метод Возвращает PlaceId и JobId сервера, где находится указанный игрок. Полезно для функции "следовать за другом".
GetLocalPlayerTeleportData() Метод Возвращает данные (variant), переданные на новый сервер при телепортации.
GetArrivingTeleportGui() Метод Возвращает пользовательский интерфейс загрузки (GUI), если он был настроен.
PromptExperienceDetailsAsync(player, placeId) Метод Показывает игроку окно с деталями (details) другого опыта и предлагает телепортироваться.
CustomizedTeleportUI Свойство Позволяет настроить пользовательский интерфейс загрузки для всех телепортов.
TeleportInitFailed Событие Срабатывает, когда инициированный телепорт не удался.
LocalPlayerTeleportData Событие Срабатывает на клиенте при получении данных телепортации.

Важно понимать, что все методы, возвращающие данные, такие как ReserveServerAsync или GetPlayerPlaceInstanceAsync, являются асинхронными. Это означает, что для их вызова необходимо использовать pcall() для обработки возможных ошибок и получения результата. Тип возвращаемых данных может быть как простой строкой (string), так и сложной таблицей (variant), в зависимости от метода.

Как получить / Где найти / Как использовать

Для начала работы с TeleportService необходимо получить ссылку на сервис и использовать его методы. Ниже приведен пошаговый алгоритм для реализации базового телепорта.

  1. Получение сервиса. В любом скрипте (серверном или клиентском) получите ссылку на TeleportService с помощью функции game:GetService("TeleportService"). Это стандартный способ доступа ко всем сервисам Roblox.
  2. Определение целевого места. Вам понадобится числовой идентификатор (PlaceId) того места (place), куда вы хотите телепортировать игроков. Этот ID можно найти в настройках вашего места в Creator Dashboard.
  3. Выбор игроков. Определите, кого именно вы хотите телепортировать. Это может быть один игрок, список игроков (players) или вся команда. Для получения списка игроков используйте Players:GetPlayers() или другие методы.
  4. Вызов метода телепортации. Используйте основной метод TeleportService:TeleportAsync(placeId, players). В качестве второго аргумента передайте таблицу с игроками. Пример кода (code) выглядит так: lua local TeleportService = game:GetService("TeleportService") local Players = game:GetService("Players") local TARGET_PLACE_ID = 12345678901234 -- Замените на ваш ID local playerToTeleport = Players:GetPlayers()[1] TeleportService:TeleportAsync(TARGET_PLACE_ID, {playerToTeleport})
  5. Передача данных (необязательно). Если вам нужно передать информацию между местами, например, выбранного персонажа или прогресс, используйте третий аргумент метода TeleportAsync. Это может быть любая переменная типа (type) variant, например, строка (string) или таблица.
  6. Обработка ошибок. Для методов, которые могут завершиться ошибкой (например, ReserveServerAsync), всегда используйте pcall(). Это позволит корректно обработать ситуацию, если сервер недоступен или произошла другая ошибка.
  7. Настройка безопасности. Убедитесь, что в настройках вашего места (place) в Creator Dashboard правильно настроен параметр "Access Control for Places". Это критически важно для предотвращения нежелательных телепортов и эксплойтов.

Советы, хитрости и особенности применения

Совет эксперта: Для создания плавного перехода между местами всегда используйте пользовательский интерфейс загрузки. Вы можете получить его через метод GetArrivingTeleportGui() и настроить под стиль вашей игры (game). Это значительно улучшит впечатление игроков от телепортации.

При работе с TeleportService важно помнить о нескольких ключевых особенностях. Во-первых, телепорт (teleport) — это не мгновенное действие. Игрок видит экран загрузки, и в это время его персонаж покидает текущий сервер. Во-вторых, все данные, которые вы передаете через teleportData, должны быть сериализуемыми. Это означает, что вы можете передавать строки (string), числа, таблицы и другие простые типы (type) данных, но не можете передавать сложные объекты, такие как Instance.

Для реализации функции "следования за другом" используйте метод GetPlayerPlaceInstanceAsync. Этот метод возвращает не только PlaceId, но и JobId конкретного сервера (server), что позволяет телепортироваться точно к другу. Однако помните, что этот метод требует прав на чтение данных о местоположении игрока и может быть недоступен для всех игроков.

Наконец, всегда учитывайте настройки безопасности. Параметр "Allow Third Party Teleports" в настройках вашего места контролирует, можете ли вы (you) телепортировать игроков в игры, которые вам не принадлежат. Для телепортов между вашими собственными играми этот параметр можно отключить. Правильная настройка этих параметров (capabilities) — залог безопасности вашего опыта и защиты от злоумышленников. Помните, что все методы и события TeleportService подробно описаны в официальной документации (summary), и вы всегда можете обратиться к ней для получения дополнительной информации.