Backfill (beta)

Normally once a battle session is created, its associated matchmaking progress stops. To continue matching players into active battles, backfill is introduced, which includes auto backfill and manual backfill, each corresponding to specific use cases.

The backfill feature is on beta stage and may not work perfectly on specific rulesets. Please contact us if backfill works not as expected on your use case.

1. Overview

Backfill enables developers to continue matching players after a battle has started. It is useful in such cases:

• When any player loses connection to dedicated server, leaving an empty team slot and unbalanced situation.
• For large battles/large worlds it may be hard to find enough players in short time, so it will be nice to start battle with small amount of players first and then continuously gather players into this battle.
• The backfilling process makes it possible to display progress of matchmaking.

2. Key Concepts

Backfill feature is provided in two forms: Auto Backfill and Manual Backfill.

2.1 Auto Backfill

Developers can enable Auto Backfill for specific match config on Web Portal.

When Auto Backfill is enabled, every battle session will be created with a backfill task. The backfill task will always try to append players for the associated battle session as long as it's not fullfilled. If one or more players disconnect from battle session, the backfill will also try to fill the empty slots of them.

Generally, Auto Backfill executes the strategy of filling as many players as the ruleset requires.

Tip

Auto Backfill differs from Auto Continue. The latter belongs the Acceptance feature, which will transfer the tickets of accepted players back to Searching stage instead of Terminated when someone rejected matchmaking result.

Auto Continue happens after the matchmaking result is waiting for players to accept it and before the battle session is created.

Auto Backfill happens after the battle session is created and will only stop when the dedicated server explicitly cancel it or the associated battle session ended.

Caution

Please note that Backfill isn't compatible with the Acceptance feature, because they cause conflicts on logical procedure.

2.2 Manual Backfill

Developers can manually start a backfill task on dedicated server.

When using Manual Backfill, two strategies are available to choose:

• Max Possible: executes the strategy of filling as many players as the ruleset requires, which is the same as Auto Backfill.
• Custom: let game decides which team to fill specified number of players, which should also satisfy the ruleset.

For example:

{
    "version": "v1.0",
    "playerAttributes": [],
    "teams": [
        {
            "name": "red",
            "minPlayers": 1,
            "maxPlayers": 3,
            "minQuantity": 1,
            "maxQuantity": 1
        },
        {
            "name": "blue",
            "minPlayers": 1,
            "maxPlayers": 3,
            "minQuantity": 1,
            "maxQuantity": 1
        }
    ],
    "rules": [
        {
            "name": "equalsize",
            "type": "comparisonRule",
            "description": "",
            "measurements": [
                "count(teams[*].players)"
            ],
            "operation": "="
        }
    ],
    "expansions": []
}

For the ruleset above, the battle starts with at minimum of 2 players: 1 for team red and 1 for team blue.

If the Max Possible strategy is applied, according to the equalsize rule, backfill will fill 2 more players: 1 for team red and 1 for team blue, reaching 2v2 situation. Now the battle is still un-fullfilled, so backfill will try finding 2 more players, reaching 3v3 and pause. If any player disconnects from the battle and make it 3v2, backfill will try to find 1 more player according to equalsize rule, reaches 3v3 and then pause again.

---

If the Custom strategy is applied, the game should decide the team fill map. Let's take the 1v1 as the start point too.

If the team fill map is like this:

{
    "red": 1,
    "blue": 1
}

Backfill will fill 2 more players, reach 2v2 and then stop. It means that backfill has completed the target and will not resume.

If the team fill map is like this:

{
    "red": 2,
    "blue": 2
}

Backfill will have the same effect of using Max Possible strategy, reach 2v2 and then 3v3 and then stops.

But, if the team fill map is like this:

{
    "red": 1
}

Backfill will not fill any player into battle, because 2v1 is illegal to the equalsize rule.

3. Key Process

Backfill has the following statuses:

• Searching: means backfill is searching players.
• Paused: means backfill is suspended, normally because the battle is full.
• Canceled: means backfill is canceled by game.
• Completed: means backfill reaches target and stopped, which only happens when using Custom strategy.
• Error: means backfill is terminated due to system failure, submit bug to us when this happened :)

Backfill starts with Searching or Paused state, depending on whether the battle session is full or not.

For Paused state, if any player disconnects from battle session, the backfill will immediately transfers to Searching state.

For Searching state, if backfill successfully filled players into battle session, it can transfer to Paused, Completed or still Searching state, depending on the strategy it use and the target it tries to reach.

4. Integration Steps

4.1 Turn on Automatic Backfill on Demand

Switch on the Auto Backfill option on match configuration if you want PGOS to automatically create a backfill request after the battle session is created.

4.2 Manage Backfill Request from Game Server

You can start or cancel a backfill requests directly from the game server that is hosting the battle session using these APIs:

• StartBackfill. start a new backfill request. Multiple backfills cannot be initiated at the same time in a battle session, and a backfill must be terminated before it can be initiated again. The following parameters can be specified when initiating a backfill:

  • Battle session id. We use the battle session id to identify the backfill request running on the battle session.

  • Backfill strategy. The player filling strategy when backfilling, the enumeration is as follows:

    • Custom. In this mode, the target player count of each team needs to be specified. However, the number of players per team must comply with the ruleset constraint.
    • MaxPossible. Backfill matchmaking will target max players as defined in ruleset and ignore expansions on player count.

  • Custom team map. The target player count of each team. This data needs to be populated when selecting the custom strategy to tell PGOS that when to stop backfilling.

• CancelBackfill. terminate the backfill request running on a battle session.

4.3 Track the Backfill Request

Game server will be notified of backfill status changes and progress changes by callbacks, add processing code to the OnBattleSessionUpdated event in Hosting module to receive and handle backfill process data.

5. Common FAQ

5.1 Will player know he is matchmaked via backfill?

No, a player won't know whether he/she is matchmaked via normal matchmaking or backfill. But developers can determine that using Web Portal.

For players matchmaked via backfill, there will be a small "Backfill" mark on right side of Battle Sesion ID of ticket log, shown as below.

5.2 Will backfill stop when the battle is full?

It depends on the strategy used to start backfill.

If Max Possible is used, when it reaches the top player count limit that ruleset restricts, backfill will pause. And if any player disconnects from battle, backfill will resume, trying to fill the empty slots. Developers can manually cancel backfill at any time if backfill is considered should be stopped.

If Custom is used, backfill will only tries to complete the target that developer sets. So backfill will stop when player count reaches custom team map.

5.3 Will backfill timeout?

No, backfill currently doesn't have timeout design.

5.4 How to choose backfill strategy?

It depends on the game type and battle scenario.

Custom strategy is suitable to battles that only need small amount of teams. When any player got disconnected and unbalanced situation is bad for experience, then using Custom strategy to backfill another player seems good choice.

Max Possible strategy is suitable to games in need of very fast matchmaking speed. Using Max Possible, a battle will start with the minimum amount of players required by ruleset, then continuously backfill more players to the battle until full.

Max Possible strategy is also suitable to large-world games that per dedicated server holds up to thousands of players. So new players will tend to be matchmaked to existing battles instead of create new ones.

5.5 What to expect, new battle or backfill?

This question also comes to us since the development stage of backfill. When new players start matchmaking, should we expect a new battle session, or just backfill them into existing one?

To answer this question, the following things need to be introduced first.

• The backfill feature doesn't block the creation of new battle sessions.
• Internally, matchmaker consider backfill first, and then normal matchmaking, and then loops. Which is to say, backfill and normal matchmaking run alternatively.
• The result of backfill and normal matchmaking are both restricted by ruleset. Illegal result won't be outputed.

So although matchmaker tends to backfill more often than normal matchmaking, it is still not guaranteed that backfill always happends.

If we look at this question in statistics way, both new battle and backfill are possible.

Tip

If the game developer wants to match players who started matchmaking within a short period of time into the same battle, the expansion feature is a better choice than backfill. For the example ruleset, please refer to this ruleset example.