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

تُقسم العديد من الألعاب إلى عدة أماكن، مثل عالم خيالي يحتوي على مدن، وقلاع، وزنزانات، وغابة شاسعة. استخدم 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 .. " انضم بالرقم " .. 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(("نقل غير صالح [%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)