question

dylan-1 avatar image
dylan-1 asked

Matchmaking: V1? V2? PubSub? Deprecated vs not? Confusing docs?

The docs are wildly confusing and seemingly neglected: Seems that there's both a v1 and v2 version of matchmaking, where 2 years later the docs still aren't updated (?!) and intermingling words of the old one (such as using the term game mode) with the new.

In my Matchmake() calls, I keep getting an error that my "game mode" is invalid, but there is no game mode in v2. This led me to believe I have v1. However, staff in Discord linked v2 docs that linked to an example API doc that... is what I implemented and allegedly deprecated (and now is being called both v1 and v2 in a paradoxical manner).

There is also a "Matchmaker" API and a "Multiplayer Matchmaking" API in both the docs and unreal SDK, to add to the confusion:

cjYWfPP.png

If this wasn't confusing enough, there's more. Within the API doc link ago, if you go back to that section's summary page, you will see [Un]Subscribe calls for PubSub:

fuPXMnY.png

...However, there is no further documentation about how to actually use these [in Unreal SDK or any]. In fact, if I search the Unreal SDK for keywords, there's not a single instance of PubSub or Subscribe in the entire SDK!

Then if you search the docs for PubSub, we find this.

5414-image.png

Now, here we can see the summary of how PubSub works: 5415-image.png

...wait, no we cannot because there's no summary here! Not a single description. Perhaps the related links would guide us in how to use pubsub for matchmaking, since it's referenced in the multiplayer matchmaking module?

5416-image.png

Nope, not here, either.

While trying to sift through the forums here, the Microsoft Discord and the BaaS Discord -- I find that everyone is confused and no one seems to truly have an answer. The closest thing I got to an answer was link to the v2 matchmaking docs earlier, but again that linked to another deprecated API call that results in "invalid game mode" errors (game mode doesn't exist in v2, meaning the v2 docs still intermingle with v1 docs); just a giant wild goose chase of deprecated documentation.

Is there any staff here that can verbosely explain which is new, which is old, what the diff is between the "matchmaker" api and "multiplayer api matchmaking calls" (where one of these seems to be deprecated), what is deprecated and what is not, how to setup pubsub [ue4] and interact with these -- just things that the scattered docs don't seem to actually explain?

apisunrealMatchmakingdocumentation
image.png (30.0 KiB)
image.png (30.0 KiB)
10 |1200

Up to 2 attachments (including images) can be used with a maximum of 512.0 KiB each and 1.0 MiB total.

Xiao Zha avatar image
Xiao Zha answered

>> There is also a "Matchmaker" API and a "Multiplayer Matchmaking" API in both the docs and unreal SDK, to add to the confusion.

Matchmaker API is for Legacy Custom Servers, while the Multiplayer Matchmaking API is the new one. You can follow the documentation: Matchmaking quickstart - PlayFab | Microsoft Learn to learn how to use new PlayFab Matchmaking service, and there is no mention of Legacy Matchmaker API in this documentation.

>> you will see [Un]Subscribe calls for PubSub. there is no further documentation about how to actually use these [in Unreal SDK or any].

Those APIs you mentioned are used for implementing Lobby and Matchmaking real time notification feature when the SDK doesn’t meet your needs. Refer to Real-time notifications for Lobby and Matchmaking APIs - PlayFab | Microsoft Learn. If you are using Client SDK, the real-time notification feature has already been integrated with the Client SDKs (such as Lobby C++ SDK, Unreal Engine 4 SDK and Unity SDK), you can refer to Lobby and Matchmaking real-time Notifications - PlayFab | Microsoft Learn.

4 comments
10 |1200

Up to 2 attachments (including images) can be used with a maximum of 512.0 KiB each and 1.0 MiB total.

dylan-1 avatar image dylan-1 commented ·

Thanks: A few follow-ups:

  1. If Matchmaker deprecated a couple years ago, can you please mark the API docs as DEPRECATED top-and-center with a link to the new one, as well as inline in the SDK? A top level "Matchmaker" looks way more enticing than a nested matchmaking under multiplayer. If this was deprecated 2 years ago, no one should even have to think twice that this is the old version - or where to find the new one. This should have been done on day 1, imo, to prevent confusion (and Googling / Discording, seems like I'm not the only one confused).

  2. For client matchmaking, I am still a bit lost. Take Client Matchmaking's Matchmake(): https://i.imgur.com/XMljDeB.png

This takes:

GameMode | string | Game mode to match make against. [Note: Required if LobbyId is not specified]

However, GameMode !exists in the game. Unless this client module was also deprecated 2 years ago and not marked either in the api docs or within the sdk?

0 Likes 0 ·
Xiao Zha avatar image Xiao Zha dylan-1 commented ·

Thanks for your suggestion, we will consider it. Also, the Matchmaking APIs in Client directory are the legacy method and no longer be supported. If you want to use PlayFab Matchmaking service, you can follow the documentation: Matchmaking - PlayFab | Microsoft Learn and use matchmaking V2 APIs: Matchmaking - REST API (PlayFab Multiplayer) | Microsoft Learn for matchmaking.

0 Likes 0 ·
dylan-1 avatar image dylan-1 commented ·

when the SDK doesn’t meet your needs.

How can it meet the needs without it? Poll every 1 second for matchmaking updates?

0 Likes 0 ·
Xiao Zha avatar image Xiao Zha dylan-1 commented ·

If you want to use REST and SignalR APIs to implement a custom notification system without the client SDK, you can refer to Real-time notifications SignalR Hub - PlayFab | Microsoft Learn, and you don’t need to poll for the changes of lobbies and matches.

0 Likes 0 ·
Carlos Feldmann avatar image
Carlos Feldmann answered

I had to implement manually the real time notifications because the Playfab Party Matchmaking SDK doesn't support Android/iOS (really why?????).

So you will need an SignalR client to connect to the PlayFab pubsub, the Default One is difficult to setup in Unity, so I bought the Best HTTP2 Package.

Then you need to implement a flow similar to this:

Create a SignalR connection to this endpoint https://titleId.playfabapi.com/PubSub Docs, you will need to authenticate the current logged in player, the Best HTTP2 provides an example for that.

Then you will need to get the Connection Handle of this SignalR connection, to do so you will call a Server Function called StartOrRecoverSession example of the request body, { traceParent = "01-84678fd693313e41fce1333289bcf482-22d157fb94ea4827-01", } And the response will include the newConnectionHandle string, and this field will be used to Subscribe to Playfab resources.

Every Subscribe resource returns a topic, so you will need to create a message listener in the SignalR client to `ReceiveMessage`, every message you receive will have a topic, so you just need to check if it is the same from the subscribe response.

That is the summary of the flow.

2 comments
10 |1200

Up to 2 attachments (including images) can be used with a maximum of 512.0 KiB each and 1.0 MiB total.

dylan-1 avatar image dylan-1 commented ·

There's a FIFTH set of APIs for matchmaking? What is "Playfab Party Matchmaking SDK" and how is it different from Client/Matchmaking (obsolete), Matchmaker (obsolete), Multiplayer::Matchmaking (incomplete), and OSS (undocumented, solo queues only)?

It already feels unprofessional that I had to savage through 4 Matchmaking APIs over 2 different SDKs where of all these. So now I'm curious what the 3rd SDK and 5th matchmaking API does that the others do not? I wonder what limitations there will be like all the other 4 had. Deprecated? Obsolete? Missing event callbacks? Also missing documentation?

0 Likes 0 ·
dylan-1 avatar image dylan-1 commented ·

I'm just sad that the "new" Multiplayer::Matchmaking API doesn't have event callbacks when the legacy API had them. Feels low-effort to remove features and call it "v2", as if PF ran out of budget 2/3 through. "Hey guys, we forgot to add events; I mean, the legacy ones had them, shouldn't we add them to the "new v2" API?

Someone up there decided, "Ah... welp, let's just tell them to use a completely 3rd-party package that's vastly complex to setup so we save dev costs on our side".

What about docs? We have FIVE matchmaking apis now and two of them don't even work for new accounts that don't have GameMode; one of them is useless on PC since it's local matchmaking only - and the newest one doesn't even have event callbacks like the old apis had. Shouldn't we update the docs - at least... warn PF devs? It's been 2 years! Some manager decided, "Nah, they'll figure it out - we don't have the budget for 30m to add obsolete/deprecated flags or memos about this."

0 Likes 0 ·

Write an Answer

Hint: Notify or tag a user in this post by typing @username.

Up to 2 attachments (including images) can be used with a maximum of 512.0 KiB each and 1.0 MiB total.