OSS: Examples? Best practices? Matchmaking events?

Question

question

dylan-1 asked Feb 2, '23

OSS: Examples? Best practices? Matchmaking events?

I'm struggling to find examples outside "You can use this OSS sdk!" for matchmaking events (my main focus) and other socket-based events. I saw the doc how to install the plugin, but then:

We're sort of just given a big, commentless repo much like "here you go, gl". No inline docs - no direction - no entry point - no init advice - no examples - no matchmaking docs - no event handling examples - no best practice advice - really, nothing at all but commentless code.

Found these that were only helpful to grab the plugin:

https://learn.microsoft.com/en-us/gaming/playfab/features/multiplayer/lobby/lobby-matchmaking-sdks/lobby-matchmaking-sdks
https://learn.microsoft.com/en-us/gaming/playfab/features/multiplayer/networking/party-unreal-engine-oss-quickstart
The repo README, that again, just really pointed to the above link(s).

There must be some sort of docs that someone forgot to link -- can anyone point me some direction? Thanks!

(PS, @staff -- no inline docs at all? Come on, mates; this is very non-standard)

sdks unreal multiplayer documentation

1

10 |1200

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

dylan-1 commented · Feb 02, 2023 at 05:47 AM

I found this buried doc:

https://learn.microsoft.com/en-us/gaming/playfab/features/multiplayer/matchmaking/quickstart-client-sdk

However, the examples are raw C++ (which is a strange choice, opposed to Unreal's C++), doesn't use the OSS SDK (that I'm going to assume operates differently), and almost all of the func names are renamed/obsolete. Since there are no namespaces shown, I have to just rummage through code to manually find the latest n greatest.

For example, PFMultiplayerInitialize (no namespace hint) is FOnlineSubsystemPlayFab::Init() in the actual SDK

Decrypting from raw [non-Unrealified] C++, using no namespaces, dated func names, low-effort examples and 0 inline docs equal an unnecessarily-difficult learning curve of trial+error.

Are there are updated docs that exist?

0 ·

Answer 1 · 2023-02-02T10:00:31Z

Gosen Gao answered Feb 2, '23

Before using the PlayFab Online Subsystem (PF OSS), please note that "It is currently designed for use when developing PC, Xbox, Steam, Nintendo Switch, PlayStation®5 and PlayStation®4 games. This subsystem layer works seamlessly on top of the existing Epic provided base Online Subsystem (OSS) GDK. PlayFab OSS compliments the base OSS by adding support for PlayFab Lobby, Matchmaking, Party networking and Voice over Internet Protocol (VOIP)." For more details, see https://learn.microsoft.com/en-us/gaming/playfab/features/multiplayer/networking/party-unreal-engine-oss-overview .

Currently, PF OSS supports the following platforms:

Xbox Series X GDK
PC GDK
Xbox One GDK
PC Steam
Nintendo Switch
PS5™ and PS4™

For other platforms, PF OSS can't be used. Once you've enabled PF OSS, it can be used just the same as other Online Subsystems in UE. Epic's OnlineSubsystem is already documented here: https://docs.unrealengine.com/5.0/en-US/online-subsystem-session-interface-in-unreal-engine/.

The reason for having minimum documentation for using the PlayFab OSS is because the Session interface docs which Epic provides should be sufficient and it can get quickly outdated for newer versions of OSS interface when Epic updates them.

The more detailed list of interfaces are available here: https://docs.unrealengine.com/5.1/en-US/API/Plugins/OnlineSubsystem/Interfaces/IOnlineSession/.

If you are not trying to use the C++ multiplayer SDK instead if you only use the OnlineSubsystem's Session interface, then you don't actually need to track the ticket status, the OSS encapsulates all the logic because the OnlineSubsystem's interface does not provide any mechanism to provide updates except success or failure.

The best way to understand the usage is to download and inspect Epic's shooter game sample.

1

10 |1200

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

dylan-1 commented · Feb 02, 2023 at 12:15 PM

While this is a comment and not answer, I am disappointed you could not clarify even a single point - I have a strong feeling that no staff at PF actually knows the answer to these questions.

Respectfully, why even make new SDKs if no one is going to spend a fraction of your budget on some document how the heck to even use it or properly maintain it? Anyone can dump a repo of commentless code with no docs and desync'd updates. You guys are Microsoft Azure now -- an enterprise, AAA product: there's no budget or care for this?

I understand there are a ton of cogs moving, but so many docs have just been stale for years now; no staff seems to care about the impact it has on your clients. Even your matchmaking modules are obsolete -- and you have 4 matchmaking modules (client/matchmaking, matchmaker, multiplayer/matchmaking, oss/matchmaking) and 2 of them are completely broken (due to GameMode) -- who knows how many others are also broken. Since your Unreal quickstart guide only demoes the deprecated Client/ API, you set your Unreal users off to bad practices from the very beginning due to stale docs.

0 ·

Answer 2 · 2023-02-03T03:03:56Z

dylan-1 answered Feb 3, '23

Sadly, it seems like the answer is that... there is no further docs (not even inline). There are only examples to install the plugin, then we're left with a commentless repo dump we have to figure out for ourselves through trial+error.

Unexpected and unfortunate that PF would release an SDK years ago and never document it, leaving their PF users burdened to figure it out for themselves only from tedious efforts :/

10 |1200

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

Answer 3 · 2023-02-09T06:33:43Z

dylan-1 answered Feb 9, '23

Updated answer:

Figured it out with some deep research and help from PF staff in Discord: The marketplace plugin multiplayer::matchmaking API is 100% incompatible; and the OSS one supports local (solo queue or console partner) multiplayer ONLY while the Client::Multiplayer is OBSOLETE (not just deprecated - broken due to GameMode). The answer is... USE NEITHER of these. There are 5 matchmaking APIs and almost all the docs are desync'd.

The unfortunate answer is: Ditch OSS and use marketplace sdk Multiplayer::Matchmaking API ONLY. Yes, the old API had event callbacks; the new API is pretty low-effort/beta-like and requires you to poll (+$$/effort).

The matchmaking docs suggest you implement the marketplace sdk then add OSS for event callbacks to prevent polling, but this is actually (once again) a stale doc that's incorrect:

https://discord.com/channels/684463257276121192/803421812352090112/1072941704744796320

The marketplace sdk and the OSS sdk have 0 interactions together; callbacks won't work. Even if you implement OSS, the big caveat no one seems to tell you is that it's for local matchmaking (solo queue) only! If you plan to have premades, OSS will not work for you, from what I can tell.

Stick with the marketplace SDK and poll with the Multiplayer::Matchmaking API.

(!) To clarify further: Client/Matchmaking API is obsolete/broken (since there is no GameMode, so it will never work on newer accounts). The docs don't tell you this.

(!) To clarify further: Matchmaker API is obsolete/broken (since there is no GameMode, so it will never work on newer accounts). The docs don't tell you this.

(!) To clarify further: The entire Client/ API is deprecated ("v1"), even though the Unreal quickstart starts you here (at immediately-deprecated APIs). The docs don't tell you this.

[There are a few related posts I'm going to copy+paste this to; hope that's ok -- clarifies so much]

10 |1200

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

question