Bloco da Sorte — Technical Design Document (TDD)

Versão: 1.0 Data: 2026-04-03 Arquitetura: Cluster Pays Engine com Flood Fill Algorithm Plataforma: Lottopar (PR Regulation)

1. Visão Geral Técnica

Bloco da Sorte implementa mecânica Cluster Pays em grade 7x7. A complexidade computacional está na detecção de clusters (Flood Fill) e na construção reversa (Reverse Builder) para entregar um prêmio específico.

Stack Recomendado: - Front-end: Unity WebGL ou HTML5/Pixi.js - Back-end: C# .NET Core ou Node.js - DB: PostgreSQL + Redis cache

2. Flood Fill Algorithm (Core)

2.1 Implementação Python

```python class ClusterGrid: def init(self, grid): self.grid = grid # 7x7 self.visited = [[False] * 7 for _ in range(7)]

def find_all_clusters(self):
    """Encontra todos clusters >= 5"""
    clusters = []

    for row in range(7):
        for col in range(7):
            if not self.visited[row][col] and self.grid[row][col] not in [EMPTY, SCATTER]:
                cluster = self.flood_fill(row, col)
                if len(cluster) >= 5:
                    symbol_id = self.grid[row][col]
                    clusters.append({
                        "symbol": symbol_id,
                        "cells": cluster,
                        "size": len(cluster)
                    })

    return clusters

def flood_fill(self, start_row, start_col):
    """Flood Fill recursivo"""
    stack = [(start_row, start_col)]
    cluster = []
    symbol = self.grid[start_row][start_col]

    while stack:
        row, col = stack.pop()

        if row < 0 or row >= 7 or col < 0 or col >= 7:
            continue
        if self.visited[row][col]:
            continue
        if self.grid[row][col] != symbol:
            continue

        self.visited[row][col] = True
        cluster.append((row, col))

        # 4 vizinhos (não diagonal)
        stack.extend([
            (row-1, col), (row+1, col),
            (row, col-1), (row, col+1)
        ])

    return cluster

def calculate_payout(self, clusters):
    """Calcula ganho total"""
    total = 0
    for cluster in clusters:
        symbol = cluster['symbol']
        size = cluster['size']

        # Lookup paytable
        payout = PAYTABLE[symbol].get(size, 0)
        total += payout

    return total

```

2.2 Complexidade

• Tempo: O(49) = O(1) pois grid é 7x7
• Espaço: O(49) para visited matrix
• Real Performance: <1ms por frame

3. Reverse Cluster Builder (Pool Finito)

3.1 Algoritmo de Construção

```python def build_winning_grid(target_prize, rtp_curve): """ Dado um prêmio, constrói uma grade que pague exatamente isso """

# Passo 1: Decompor prêmio
components = decompose_prize_into_components(target_prize)
# Exemplo retorno:
# [
#   {"symbol": "PANDEIRO", "size": 7, "payout": 35},
#   {"symbol": "REI_MOMO", "size": 5, "payout": 100}
# ]

# Passo 2: Inicializar grade vazia
grid = [[EMPTY] * 7 for _ in range(7)]

# Passo 3: Plantar clusters vencedores
occupied = set()  # Rastreia posições já usadas

for component in components:
    # Escolher posição aleatória para este cluster
    start_row, start_col = find_free_position(occupied)

    # Plantar cluster organicamente
    cluster_cells = grow_cluster_organic(
        grid, start_row, start_col,
        component['symbol'], component['size']
    )

    occupied.update(cluster_cells)

# Passo 4: Preencher resto com bloqueadores
fill_with_blockers(grid, occupied)

# Passo 5: Validar nenhuma vitória acidental
clusters = find_all_clusters(grid)
calculated_payout = calculate_payout(clusters)

assert abs(calculated_payout - target_prize) < 0.01, \
    f"Prize mismatch: {calculated_payout} vs {target_prize}"

return grid

def grow_cluster_organic(grid, start_row, start_col, symbol, target_size): """ Crescer cluster de forma orgânica (tetris shapes) não apenas quadrados """ cluster = [(start_row, start_col)] grid[start_row][start_col] = symbol

attempts = 0
while len(cluster) < target_size and attempts < 100:
    # Selecionar célula de bordo aleatória
    edge_cell = random.choice(cluster)
    row, col = edge_cell

    # Expandir em 1 direção aleatória
    directions = [(-1, 0), (1, 0), (0, -1), (0, 1)]
    random.shuffle(directions)

    for dr, dc in directions:
        new_row, new_col = row + dr, col + dc

        # Validar espaço livre
        if (0 <= new_row < 7 and 0 <= new_col < 7 and
            grid[new_row][new_col] == EMPTY):

            grid[new_row][new_col] = symbol
            cluster.append((new_row, new_col))
            break

    attempts += 1

return cluster

def fill_with_blockers(grid, occupied): """ Preencher células vazias com padrão checkerboard que previne conexões acidentais """ for row in range(7): for col in range(7): if (row, col) not in occupied and grid[row][col] == EMPTY: # Alternar A, B para evitar conexões symbol = BLOCKER_A if (row + col) % 2 == 0 else BLOCKER_B grid[row][col] = symbol ```

3.2 Decomposição de Prêmio

```python def decompose_prize_into_components(target_prize): """ Quebra prêmio em componentes de cluster realizáveis """ components = [] remaining = target_prize

# Estratégia: usar símbolos premium primeiro
symbols_by_value = sorted(PAYTABLE.items(),
                         key=lambda x: x[1]['max_payout'],
                         reverse=True)

for symbol, payouts in symbols_by_value:
    if remaining <= 0.01:
        break

    # Encontrar tamanho de cluster que cabe neste remaining
    for size in range(15, 4, -1):  # 15, 14, 13...5
        payout = payouts.get(size, 0)

        if payout <= remaining:
            components.append({
                "symbol": symbol,
                "size": size,
                "payout": payout
            })
            remaining -= payout
            break

return components

```

4. Cascade Processing

4.1 Loop de Cascata

```python class CascadeProcessor: def init(self, grid, phantom_buffer): self.grid = grid # 7x7 viewport self.phantom = phantom_buffer # 7x14 self.cascades = []

def process_cascades(self):
    """Processa todas as cascatas até não haver mais vitórias"""
    cascade_num = 0

    while True:
        cascade_num += 1

        # 1. Detectar clusters
        clusters = self.find_all_clusters()

        if not clusters:
            break  # Sem mais vitórias

        # 2. Registrar cascata
        cascade_data = {
            "num": cascade_num,
            "clusters": clusters,
            "payout": sum(c['payout'] for c in clusters)
        }
        self.cascades.append(cascade_data)

        # 3. Remover símbolos
        self.remove_winning_symbols(clusters)

        # 4. Aplicar gravidade (queda)
        self.apply_gravity()

        # 5. Repor do buffer
        self.replenish_from_phantom()

    return self.cascades

def remove_winning_symbols(self, clusters):
    """Remove símbolos vencedores"""
    for cluster in clusters:
        for row, col in cluster['cells']:
            self.grid[row][col] = EMPTY

def apply_gravity(self):
    """Símbolos caem"""
    for col in range(7):
        # Compactar coluna
        symbols = [self.grid[row][col] for row in range(7)
                  if self.grid[row][col] != EMPTY]

        # Preencher com vazios no topo
        for row in range(7 - len(symbols)):
            self.grid[row][col] = EMPTY

        # Preencher com símbolos embaixo
        for i, sym in enumerate(symbols):
            self.grid[7 - len(symbols) + i][col] = sym

def replenish_from_phantom(self):
    """Puxa símbolos do phantom buffer"""
    for col in range(7):
        # Contar vazios no topo da coluna
        empty_count = 0
        for row in range(7):
            if self.grid[row][col] != EMPTY:
                break
            empty_count += 1

        # Puxa do phantom (bottom to top)
        for i in range(empty_count):
            symbol = self.phantom[13 - i][col]
            self.grid[i][col] = symbol

        # Scroll phantom
        self.phantom.pop()  # Remove última linha
        # Adicionar nova linha (será populada em próxima cascata)
        new_row = [RANDOM_NON_WINNING() for _ in range(7)]
        self.phantom.insert(0, new_row)

```

5. Phantom Buffer Management

5.1 Pre-computation do Buffer

```python def build_phantom_for_cascades(target_prize, expected_cascades=3): """ Pré-constrói phantom buffer para garantir cascatas renderizam o prêmio correto """ phantom = [[EMPTY] * 7 for _ in range(14)] remaining = target_prize

for cascade_idx in range(expected_cascades):
    prize_per_cascade = remaining / (expected_cascades - cascade_idx)

    # Gerar símbolos que renderizam este prêmio
    symbols = generate_symbols_for_prize(prize_per_cascade)

    # Preencher linha do phantom
    for col in range(7):
        phantom[cascade_idx][col] = symbols[col]

    remaining -= prize_per_cascade

# Preencher resto com lixo
for row in range(expected_cascades, 14):
    for col in range(7):
        phantom[row][col] = random_non_winning_symbol()

return phantom

```

5.2 Buffer Lifecycle

``` Inicial (14 linhas): [P0] ← Próxima a cair [P1] ... [P13]

Após 1ª cascata (1 linha usada): [P1] [P2] ... [P13] [NEW] ← Nova linha gerada aleatoriamente

Após 2ª cascata: [P2] ... [NEW1] [NEW2] ```

6. Paytable Implementation

6.1 Estrutura de Dados

```python PAYTABLE = { "REI_MOMO": { 5: 20, # 5 símbolos = 20% da aposta 6: 20, 7: 50, 8: 50, 9: 100, 10: 100, 11: 250, 12: 250, 13: 250, 14: 250, 15: 500 # 15+ = 500% }, "RAINHA": { 5: 15, 6: 15, 7: 25, # ... 15: 200 }, "PANDEIRO": { 5: 5, 6: 5, 7: 8, # ... 15: 50 }, # ... resto dos símbolos }

def calculate_payout(symbol, size): """Lookup seguro com fallback""" if size >= 15: size = 15 # Max cap

return PAYTABLE.get(symbol, {}).get(size, 0)

```

7. Feature Buy Integration (Optional)

7.1 Fluxo

```python def trigger_feature_buy_bonus(feature_buy_cost, num_spins=10): """ Feature Buy = aposta de alta denominação que força entrada em bônus """

# 1. Débito
player_balance -= feature_buy_cost

# 2. Enviar para Lottopar como aposta normal
response = lottopar_server.place_bet({
    "game_id": "BLOCO_DA_SORTE",
    "amount": feature_buy_cost
})

prize = response['prize']  # Ex: R$ 450

# 3. Construir script de bônus
bonus_script = build_bonus_script(prize, num_spins)

# 4. Executar bônus
for spin_data in bonus_script:
    render_spin(spin_data)

return sum(spin['final_win'] for spin in bonus_script)

```

8. JSON Payload Structure

8.1 Spin Response

json { "spin_id": "CARNAVAL_001", "grid": [ ["PANDEIRO", "PANDEIRO", "BLOCKER_A", "REI_MOMO", "REI_MOMO", "BLOCKER_B", "BLOCKER_A"], ["RAINHA", "BLOCKER_B", "RAINHA", "REI_MOMO", "BLOCKER_A", "BLOCKER_B", "RAINHA"], ... ], "winning_clusters": [ { "symbol": "PANDEIRO", "size": 8, "cells": [[0,0], [0,1], [1,0], [1,1], [2,0], [2,1], [3,0], [3,1]], "payout": 40 } ], "cascades": [ { "cascade_num": 1, "removed_cells": [[0,0], [0,1], ...], "new_symbols": [["RAINHA", "BLOCKER_A", ...]], "clusters_this_cascade": [{"symbol": "RAINHA", "size": 6, "payout": 30}] } ], "total_win": 70, "bonus_triggered": false }

8.2 Bonus Response

json { "bonus_id": "BONUS_2026040312", "num_spins": 10, "spins": [ { "spin_num": 1, "grid": [...], "clusters": [...], "cascades": [...], "bombs": [{"pos": [1,2], "multiplier": 10}], "spin_win": 50, "total_multiplier": 10, "spin_total": 500 }, ... ], "total_bonus_win": 3500 }

9. RTP Validation

9.1 Math Testing

```python def validate_rtp(num_spins=50000, target_rtp=0.94): """Testa se RTP observado bate com esperado""" total_in = 0 total_out = 0

for _ in range(num_spins):
    spin = run_spin()
    total_in += spin['bet']
    total_out += spin['payout']

observed_rtp = total_out / total_in
deviation = abs(observed_rtp - target_rtp)

assert deviation < 0.02, \
    f"RTP Deviation: {deviation*100:.2f}%"

print(f"✓ RTP Test: {observed_rtp:.4f}")

```

10. Hardware & Performance

10.1 Mobile Optimization

```csharp // Object Pooling para símbolos public class SymbolPool { private Queue pool = new Queue();

public Symbol Get() => pool.Count > 0 ?
    pool.Dequeue() : new Symbol();

public void Return(Symbol sym) => pool.Enqueue(sym);

}

// Usar Sprite Atlas Texture2D atlas = Resources.Load("sprites/carnival_atlas"); // Evita múltiplas draw calls

// Desabilitar partículas em Low-End if (SystemInfo.systemMemorySize < 2048) { particleSystem.enabled = false; } ```

11. SAS 6.02 Protocol Integration

Eventos reportados: - Machine Cash In/Out - Game Round Results - Bonus Triggered - Feature Buy - Meters Update

12. Debugging Tools

```python

Debug mode: CMD + SHIFT + D

Permite clicar na grade para alterar símbolos

Testa detecção de clusters sem depender da sorte

if DEBUG_MODE: # Visualizar Flood Fill em tempo real draw_flood_fill_visualization()

# Inspector para reel strips
show_reel_inspector()

```

Conclusão

Bloco da Sorte é computacionalmente simples (Flood Fill O(1)) mas exige integração cuidadosa com Pool Finito. O Reverse Cluster Builder é a chave para entregar prêmios precisos.

Data: 2026-04-03 Status: Pronto para Desenvolvimento

Prompts de Geração de Arte IA

Clique em qualquer prompt para copiar. Os prompts abaixo são otimizados para Midjourney v6, DALL-E 3, e Stable Diffusion.