Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/StakeEngine/math-sdk/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us