النقل بين الأماكن

تُقسم العديد من الألعاب إلى عدة أماكن، مثل عالم خيالي مع بلدات وقلع وزنزانات وغابة شاسعة. استخدم TeleportService لنقل المستخدمين بين الأماكن، إلى خوادم مختلفة، أو حتى إلى ألعاب أخرى.

نقل اللاعبين

لنقل اللاعبين، استخدم TeleportService:TeleportAsync(). هذه الطريقة تقبل ثلاثة معلمات:

• PlaceId للمستخدمين الذين ستنقلهم إليهم.
• مصفوفة تحتوي على مثيلات Player التي ترغب في نقلها.
• مثيل اختياري من TeleportOptions يحتوي على خصائص مخصصة لنداء TeleportAsync().

local Players = game:GetService("Players")
local TeleportService = game:GetService("TeleportService")

local TARGET_PLACE_ID = 12345678901234 -- استبدل برقمك الخاص
local playerToTeleport = Players:GetPlayers()[1] -- الحصول على أول مستخدم في اللعبة

TeleportService:TeleportAsync(TARGET_PLACE_ID, {playerToTeleport})

للحصول على اللاعبين المناسبين للنقل، يمكنك استخدام حدث BasePart.Touched أو حدث ProximityPrompt.Triggered للحصول على Player فردي. ثم يمكنك التحقق مما إذا كان اللاعب جزءًا من فريق (Player.Team) أو جماعة (Player.PartyId). أخيرًا، يمكنك استخدام Team:GetPlayers() أو SocialService:GetPlayersByPartyId() إذا كنت ترغب في نقل المجموعة بالكامل بدلاً من الفرد فقط.

تكوين النقل الآمن

ثلاثة إعدادات تتعامل مع أمان النقل.

تحكم الوصول للأماكن يتحكم في نقل اللاعبين إلى لعبتك وهو الإعداد الأكثر أهمية لمنع استغلالات النقل.

• إذا اخترت مفتوح بالكامل، يمكن للاعبين الانضمام إلى أي مكان في لعبتك من خلال النقلات من أي لعبة، بما في ذلك الروابط العميقة، دعوات الألعاب، الانضمام إلى صديق، وغير ذلك.

  هذه خيار جيد إذا كانت لعبتك تحتوي على عدة أماكن وترغب في أن يتمكن الأصدقاء من الانضمام بسهولة إلى بعضهم البعض بغض النظر عن المكان الذي يتواجدون فيه. إذا لم تختر هذا الخيار، فإن اللاعبين الذين يحاولون الانضمام إلى أصدقائهم في أماكن غير البداية سينضمون بدلاً من ذلك إلى مكان البداية في لعبتك.

• إذا اخترت مقيد لنفس الكون فقط، يمكن للاعبين الانضمام إلى أماكن غير البداية فقط من خلال النقلات داخل ألعابك. هذا الإعداد يسمح بكلا النوعين من عمليات النقل التي تبدأ من العميل أو الخادم.

  هذا خيار جيد إذا كان لديك لعبة قديمة لا ترغب في نقلها إلى النقلات الآمنة.

• إذا اخترت آمن داخل الكون فقط، يمكن للاعبين الانضمام إلى أماكن غير البداية فقط من خلال النقلات التي تبدأ من الخادم داخل هذه اللعبة.

  هذا خيار جيد إذا كانت لعبتك تحتوي على نظام تقدم صارم قبل أن يتمكن اللاعبون من الوصول إلى مناطق معينة. كما أنه خيار جيد إذا كانت لعبتك تحتوي على مكان اختبار لا ينبغي أن يتمكن اللاعبون من الوصول إليه أو لأماكن تستخدم الخوادم المحجوزة فقط.

الانتقال إلى النقلات الآمنة

إذا كان لديك لعبة قائمة تستخدم النقلات من جانب العميل وترغب في فرض النقلات التي تبدأ من الخادم، الهدف هو نقل جميع منطق النقل إلى سكربتات الخادم:

1. ابحث عن جميع السكربتات العميلة التي تستدعي Teleport().
2. غير هذه الاستدعاءات لتقوم بدلاً من ذلك بإطلاق الأحداث البعيدة. بدلاً من ذلك، يمكنك تغيير الاستدعاءات لاستخدام ProximityPrompts، ClickDetectors، أو حتى استخدام حدث BasePart.Touched فقط.
3. أعيد تنفيذ النقل في سكربت الخادم باستخدام TeleportAsync().
4. عندما لا توجد المزيد من استدعاءات Teleport()، غير تحكم الوصول للأماكن إلى آمن.

إنشاء شاشات نقل مخصصة

عندما يقوم المستخدم بتفعيل النقل، يرى شاشة التحميل القياسية من Roblox أثناء انتظاره لتحميل المكان الجديد. إذا رغبت في ذلك، يمكنك إضافة شاشة نقل مخصصة من خلال استدعاء TeleportService:SetTeleportGui() على العميل.

المثال التالي يحدد ScreenGui مخصص من ReplicatedStorage. أي سكربتات ضمن ScreenGui لن تعمل.

local TeleportService = game:GetService("TeleportService")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local teleportGui = ReplicatedStorage.TeleportGui

TeleportService:SetTeleportGui(teleportGui)

تخصيص خيارات النقل

يمكنك تخصيص النقل، مثل نقل المستخدمين إلى خادم محدد و إرسال بيانات المستخدم مع النقلات، عن طريق إعداد مثيل TeleportOptions وتمريره إلى طريقة TeleportService:TeleportAsync().

النقل إلى الخوادم المحددة

لنقل المستخدمين إلى خوادم محددة، قم بتعيين الخادم المستهدف باستخدام TeleportOptions وتمريره إلى طريقة TeleportAsync(). إذا لم تحدد خادمًا، يتم نقل المستخدمين إلى خادم عام؛ تُستخدم معلومات أول مستخدم في القائمة للتوفيق.

لنقل المستخدمين إلى خادم عام محدد، قم بتعيين خاصية TeleportOptions.ServerInstanceId كمعرف مثيل صالح، وهو معرف فريد لخادم عام.

local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ServerInstanceId = targetServerId

لنقل المستخدمين إلى خادم محجوز محدد، قم بتعيين TeleportOptions.ReservedServerAccessCode صالح، وهو رمز فريد لدخول خادم محجوز.

local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ReservedServerAccessCode = reservedServerCode

لنقل المستخدمين إلى خادم محجوز جديد، قم بتعيين TeleportOptions.ShouldReserveServer إلى true.

local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ShouldReserveServer = true

إرسال بيانات المستخدم مع النقلات

يؤدي نقل المستخدم بين الأماكن إلى إهمال أي بيانات محلية مرتبطة بهذا المستخدم. يمكنك استخدام الأساليب التالية لمعالجة استمرارية البيانات بين الأماكن:

• إذا كانت لعبتك تستخدم بيانات آمنة مثل العملة داخل اللعبة أو المخزون، قم بتنفيذ محلات البيانات أو محلات الذاكرة للحفاظ على البيانات من مكان إلى آخر.

• لإرسال بيانات غير آمنة أساسية من مكان إلى آخر، استدعِ TeleportOptions:SetTeleportData() قبل تمريرها إلى TeleportAsync(). لا تمرر بيانات آمنة باستخدام هذه الطريقة؛ البيانات مرئية للعميل وغير مشفرة.

local teleportData = {
    randomNumber = RNG:NextInteger(1, 100),
}

local teleportOptions = Instance.new("TeleportOptions")
teleportOptions:SetTeleportData(teleportData)

لاسترجاع جميع البيانات عند وصول مستخدم إلى المكان الجديد بعد النقل، استخدم وظيفة Player:GetJoinData()، التي تُرجع قاموسًا يحتوي على مفتاح TeleportData.

local Players = game:GetService("Players")

local function onPlayerAdded(player)
    local joinData = player:GetJoinData()
    local teleportData = joinData.TeleportData
    local randomNumber = teleportData.randomNumber

    print(player.Name .. " joined with the number " .. randomNumber)
end

Players.PlayerAdded:Connect(onPlayerAdded)

لاسترجاع بيانات النقل فقط على العميل، يمكنك استخدام TeleportService:GetLocalPlayerTeleportData().

التعامل مع النقلات الفاشلة

مثل أي استدعاء API يتضمن طلبات الشبكة، يمكن أن تفشل النقلات وتؤدي إلى ظهور خطأ. قم بتشغيلها في مكالمات محمية (pcall()). بعض الفشل يستفيد من الإعادة، وخاصة تلك التي تتعلق بالخوادم المحجوزة، لذلك نوصي بإعادة المحاولة عدة مرات عند الفشل.

حتى إذا كانت المكالمة ناجحة وبدأت النقل، يمكن أن تفشل في اللحظة الأخيرة دون إصدار خطأ وتترك المستخدم في الخادم. عندما يحدث ذلك، يتم تفعيل حدث TeleportService.TeleportInitFailed.

المثال التالي من ModuleScript يعيد دالة SafeTeleport واحدة تقوم بنقل اللاعبين في مكالمة محمية مع منطق إعادة المحاولة. يحتوي أيضًا على دالة handleFailedTeleport للتعامل مع الحالات التي كانت المكالمة ناجحة ولكن النقل لم يحدث.

local TeleportService = game:GetService("TeleportService")

local ATTEMPT_LIMIT = 5
local RETRY_DELAY = 1
local FLOOD_DELAY = 15

local function SafeTeleport(placeId, players, options)
    local attemptIndex = 0
    local success, result -- تعريف نتائج pcall خارج الحلقة حتى يمكن الإبلاغ عن النتائج لاحقًا

    repeat
        success, result = pcall(function()
            return TeleportService:TeleportAsync(placeId, players, options) -- نقل المستخدم في مكالمة محمية لمنع الأخطاء
        end)
        attemptIndex += 1
        if not success then
            task.wait(RETRY_DELAY)
        end
    until success or attemptIndex == ATTEMPT_LIMIT -- التوقف عن محاولة النقل إذا كانت المكالمة ناجحة، أو إذا تم الوصول إلى حد إعادة المحاولة

    if not success then
        warn(result) -- طباعة سبب الفشل على الإخراج
    end

    return success, result
end

local function handleFailedTeleport(player, teleportResult, errorMessage, targetPlaceId, teleportOptions)
    if teleportResult == Enum.TeleportResult.Flooded then
        task.wait(FLOOD_DELAY)
    elseif teleportResult == Enum.TeleportResult.Failure then
        task.wait(RETRY_DELAY)
    else
        -- إذا كانت النقل غير صالحة، أبلغ عن الخطأ بدلاً من إعادة المحاولة
        error(("Invalid teleport [%s]: %s"):format(teleportResult.Name, errorMessage))
    end

    SafeTeleport(targetPlaceId, {player}, teleportOptions)
end

TeleportService.TeleportInitFailed:Connect(handleFailedTeleport)

return SafeTeleport

تستقبل دالة SafeTeleport نفس المعلمات مثل دالة TeleportAsync(). يمكنك استخدام السكربت التالي مع دالة SafeTeleport لإجراء النقلات من أي مكان في لعبتك:

local Players = game:GetService("Players")
local TeleportService = game:GetService("TeleportService")
local ServerScriptService = game:GetService("ServerScriptService")

local SafeTeleport = require(ServerScriptService.SafeTeleport)

local PLACE_TO_TELEPORT_TO = 12345678

local function teleport(touchPart)
    local playerToTeleport = game.Players:GetPlayerFromCharacter(touchPart.Parent)

    if playerToTeleport then
        SafeTeleport(PLACE_TO_TELEPORT_TO, {playerToTeleport})
    end
end

script.Parent.Touched:Connect(teleport)