[Developer Doc] Private Play & Play Style API

In Play, we’re continuing our focus on making 1:1 and group social play experiences as clear and
compelling as possible. This includes building features to better support gameplay in chat
threads, like a game list in our chat thread composers and support for Private Tournaments,
both of which will be powered by more compelling XMA layouts. For more on Private
Tournaments, please check in with your SPM for that document.

The most important thing with messaging-based play is enabling people to play socially, but
privately, rather than encouraging them to play with everyone else on Facebook.

In the game list for 1:1 threads, we’ll focus on turn-based games. In the group thread game list,
we’re starting with competitive score-based games (Private Tournaments) but expect to
expand to real-time games as well.

The games we include in these lists will depend on their retention/popularity, production
quality and how well they support private game experiences. We expect to update these lists as
we learn which games and implementations add the most value for players.

To make the experience of playing in chat threads awesome, we’d like developers to help us
make chat-based play as clear and compelling as possible. Your SPM will share more about the
best practices as they evolve, but for now we need to ensure that if your game is being
launched from a message thread, that it’s grouping the right people together and sending a
Custom Update to the thread.

Current Implementation
Launching a game from the Messenger game list automatically puts users in a context with the
other people in the thread, but the game does not know that players expect to be playing
privately. By introducing new APIs, we can help deliver on player expectations for private play.

Today, you can detect when your game is being played in Messenger
You might want to do this if you need to provide a different experience for these launch
entrypoints, but we are planning to replace this with a more nuanced API (more info to come).
1. Call FBInstant.getEntryPointAsync(). If the API returns
a. messenger_game_list then the game was launch from the game list
b. admin_message then the game was launched from an XMA

To properly store game state and show the correct players:

 1. Call FBInstant.context.getID() to get the context ID, which you can use in combination
with your own identifiers to save game state, or find the players in this context.
2. Call FBInstant.context.getPlayersAsync() to find out who else is in the context and
display the correct players in the game.
a. If the API only returns one player it’s because the other players haven’t joined or
played in the context yet.
b. In this case, when you’re trying to show the other players in the game UI you
might need to show something like “next player” “opponent” “your friend” in place
of the player(s) name, as needed.

When the player has finished their turn

1. Call FBInstant.updateAsync after the turn to drop the XMA into the thread.

Coming soon: Get more information about how players are expecting to play together.
We will be supporting different game types in different game lists and threads in the
Messenger composer. In some cases, a game only supports one gameplay mode and will do the
right thing, but some games support tournaments AND real-time AND turn-based play. We’re
adding a new API, so developers understand which gameplay experience people are expecting.

What’s changing (ETA Q4, 2023)

Games will want to fetch a new property to get full context on the desired gaming experience.
Instead of calling FBInstant.getEntryPointAsync() the game will call
FBInstant.context.getPlayStyle() to fetch the play style expectation the game was launched
with. Details below.

API Doc Example

// This function should be called after FBInstant.initializeAsync()
// resolves.

var playStyle = FBInstant.getPlayStyle();

Returns ("BASIC" | "TWOPLAYER_TURN" | "TWOPLAYER_SCORE" | "MULTIPLAYER_TURN" |

"MULTIPLAYER_SCORE" | "MULTIPLAYER_COOP" | "REALTIME") Type of the current game play
style

How to support private game experiences

By using the Play Style type, we can ensure:
[1] Games follow best practices for playing in chat threads and other private contexts. Please
talk to your SPM to learn more.

[2] Custom Updates are specific and compelling

Play Style API Response Expectation XMA

BASIC No social play expectation

on-launch. Path the player as
normal.

We will also be testing

placing Meta Avatars in
these XMAs with
animated expressions
mapped to things like
winning, losing and
waiting.

TWOPLAYER_TURN Players are expecting to take

turns and we’ll use the turn
indicator XMA above
MULTIPLAYER_SCORE Players are expecting to
compete on a private
leaderboard.

REALTIME Games that can only be played in TBD, possibly something

real-time. We are exploring ways like this:
of helping players get their group
together before launching the
game.

Not in use yet We’d love to hear if these would be useful for your game.

TWOPLAYER_SCORE Could be used where players are TBD

expecting to compete based on
scores, but with only two people.

MULTIPLAYER_TURN Could be used for an TBD

asynchronous board game.

MULTIPLAYER_COOP Could be used when players are TBD

working together to achieve a
game goal.