Cluster Wins

Evaluate wins based on connected groups of adjacent like-symbols anywhere on the board.

The Cluster class detects groups of adjacent matching symbols (clusters) and pays out when the cluster meets a minimum size threshold. Adjacency is defined as sharing the same reel or row — diagonal connections do not count.

How cluster detection works

Clusters are found using a breadth-first search (BFS) algorithm:

1. Each non-wild, unvisited position on the board is used as a seed.
2. All orthogonally adjacent positions matching the seed symbol (or wild) are recursively added to the cluster.
3. The final cluster size is compared against config.paytable to determine the payout.

Wild symbols contribute to any cluster they are adjacent to, and can simultaneously belong to clusters of different symbols.

Configuration

Because cluster sizes can range from the minimum up to the full board size, it is common to use range-based payouts instead of individual entries. The convert_range_table() method on Config generates all config.paytable entries from a compact pay_group definition:

pay_group = {
    ((min_kind, max_kind), symbol): payout,
    ...
}

config.paytable · dict · required

Maps (cluster_size, symbol) tuples to payout multipliers. Generated from pay_group via config.convert_range_table(pay_group).

pay_group = {
    ((5, 5),  "H1"): 1.0,
    ((6, 7),  "H1"): 3.0,
    ((8, 10), "H1"): 8.0,
    ((11, 25), "H1"): 25.0,
}
config.convert_range_table(pay_group)
# Generates: {(5,"H1"): 1.0, (6,"H1"): 3.0, (7,"H1"): 3.0, (8,"H1"): 8.0, ...}

Range bounds are inclusive.

Cluster.get_cluster_data()

Cluster.get_cluster_data(
    config: Config,
    board: list[list[Symbol]],
    global_multiplier: int,
    multiplier_key: str = "multiplier",
    wild_key: str = "wild",
) -> dict

Top-level entry point. Calls get_clusters() then evaluate_clusters() and returns win data.

config · Config · required

Game configuration with config.paytable populated.

board · list[list[Symbol]] · required

Active game board indexed as board[reel][row].

global_multiplier · int · required

Scalar multiplier applied to all cluster wins.

multiplier_key · str · default: "multiplier"

Symbol attribute key for reading per-symbol multiplier values.

wild_key · str · default: "wild"

Symbol attribute key identifying wild symbols.

Return value

win_data = {
    "totalWin": float,
    "wins": [
        {
            "symbol": str,
            "clusterSize": int,
            "win": float,
            "positions": [{"reel": int, "row": int}, ...],
            "meta": {
                "globalMult": int,
                "clusterMult": int,
                "winWithoutMult": float,
                "overlay": {"reel": int, "row": int},
            },
        }
    ],
}

totalWin · float

Sum of all cluster wins for this board state.

wins · list

One entry per paying cluster.

Show win entry fields

symbol · str

Name of the winning symbol.

clusterSize · int

Number of symbols in the cluster (used for paytable lookup).

win · float

Final payout: paytable[(clusterSize, symbol)] × clusterMult × globalMult.

positions · list

All positions in the cluster as {"reel": int, "row": int}.

meta · object

Show meta fields

globalMult · int

The global_multiplier passed into get_cluster_data().

clusterMult · int

Sum of multiplier attribute values from all positions in the cluster. Minimum value is 1.

winWithoutMult · float

Raw payout from config.paytable before multipliers.

overlay · object

Board position to display the win amount overlay, calculated as the position closest to the cluster’s center-of-mass: {"reel": int, "row": int}.

Exploding symbols and tumble integration

During evaluate_clusters(), every symbol in a paying cluster has its explode attribute set to True. This signals the Tumble class to remove those symbols and cascade new ones down. The typical tumble loop looks like:

# Initial evaluation
self.win_data = Cluster.get_cluster_data(
    self.config, self.board, global_multiplier=self.global_mult
)
self.win_manager.update_spinwin(self.win_data["totalWin"])

# Cascade loop
while self.win_data["totalWin"] > 0 and not self.wincap_triggered:
    self.tumble_board()
    self.win_data = Cluster.get_cluster_data(
        self.config, self.board, global_multiplier=self.global_mult
    )
    self.win_manager.update_spinwin(self.win_data["totalWin"])
    self.emit_tumble_win_events()

Lower-level methods

Cluster.get_clusters(board, wild_key)

Returns a dict mapping symbol names to lists of clusters, where each cluster is a list of (reel, row) tuples. All clusters of size ≥ 1 are returned; paytable filtering happens in evaluate_clusters().

Cluster.evaluate_clusters(config, board, clusters, global_multiplier, multiplier_key, return_data)

Determines payouts from the cluster dict, updates symbol explode flags, and populates return_data. Returns (board, return_data, total_win).

Cluster.record_cluster_wins(gamestate)

Writes force-file entries keyed by kind (cluster size), symbol, combined mult, and gametype.

Cluster pays games almost always use a cascading/tumble mechanic. Pair get_cluster_data() with tumble_board() from the Tumble class for a complete cascade loop.