📚 Pré-requisitos Teóricos: este projeto aplica conceitos ensinados na Especialização em Android Nativo. Recomendado revisar antes de iniciar.

🎲 P01: Guia Passo a Passo - Dados RPG (D20 3D / Animado)

v1.0 — Android Nativo, Java, Animações Interpoladas, Views XML e Efeitos Físicos

Série Prática Android Clássico — Projeto 1 de 21

• P01 (2D): Dados RPG 2D Clássico · Java · XML Views · Eventos de Toque
• ➡️ P01 (3D / este): Dados RPG 3D · RotateAnimation & Interpoladores
• P01 (Hello World): Ciclo de Vida & ViewBinding em Kotlin
• P02: Jogo da Memória com Cartas PNG & Grid

🏛️ Visão Geral & Arquitetura Visual

O projeto Dados RPG 3D / Animado evolui a mecânica básica do simulador de dados para incorporar uma experiência visual dinâmica e imersiva. Utilizando o framework de animações clássicas do Android (RotateAnimation, AccelerateDecelerateInterpolator e AnimationListener), a aplicação simula o giro tridimensional do dado com desaceleração física gradual antes de revelar a face sorteada.

📁 Estrutura de Pastas Anti-Colisão

Todo o código Android, animações em XML e recursos visuais estão organizados na subpasta canônica mobile-android-xml/:

catalogo_projetos/android_p01_dado_3d/
├── assets/
│   ├── arquitetura_dado_3d.svg
│   └── screenshot_p01.png
├── mobile-android-xml/
│   ├── app/
│   │   ├── src/
│   │   │   └── main/
│   │   │       ├── java/br/com/curso/dadosrpg3d/
│   │   │       │   └── MainActivity.java
│   │   │       ├── res/
│   │   │       │   ├── anim/
│   │   │       │   │   └── giro_dado.xml
│   │   │       │   ├── drawable/
│   │   │       │   └── layout/activity_main.xml
│   │   │       └── AndroidManifest.xml
│   │   └── build.gradle
│   ├── gradle/
│   ├── build.gradle
│   ├── gradlew
│   ├── settings.gradle
│   └── README.md
└── index.md

🧑‍💼 Engenharia de Software & Especificação Formal

1. Histórias de Usuário (User Stories)

2. Requisitos do Sistema

Requisitos Funcionais (RF)

• RF-01: Exibir ImageView com ilustração do dado D20 e botão acionador de rolagem.
• RF-02: Executar rotação completa (0 a 1080 graus) com interpolação de física clássica.
• RF-03: Sortear número aleatório entre 1 e 20 no início da rolagem, retendo o valor oculto até a desaceleração final.
• RF-04: Bloquear interações do usuário durante a execução do listener AnimationListener.onAnimationStart().
• RF-05: Revelar o resultado e reabilitar a interface no callback onAnimationEnd().

Requisitos Não-Funcionais (RNF)

• RNF-01 (Fluidez Gráfica): Taxa constante de 60 FPS durante toda a execução da animação de rotação.
• RNF-02 (Sincronismo de Thread): Todas as mutações visuais devem ser executadas obrigatoriamente na UI Thread principal do Android.
• RNF-03 (Alocação de Objetos): Reutilização de instâncias de Animation para evitar disparos frequentes do Garbage Collector.
• RNF-04 (Compatibilidade de API): Suporte estrito desde API 21 até API 34 sem dependências de bibliotecas externas pesadas.
• RNF-05 (Responsividade de Tela): Manutenção do centro do pivô do dado independente da densidade de pixels (DPI) do dispositivo.

3. Diagrama de Casos de Uso

flowchart TD
    Player([fa:fa-user Jogador de RPG])

    subgraph AppDado3D ["🎲 App Dado D20 3D (mobile-android-xml)"]
        UC01["Iniciar Rolagem Animada"]
        UC02["Interpolar Rotação com Desaceleração"]
        UC03["Bloquear Interações Simultâneas"]
        UC04["Revelar Face Final Sorteada"]
        UC05["Reabilitar Controles"]
    end

    Player --> UC01
    UC01 --> UC02
    UC01 --> UC03
    UC02 --> UC04
    UC04 --> UC05

4. Matriz de Rastreabilidade (RTM)

🛠️ Implementação Guiada (MainActivity.java)

📄 mobile-android-xml/app/src/main/java/br/com/curso/dadosrpg/MainActivity.java (arquivo real do projeto)

package br.com.curso.dadosrpg;

import android.graphics.Color;
import android.os.Bundle;
import android.os.Handler;
import android.view.animation.Animation;
import android.view.animation.RotateAnimation;
import android.widget.Button;
import android.widget.TextView;
import androidx.appcompat.app.AppCompatActivity;
import java.util.Random;

public class MainActivity extends AppCompatActivity {

    private TextView txtResultado;
    private Button btnRolar;
    private final Random gerador = new Random();
    private boolean estaRolando = false;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        txtResultado = findViewById(R.id.txt_resultado);
        btnRolar = findViewById(R.id.btn_rolar);

        btnRolar.setOnClickListener(v -> simularLancamento());
    }

    private void simularLancamento() {
        if (estaRolando) return;
        estaRolando = true;

        // Inicia a animação de rotação
        RotateAnimation anim = new RotateAnimation(0, 360, 
                Animation.RELATIVE_TO_SELF, 0.5f, 
                Animation.RELATIVE_TO_SELF, 0.5f);
        anim.setDuration(100);
        anim.setRepeatCount(10); // Gira 10 vezes rapidamente
        txtResultado.startAnimation(anim);

        // Handler para trocar os números rapidamente (efeito visual)
        Handler handler = new Handler();
        for (int i = 0; i <= 20; i++) {
            final int index = i;
            handler.postDelayed(() -> {
                if (index < 20) {
                    // Troca por um número aleatório rápido
                    txtResultado.setText(String.valueOf(gerador.nextInt(20) + 1));
                    txtResultado.setTextColor(Color.GRAY);
                } else {
                    // Resultado Final
                    exibirResultadoFinal();
                    estaRolando = false;
                }
            }, i * 50); // Troca a cada 50ms
        }
    }

    private void exibirResultadoFinal() {
        int numero = gerador.nextInt(20) + 1;
        txtResultado.setText(String.valueOf(numero));

        // Efeitos Especiais baseados no resultado
        if (numero == 20) {
            txtResultado.setTextColor(Color.parseColor("#FFD700")); // Dourado (Crítico!)
            ToastMessage("CRITICAL HIT! ⚔️");
        } else if (numero == 1) {
            txtResultado.setTextColor(Color.parseColor("#555555")); // Cinza escuro (Falha!)
            ToastMessage("CRITICAL FAIL! 💀");
        } else {
            txtResultado.setTextColor(Color.WHITE);
        }
    }
    
    private void ToastMessage(String msg) {
        android.widget.Toast.makeText(this, msg, android.widget.Toast.LENGTH_SHORT).show();
    }
}

🚀 Como Executar no Laboratório

1. Navegue até a subpasta do projeto

cd catalogo_projetos/android_p01_dado_3d/mobile-android-xml

2. Compile e execute via Gradle Wrapper

./gradlew assembleDebug
./gradlew test

[!TIP] Abra a pasta mobile-android-xml/ no Android Studio e execute em um dispositivo virtual ou físico com aceleração de hardware ativada para conferir os 60 FPS da animação.

🏁 Matriz de Checkpoints de Conclusão