Technical Design Document (TDD)

Jogo 19 - Besouro Turbo

Versão: 1.0 Data: 2026-04-03 Mercado: Brasil (Paraná - Lottopar) Arquitetura: Pool Finito + Modificador Controlado + Z-Ball Validation

1. Visão Geral

Besouro Turbo adiciona uma camada de "Modificadores Aleatórios" ao Bingo clássico. O besouro é apenas renderização visual de números já decididos pelo Pool para serem marcados gratuitamente.

2. Estrutura de Bilhete Estendida

```json { "ticket_id": "TKT-19-20260403-001", "base_prize": 100, "winning_cartela": 2,

"beetles": [ { "number": 15, "trigger_after_ball": 8 }, { "number": 42, "trigger_after_ball": 16 }, { "number": 73, "trigger_after_ball": 25 } ],

"z_ball": { "allowed": true, "cost": 80, "valid_numbers": [5, 12, 33, 27, 41] } } ```

3. Algoritmo de Marcação de Besouro

```csharp public class BeetleModifierSystem { public class BeetleMarking { public int NumberToMark; public int TriggerAfterBallIndex; public bool HasBeenTriggered; }

private List<BeetleMarking> pendingBeetles = new();
private BingoPatternDetector patternDetector;
private decimal ticketWinAmount;

public void InitializeBeetles(
    List<int> beetleNumbers,
    int[] winningCartela)
{
    // Validar que nenhum besouro cria over-win
    for (int i = 0; i < beetleNumbers.Count; i++)
    {
        int number = beetleNumbers[i];
        int triggerBall = (i + 1) * 8; // Distribuído: 8, 16, 24

        // Verificação de Constraint
        if (WouldCauseOverWin(number, winningCartela))
        {
            LogWarning($"Beetle {number} would cause over-win, skipping");
            continue;
        }

        pendingBeetles.Add(new BeetleMarking
        {
            NumberToMark = number,
            TriggerAfterBallIndex = triggerBall,
            HasBeenTriggered = false
        });
    }
}

public void OnBallDrawn(int ballIndex, int ballNumber)
{
    // Verificar se algum besouro deve ser acionado agora
    foreach (var beetle in pendingBeetles.Where(b => !b.HasBeenTriggered))
    {
        if (ballIndex >= beetle.TriggerAfterBallIndex)
        {
            TriggerBeetle(beetle, ballNumber);
            beetle.HasBeenTriggered = true;
        }
    }
}

private void TriggerBeetle(BeetleMarking beetle, int lastBallNumber)
{
    // Marcar o número nos carterias
    MarkNumberOnAllCartelas(beetle.NumberToMark);

    // Animação
    StartCoroutine(AnimateBeetleFlying(
        startPosition: GetRandomPositionOnScreen(),
        targetNumber: beetle.NumberToMark,
        duration: 2.0f));

    // Áudio
    PlayAudio("beetle_buzz.wav");
    PlayAudio("beetle_mark_ding.wav", delay: 1.5f);
}

private bool WouldCauseOverWin(int numberToMark, int[] winningCartela)
{
    // Verificação: Se marcar este número, causaria vitória não-autorizada?

    // 1. Contar quantos números do padrão-alvo já estão marcados
    int alreadyMarked = winningCartela.Count(n => IsMarked(n));

    // 2. Se adicionar este número, completa o padrão?
    bool wouldComplete = (alreadyMarked + 1) == winningCartela.Length;

    // 3. Se completa, o prêmio seria maior que autorizado?
    if (wouldComplete)
    {
        string completedPattern = DetectPattern(winningCartela);
        decimal completedPrize = GetPrizeForPattern(completedPattern);

        if (completedPrize > ticketWinAmount)
        {
            return true; // BLOQUEADO
        }
    }

    return false;
}

private void MarkNumberOnAllCartelas(int number)
{
    for (int cartelaIndex = 0; cartelaIndex < 4; cartelaIndex++)
    {
        for (int position = 0; position < 15; position++)
        {
            if (cartelaNumbers[cartelaIndex][position] == number)
            {
                marked[cartelaIndex][position] = true;
            }
        }
    }
}

} ```

4. Sistema de Bola Z (Z-Ball)

4.1 Validação de Números Selecionáveis

```csharp public class ZBallValidationEngine { private decimal ticketWinAmount; private List validSelectableNumbers = new();

public void InitializeZBall(
    int[] winningCartela,
    string targetPattern,
    decimal maxAllowedWin)
{
    // Determinar quais números são "seguros" de escolher

    foreach (int number in Enumerable.Range(1, 90))
    {
        if (winningCartela.Contains(number))
        {
            // Este número já está marcado, skip
            continue;
        }

        // Simulação: Se jogador escolher este número, qual seria o padrão?
        var simulatedCartela = (int[])winningCartela.Clone();
        Array.Add(ref simulatedCartela, number);

        string resultingPattern = DetectPatternAfterAddingNumber(
            simulatedCartela, number);

        decimal resultingPrize = GetPrizeForPattern(resultingPattern);

        // Só permitir se prêmio <= autorizado
        if (resultingPrize <= maxAllowedWin)
        {
            validSelectableNumbers.Add(number);
        }
    }
}

public List<int> GetValidSelectableNumbers()
{
    return validSelectableNumbers;
}

public bool IsNumberSelectable(int number)
{
    return validSelectableNumbers.Contains(number);
}

public void DisableInvalidNumbers(Canvas uiCanvas)
{
    // Desativar visualmente todos os números não-selecionáveis
    for (int num = 1; num <= 90; num++)
    {
        var button = uiCanvas.Find($"NumberButton_{num}");
        if (button != null)
        {
            button.interactable = IsNumberSelectable(num);

            if (!button.interactable)
            {
                button.GetComponent<Image>().color = Color.gray;
            }
        }
    }
}

} ```

4.2 Preço da Bola Z

```csharp public decimal CalculateZBallPrice(decimal prizeAtRisk) { // Desconto de 20% pois garante 100% de acerto return prizeAtRisk * 0.80m; }

// Exemplos: // Falta 1 para Bingo (R$ 500) → Z-Ball custa R$ 400 // Falta 1 para Linha (R$ 50) → Z-Ball custa R$ 40 ```

4.3 Processamento da Escolha

```csharp public class ZBallSelectionHandler { public async Task ProcessZBallSelection(int selectedNumber) { // 1. Validação (antes de renderizar) if (!validationEngine.IsNumberSelectable(selectedNumber)) { return new SelectionResult { Success = false, Reason = "INVALID_SELECTION" }; }

    // 2. Debitar custo
    await BankingService.DebitZBallCost(zBallPrice);

    // 3. Marcar número
    MarkNumberOnAllCartelas(selectedNumber);

    // 4. Detectar padrão resultante
    var resultPattern = patternDetector.CheckPattern(allDrawnBalls);

    // 5. Renderizar resultado
    if (resultPattern != null)
    {
        PlayWinAnimation(resultPattern);
        return new SelectionResult
        {
            Success = true,
            PatternDetected = resultPattern,
            Prize = GetPrizeForPattern(resultPattern)
        };
    }

    return new SelectionResult
    {
        Success = true,
        PatternDetected = null,
        Prize = 0
    };
}

}

public struct SelectionResult { public bool Success; public string Reason; // Se falhou public BingoPattern PatternDetected; public decimal Prize; } ```

5. Banco de Dados

```sql CREATE TABLE beetle_markings ( marking_id INTEGER PRIMARY KEY AUTOINCREMENT, round_id INTEGER NOT NULL,

number_marked INTEGER NOT NULL,
trigger_ball_index INTEGER,

timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,

FOREIGN KEY (round_id) REFERENCES game_rounds(round_id)

);

CREATE TABLE z_ball_transactions ( z_ball_id INTEGER PRIMARY KEY AUTOINCREMENT, round_id INTEGER NOT NULL,

cost DECIMAL(10, 2),
selected_number INTEGER,

resulting_pattern VARCHAR(50),
prize_amount DECIMAL(10, 2),

timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,

FOREIGN KEY (round_id) REFERENCES game_rounds(round_id)

); ```

6. Testes QA

Versão

v1.0 - 2026-04-03 Arquiteto: Backend - Oktop.AI Status: Pronto para Implementação

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.