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 the dedicated server, it leaves an empty team slot and an unbalanced situation.
• For large battles/large worlds, it may be hard to find enough players in a short time, so it will be nice to start the battle with a small number of players first and then continuously gather players into this battle.
• The backfilling process makes it possible to display the progress of matchmaking.

2. Key Concepts

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

2.1 Auto Backfill

Developers can enable Auto Backfill for a specific match config on the 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 cancels it or the associated battle session ends.

Caution

Please note that Backfill isn't compatible with the Acceptance feature, because it causes conflicts with the logical procedure.

2.2 Manual Backfill

Developers can manually start a backfill task on a dedicated server.

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

• Max Possible: executes the strategy of filling as many players as the ruleset requires, which is the same as Auto Backfill.
• Custom: let the game decides which team to fill the 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 a 2v2 situation. Now the battle is still unfulfilled, so backfill will try finding 2 more players, reaching 3v3, and then pause. If any player disconnects from the battle and make it 3v2, backfill will try to find 1 more player according to the equalsize rule, reach 3*, 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 starting 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's 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's fill map is like this:

{
    "red": 1
}

Backfill will not fill any player into battle, because 2v1 is illegal due to the equalize 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 the game.
• Completed: means backfill reaches the target and stopped, which only happens when using the Custom strategy.
• Error: means backfill is terminated due to system failure, submit a bug to us when this happens :)

Backfill starts with the 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 the Searching state, if backfill successfully fills players into a battle session, it can transfer to Paused, Completed, or still Searching state, depending on the strategy it uses 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 request 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 sessionIDd. We use the battle session ID to identify the backfill request running on the battle session.

  • Backfill strategy. The player's 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 the 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 the player know he is matched via backfill?

No, a player won't know whether he/she is matchmaked via normal matchmaking or backfill. But developers can determine that using the 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 a timeout design.

5.4 How to choose a backfill strategy?

It depends on the game type and battle scenario.

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

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

Max Possible strategy is also suitable for large-world games that per dedicated server holds up to thousands of players. So new players will tend to be matched to existing battles instead of creating 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, matchmakers 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 is both restricted by the ruleset. An illegal result won't be output.

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 statistically, 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.