ارسال درخواست Match-Making

دقت کنید که این مستند مخصوص رقابت آنلاین است و برای نیازمندی‌های چت هیچ کاربردی ندارد.

سرویس Match-Making به شما کمک می‌کند که بتوانید با بازیکنان هم‌سطح خود مسابقه دهید. این سرویس در اکثر بازی‌ها مهم و مورد نیاز است، و در هر بازی که رقابت آنلاین (مبارزه چند کاربر واقعی و نه هوش مصنوعی به صورت آنلاین) معنی داشته باشد، مفهوم Match-Making نیز مورد نیاز خواهد بود. اگر به طور دقیق با این مفهوم در بکتوری آشنایی ندارید، به آشنایی با سرویس Match-Making مراجعه کنید.

در این مستند کارهایی که با SDK یونیتی برای Match-Making می‌توانید انجام دهید را توضیح خواهیم داد.

منظور از Match-Making در بکتوری، اتصال هوشمندانه بازیکنان هم‌سطح به یکدیگر برای شروع یک Match است، اما برای شروع یک Match می‌توانید به جای Match-Making از روش به چالش کشیدن دوستان نیز استفاده کنید که جایگزینی برای Match-Making است.

پیش‌نیاز

1. در صورتی که با سرویس بلادرنگ آشنایی ندارید، به معرفی سرویس بلادرنگ مراجعه کنید.
2. در صورتی که هنوز با تنظیمات پنل سرویس بلادرنگ آشنا نشده اید، به تنظیمات پنل سرویس بلادرنگ مراجعه کنید.
3. اگر با سرویس Match-Making آشنایی ندارید، به آشنایی با سرویس Match-Making مراجعه کنید.
4. اگر هنوز SDK یونیتی را راه‌اندازی نکرده‌اید، به راه‌اندازی SDK یونیتی مراجعه کنید.
5. در صورتی که با نحوه‌ی اتصال به سرویس بلادرنگ و ایجاد یک چت ساده به کمک آن آشنایی ندارید، مستند اتصال ساده و ارسال پیام را حتما مطالعه کنید.

درخواست برای Match-Making

در صورتی که به سرویس بلادرنگ بکتوری متصل شوید، می‌توانید بر روی اتصال انجام شده درخواست Match-Making دهید. همچنین باید تعریف انواع Match-Making را در پنل انجام داده باشید.

در اپلیکیشن شما، کاربر با کلیک بر روی دکمه یا منو یا … با محتوای “درخواست رقابت” اعلام می‌کند که می‌خواهد وارد یک رقابت آنلاین با دیگر کاربران شود. شما پس از درخواست کاربر باید کدی مشابه زیر را برای درخواست یک رقابت آنلاین به بکتوری بدهید: (از این مثال استفاه شده است.)

// 1. Create match-making object
BacktoryMatchMaking backtoryMatchMaking =
    new BacktoryMatchMaking ("group_fight_classic", 3300);

// 2. Request for match making
backtoryMatchMaking.Request("{\"name\": \"ali\", \"profilePic\": \"http://storage.backtory.com/my-app/test.png\" }", (response) =>
    {
        // 3. Check if request sent successfully or not
        if (response.Successful) {
            Debug.Log("Request match succeeded.");
        } else {
            Debug.Log("Operation failed with code: "
                    + response.Code
                    + " and message: "
                    + response.Message);
        }
    });

توضیح: کد بالا در سه قدم کوچک، یک درخواست group_fight_classic داد:

1. شیء Match-Making بکتوری را با کمک عملگر new و برای group_fight_classic با مقدار MMR برابر 3300 ایجاد کرد.
2. به کمک شیءایجاد شده یک درخواست به همراه یک متادیتا ارسال کرد.
3. چک کرد که درخواست با موفقیت به دست سرور رسیده باشد.

فیلد MetaData: در مثال بالا یک رشته دلخواه به عنوان متادیتای کاربر فعلی به سرویس Match-Making ارسال شد، این متادیتا تاثیری در فرآیند انطباق بازیکنان با هم ندارد. در صورتی که یک رقابت آنلاین برای این درخواست پیدا شود، این متادیتا برای همه بازیکنان در آن رقابت ارسال خواهد شد و می‌توانند نام بازیکن (ali) و تصویر او (test.png) را در صفحه بازی نشان دهند.

کنسل کردن درخواست Match-Making

در صورتی که کاربر شما در حین پیدا شدن رقابت توسط Match-Making از انجام رقابت پشیمان شد (یعنی قبل از اینکه رقابت پیدا شود)، می‌تواند درخواست خود را کنسل کند. برای کنسل کردن درخواست باید شیءی که در مرحله قبل ایجاد کرده بود، را نگه‌داری کرده باشد. با داشتن شیء Match-Making بکتوری با کدی مانند زیر می‌توان درخواست را کنسل کرد:

// 1. Cancel previous request
backtoryMatchMaking.Cancel ((response) =>
{
    // 2. Check if request cancelled successfully or not
    if (response.Successful) {
        Debug.Log("Your matchmaking request is cancelled now.");
    } else {
        Debug.Log("Operation failed with code: "
            + response.Code
            + " and message: "
            + response.Message);
    }
});

همانطور که می‌بینید در دو مرحله با داشتن شیء Match-Making می‌توان درخواست قبلی را لغو کرد:

1. یک درخواست کنسل روی شیء Match-Making که داریم، ارسال می‌کنیم.
2. چک می‌کنیم که درخواست با موفقیت به دست سرور رسیده باشد.

تنظیم MatchmakingListener

در قسمت‌های قبلی دیدید که چگونه می‌توان درخواست Match-Making را ارسال کرد، و پس از ارسال آن را کنسل نمود. در ادامه خواهید دید که چگونه اتفاقاتی که از طرف سرور به اپلیکیشن ارسال می‌شود را فهمیده و عکس‌العمل مناسب نشان دهید. این اتفاقات عبارتند از:

• وضعیت Match-Making به‌روز شود، مثلا یه کاربر هم امتیاز درخواست Match-Making کند. (Match-Making Update)
• یک Match بر اساس درخواست بازیکنان پیدا شود. (Match Found)
• عملیات Match-Making شکست بخورد، یعنی در زمان تعیین شده، بازیکنان کافی پیدا نشود. (Match Not Found)

برای دریافت این سه پیام باید از همان شیء Match-Making بکتوری استفاده کنید که آن را ایجاد کرده و روی آن درخواست ارسال کرده بودید. نمونه کد راه‌اندازی آن به صورت زیر است:

backtoryMatchMaking.OnMatchFound = (match) => {
    // 1. TODO: handle match found here
};
backtoryMatchMaking.OnMatchmakingUpdate = (participantList) => {
    // 2. TODO: handle match-making update here
};
backtoryMatchMaking.OnMatchNotFound = (message) => {
    // 3. TODO: handle match not found here
};

در ادامه به توضیح هر یک از لیسنرهای بالا خواهیم پرداخت. این لیسنرها در مواقع لازم توسط بکتوری فراخوانی خواهند شد و شما می‌توانید منطق مورد نظر خود را در این سه تابع پیاده‌سازی کنید:

• پیام OnMatchmakingUpdate
• پیام OnMatchFound
• پیام OnMatchNotFound

دریافت پیام MatchMaking Update

از زمانی که شما درخواست Match-Making بدهید، تا زمانی که واقعا بازی به حد نصاب برسد، چندین بار وضعیت Match-Making به روزرسانی می‌شود. برای مثال در یک رقابت ده نفره، وقتی نفر دوم درخواست می‌دهد و با نفر اول انطباق پیدا می‌کند، وضعیت Match-Making از وضعیت یک نفره به وضعیت دو نفره می‌رود. همینطور برای بازیکنان سوم، چهارم، … تا دهم. در واقع وقتی کاربر شما درخواست برای رقابت آنلاین می‌دهد، تا زمانی که همه بازیکنان درخواست بدهند و بازی آغاز شود، به ازای هر تغییر در وضعیت، تمام بازیکنان خبردار می‌شوند. همانطور که در قسمت قبل دیدیم، این خبردارشدن به واسطه‌ی شیء BacktoryMatchMaking و از طریق تابع OnMatchmakingUpdate اتفاق می‌افتد.

backtoryMatchMaking.OnMatchmakingUpdate = (mmUpdateMessage) =>
{
    Debug.Log("Matchmaking update received.");
    Debug.Log("Match update webhook response: " + mmUpdateMessage.ExtraMessage);

    var participantList = mmUpdateMessage.Participants;
    Debug.Log("Players of Match until now: ");
    for (int i = 0; i < participantList.Count; i++) {
        Debug.Log("UserId: " + participantList[i].UserId);
        Debug.Log("MetaData: " + participantList[i].MetaData);
    }
};

دریافت پیام Match Found

در صورتی که شما درخواست یک رقابت آنلاین را از طریق مکانیزم Match-Making بدهید، و تعدادی کاربر هم‌سطح دیگر نیز این درخواست را بدهند، سرویس Match-Making آنها را با هم انطباق می‌دهد و به همگی آنها پیام یافت‌شدن رقابت (Match-Found) را ارسال می‌کند. شما در تابع OnMatchFound مطابق زیر می‌توانید متوجه پیدا شدن یک رقابت آنلاین برای کاربر فعلی گوشی شوید.

نمونه کد زیر تابع OnMatchFound از شیء BacktoryMatchMaking را پیاده‌سازی و اطلاعات رقابت آنلاین را چاپ می‌کند:

backtoryMatchMaking.OnMatchFound = (BacktoryMatch match) =>
{
    Debug.Log("Found Match Id: " + match.MatchId);
    Debug.Log("Address: " + match.Address);
    Debug.Log("Match found webhook response: " + match.ExtraMessage);

    Debug.Log("Players of Match: ");
    for (int i = 0; i < match.MatchParticipants.Count; i++)
    {
        Debug.Log("UserId: " + match.MatchParticipants[i]);
    }
};

در کد بالا، فیلد MatchId شناسه رقابت آنلاینی است که ایجاد شده و فیلد Address آدرس بازی در سرور بکتوری است.

دریافت پیام Match Not Found

در حالتی که تعدادی کاربر درخواست Match-Making بدهند، و در زمان معین شده در پنل تعداد بازیکنان به حد نصاب نرسد، عملیات با شکست مواجه خواهد شد. در این حالت، همه کاربرانی که درخواست داده بودند، از طریق تابع OnMatchNotFound از شیء BacktoryMatchMaking مطلع خواهند شد.

تکه کد زیر اطلاعاتی را که در شیء BacktoryMatchNotFoundMessage دریافت شده وجود دارد، لاگ می‌زند.

backtoryMatchMaking.OnMatchNotFound = (BacktoryMatchNotFoundMessage message) =>
{
    Debug.Log("Request with id: " + message.MatchMakingRequestId + " failed.");
    Debug.Log("Category: " + message.MatchmakingName);
    Debug.Log("Skill: " + message.Skill);
    Debug.Log("MetaData: " + message.MetaData);
};

در قسمت دریافت پیام Match Found دیدید که چگونه با پیدا شدن یک Match در بکتوری، یک شیء BacktoryMatch دریافت می‌کنید. در ادامه راه، به کمک این شیء باید به رقابت آنلاین وصل شده و بازی را انجام دهید. در مستند رقابت آنلاین خواهید دید که چگونه می‌توان یک رقابت را به کمک بکتوری انجام داد.

گام بعدی

• به چالش کشیدن دوستان (Challenge)