sevenx_engine 0.2.11

# 🤖 SevenX Engine - Guia Completo Android


## 📱 Visão Geral


A SevenX Engine oferece suporte completo para Android com recursos nativos:

- ✅ **Touch Multi-touch** - Suporte completo para múltiplos toques
- ✅ **Gestos Avançados** - Tap, Double Tap, Long Press, Swipe, Pinch, Rotate
- ✅ **Sensores** - Acelerômetro e Giroscópio
- ✅ **Vibração** - Feedback háptico com intensidade variável
- ✅ **Joystick Virtual** - Controles touch customizáveis
- ✅ **Bateria** - Monitoramento e otimização automática
- ✅ **Orientação** - Suporte para Portrait e Landscape
- ✅ **Notificações** - Sistema de notificações locais
- ✅ **Conectividade** - Detecção de WiFi/Mobile
- ✅ **Armazenamento** - Persistência de dados
- ✅ **Permissões** - Gerenciamento de permissões Android
- ✅ **Teclado Virtual** - Controle do teclado on-screen

## 🚀 Quick Start


### 1. Configuração do Ambiente


```powershell
# Execute o script de configuração

.\build-android-complete.ps1
```

O script irá:
- Instalar `cargo-apk` se necessário
- Adicionar targets Android (ARM64 e ARMv7)
- Verificar configuração do NDK
- Buildar seus exemplos

### 2. Primeiro Exemplo Android


```rust
use sevenx_engine::{Engine, EngineConfig, GameState};

#[cfg(target_os = "android")]

use sevenx_engine::android::AdvancedAndroidManager;

struct MyAndroidGame {
    #[cfg(target_os = "android")]
    android: AdvancedAndroidManager,
}

impl GameState for MyAndroidGame {
    fn new() -> Self {
        #[cfg(target_os = "android")]
        {
            let mut android = AdvancedAndroidManager::new();
            
            // Cria joystick virtual
            android.input.create_virtual_joystick(100.0, 450.0, 50.0);
            
            Self { android }
        }
        
        #[cfg(not(target_os = "android"))]
        {
            Self {}
        }
    }

    fn update(&mut self, dt: f32, _input: &InputHandler, _world: &mut World) {
        #[cfg(target_os = "android")]
        {
            self.android.update();
            
            // Processa toques
            let touches = self.android.input.get_touches();
            for touch in touches {
                println!("Touch: {}, {} (pressure: {})", 
                    touch.x, touch.y, touch.pressure);
            }
        }
    }

    fn draw(&mut self, _world: &World, pixels: &mut [u8]) {
        // Seu código de renderização
    }
}

fn main() {
    let config = EngineConfig::new()
        .with_title("My Android Game")
        .with_size(800, 600);
    
    Engine::with_config(config).run::<MyAndroidGame>();
}
```

### 3. Build e Instalação


```powershell
# Build para ARM64 (recomendado)

cargo apk build --example my_game --target aarch64-linux-android --release

# Instalar no dispositivo

adb install target\aarch64-linux-android\release\examples\my_game.apk

# Ou build + run direto

cargo apk run --example my_game --target aarch64-linux-android
```

## 📚 Recursos Detalhados


### Touch e Multi-touch


```rust
// Obter todos os toques ativos
let touches = android.input.get_touches();

// Verificar toque em área específica
if android.input.is_touch_in_area(100.0, 100.0, 200.0, 50.0) {
    println!("Botão tocado!");
}

// Número de toques
let count = android.input.touch_count();
```

### Gestos Avançados


```rust
// Atualizar reconhecedor de gestos
android.gestures.update(&touches);

// Processar gestos detectados
for gesture in android.gestures.get_gestures() {
    match gesture.gesture_type {
        GestureType::Tap => {
            println!("Tap em: {}, {}", gesture.position.0, gesture.position.1);
        }
        GestureType::DoubleTap => {
            println!("Double tap!");
        }
        GestureType::LongPress => {
            println!("Long press!");
        }
        GestureType::Swipe(direction) => {
            match direction {
                SwipeDirection::Up => println!("Swipe para cima"),
                SwipeDirection::Down => println!("Swipe para baixo"),
                SwipeDirection::Left => println!("Swipe para esquerda"),
                SwipeDirection::Right => println!("Swipe para direita"),
            }
        }
        GestureType::Pinch(pinch_type) => {
            println!("Pinch: {:?}, scale: {}", pinch_type, gesture.scale);
        }
        GestureType::Rotate => {
            println!("Rotação: {} radianos", gesture.angle);
        }
    }
}

// Verificar gesto específico
if android.gestures.has_gesture(GestureType::Tap) {
    println!("Tap detectado!");
}
```

### Joystick Virtual


```rust
// Criar joystick
android.input.create_virtual_joystick(100.0, 450.0, 50.0);

// Obter eixos (-1.0 a 1.0)
let (axis_x, axis_y) = android.input.get_virtual_joystick_axis();

// Mover personagem
player.x += axis_x * speed * dt;
player.y += axis_y * speed * dt;
```

### Sensores


```rust
// Acelerômetro (m/s²)
let accel = android.input.get_accelerometer();
println!("Aceleração: {}, {}, {}", accel.x, accel.y, accel.z);

// Detectar sacudida
if accel.x.abs() > 15.0 || accel.y.abs() > 15.0 {
    println!("Dispositivo sacudido!");
}

// Giroscópio (rad/s)
let gyro = android.input.get_gyroscope();
println!("Rotação: {}, {}, {}", gyro.x, gyro.y, gyro.z);

// Controle por inclinação
player.x += accel.x * sensitivity * dt;
```

### Vibração


```rust
// Vibração simples (milissegundos)
android.vibration.vibrate(100);

// Vibração com intensidade
use sevenx_engine::android::VibrationIntensity;

android.vibration.vibrate_with_intensity(50, VibrationIntensity::Light);
android.vibration.vibrate_with_intensity(100, VibrationIntensity::Medium);
android.vibration.vibrate_with_intensity(200, VibrationIntensity::Heavy);

// Padrão customizado
use sevenx_engine::android::VibrationPattern;

let pattern = VibrationPattern {
    durations: vec![0, 100, 50, 100], // espera, vibra, espera, vibra
    repeat: false,
};
android.vibration.vibrate_pattern(pattern);

// Cancelar vibração
android.vibration.cancel();

// Habilitar/desabilitar
android.vibration.set_enabled(false);
```

### Bateria e Performance


```rust
// Informações da bateria
if let Some(battery) = android.input.get_battery() {
    println!("Nível: {:.0}%", battery.level * 100.0);
    println!("Carregando: {}", battery.is_charging);
    println!("Temperatura: {:.1}°C", battery.temperature);
}

// Performance automática
android.performance.set_target_fps(60);

// Modo economia de bateria
if battery.level < 0.2 {
    android.performance.enable_power_save(); // FPS -> 30
}

// Thermal throttling automático
// Se temperatura > 45°C, reduz FPS automaticamente
```

### Orientação


```rust
use sevenx_engine::android::ScreenOrientation;

// Obter orientação atual
let orientation = android.orientation.get_orientation();

// Verificar tipo
if android.orientation.is_landscape() {
    println!("Modo paisagem");
}

if android.orientation.is_portrait() {
    println!("Modo retrato");
}

// Travar orientação
android.orientation.lock(ScreenOrientation::Landscape);

// Destravar
android.orientation.unlock();
```

### Notificações


```rust
// Notificação simples
let id = android.notifications.show("Título", "Mensagem");

// Notificação agendada
use std::time::Duration;

android.notifications.show_delayed(
    "Lembrete",
    "Volte ao jogo!",
    Duration::from_secs(3600) // 1 hora
);

// Cancelar notificação
android.notifications.cancel(id);

// Cancelar todas
android.notifications.cancel_all();
```

### Conectividade


```rust
// Verificar conexão
if android.connectivity.is_connected() {
    println!("Conectado!");
}

// Tipo de rede
if android.connectivity.is_wifi() {
    println!("WiFi - pode baixar assets grandes");
} else if android.connectivity.is_mobile() {
    println!("Dados móveis - economizar banda");
}

// Rede medida (dados móveis limitados)
if android.connectivity.is_metered() {
    println!("Conexão medida - evitar downloads grandes");
}
```

### Armazenamento


```rust
// Salvar dados
android.storage.save("player_name", "João");
android.storage.save("high_score", "1000");

// Carregar dados
if let Some(name) = android.storage.load("player_name") {
    println!("Bem-vindo, {}!", name);
}

// Verificar existência
if android.storage.has("high_score") {
    println!("Save encontrado!");
}

// Remover
android.storage.remove("temp_data");

// Limpar tudo
android.storage.clear();
```

### Permissões


```rust
use sevenx_engine::android::Permission;

// Solicitar permissão
if android.permissions.request(Permission::Camera) {
    println!("Permissão de câmera concedida!");
}

// Verificar permissão
if android.permissions.is_granted(Permission::Storage) {
    // Pode acessar armazenamento
}

// Revogar (para testes)
android.permissions.revoke(Permission::Microphone);

// Permissões disponíveis:
// - Permission::Camera
// - Permission::Microphone
// - Permission::Location
// - Permission::Storage
// - Permission::Contacts
// - Permission::Calendar
```

### Teclado Virtual


```rust
// Mostrar teclado
android.keyboard.show();

// Esconder teclado
android.keyboard.hide();

// Verificar visibilidade
if android.keyboard.is_visible() {
    println!("Teclado aberto");
}

// Obter texto
let text = android.keyboard.get_text();

// Definir texto
android.keyboard.set_text("Novo texto".to_string());

// Limpar
android.keyboard.clear();
```

### Compartilhamento


```rust
use sevenx_engine::android::ShareManager;

// Compartilhar texto
ShareManager::share_text("Meu high score: 1000!");

// Compartilhar imagem
ShareManager::share_image("/sdcard/screenshot.png");

// Compartilhar arquivo
ShareManager::share_file("/sdcard/save.dat", "application/octet-stream");
```

## 🎮 Exemplo Completo: Jogo Mobile


```rust
use sevenx_engine::{
    Engine, EngineConfig, GameState,
    input::InputHandler,
    world::World,
    ui::render_text,
};

#[cfg(target_os = "android")]

use sevenx_engine::android::{
    AdvancedAndroidManager, GestureType, VibrationIntensity,
};

struct MobileGame {
    #[cfg(target_os = "android")]
    android: AdvancedAndroidManager,
    
    player_x: f32,
    player_y: f32,
    score: u32,
}

impl GameState for MobileGame {
    fn new() -> Self {
        #[cfg(target_os = "android")]
        {
            let mut android = AdvancedAndroidManager::new();
            
            // Setup inicial
            android.input.create_virtual_joystick(100.0, 450.0, 50.0);
            android.permissions.request(sevenx_engine::android::Permission::Storage);
            
            // Carregar high score
            let score = if let Some(saved) = android.storage.load("high_score") {
                saved.parse().unwrap_or(0)
            } else {
                0
            };
            
            Self {
                android,
                player_x: 400.0,
                player_y: 300.0,
                score,
            }
        }
        
        #[cfg(not(target_os = "android"))]
        {
            Self {
                player_x: 400.0,
                player_y: 300.0,
                score: 0,
            }
        }
    }

    fn update(&mut self, dt: f32, _input: &InputHandler, _world: &mut World) {
        #[cfg(target_os = "android")]
        {
            self.android.update();
            
            // Controle por joystick
            let (axis_x, axis_y) = self.android.input.get_virtual_joystick_axis();
            self.player_x += axis_x * 200.0 * dt;
            self.player_y += axis_y * 200.0 * dt;
            
            // Controle por acelerômetro
            let accel = self.android.input.get_accelerometer();
            self.player_x += accel.x * 10.0 * dt;
            
            // Gestos
            for gesture in self.android.gestures.get_gestures() {
                match gesture.gesture_type {
                    GestureType::Tap => {
                        self.score += 10;
                        self.android.vibration.vibrate_with_intensity(
                            30,
                            VibrationIntensity::Light
                        );
                    }
                    GestureType::DoubleTap => {
                        self.score += 50;
                        self.android.vibration.vibrate_with_intensity(
                            50,
                            VibrationIntensity::Heavy
                        );
                    }
                    _ => {}
                }
            }
            
            // Salvar high score
            self.android.storage.save("high_score", &self.score.to_string());
        }
    }

    fn draw(&mut self, _world: &World, pixels: &mut [u8]) {
        let score_text = format!("Score: {}", self.score);
        render_text(&score_text, 20, 20, [255, 255, 255, 255], pixels, 800);
        
        // Desenhar player (círculo simples)
        let px = self.player_x as i32;
        let py = self.player_y as i32;
        let radius = 20;
        
        for y in (py - radius).max(0)..(py + radius).min(600) {
            for x in (px - radius).max(0)..(px + radius).min(800) {
                let dx = x - px;
                let dy = y - py;
                if dx * dx + dy * dy <= radius * radius {
                    let idx = ((y * 800 + x) * 4) as usize;
                    if idx + 3 < pixels.len() {
                        pixels[idx] = 255;     // R
                        pixels[idx + 1] = 100; // G
                        pixels[idx + 2] = 100; // B
                        pixels[idx + 3] = 255; // A
                    }
                }
            }
        }
    }
}

fn main() {
    let config = EngineConfig::new()
        .with_title("Mobile Game")
        .with_size(800, 600);
    
    Engine::with_config(config).run::<MobileGame>();
}
```

## 📦 Configuração do Cargo.toml


```toml
[package.metadata.android]
package = "com.sevenx.mygame"
build_targets = ["aarch64-linux-android", "armv7-linux-androideabi"]
assets = "assets"

[package.metadata.android.sdk]
min_sdk_version = 24
target_sdk_version = 33
compile_sdk_version = 33

[[package.metadata.android.uses_permission]]
name = "android.permission.INTERNET"

[[package.metadata.android.uses_permission]]
name = "android.permission.VIBRATE"

[[package.metadata.android.uses_permission]]
name = "android.permission.WAKE_LOCK"

[[package.metadata.android.uses_feature]]
name = "android.hardware.touchscreen"
required = true

[[package.metadata.android.uses_feature]]
name = "android.hardware.sensor.accelerometer"
required = false

[lib]
crate-type = ["cdylib", "rlib"]

[[example]]
name = "my_game"
crate-type = ["cdylib"]

[target.'cfg(target_os = "android")'.dependencies]
android-activity = { version = "0.6", features = ["native-activity"] }
```

## 🔧 Troubleshooting


### Erro: NDK não encontrado


```powershell
# Instale o NDK via Android Studio ou:

# 1. Baixe de https://developer.android.com/ndk/downloads

# 2. Configure a variável:

$env:ANDROID_NDK_ROOT = "C:\Android\sdk\ndk\25.2.9519653"
```

### Erro: cargo-apk não encontrado


```powershell
cargo install cargo-apk
```

### Erro: Target não instalado


```powershell
rustup target add aarch64-linux-android
rustup target add armv7-linux-androideabi
```

### APK não instala no dispositivo


```powershell
# Verifique se o dispositivo está conectado

adb devices

# Desinstale versão antiga

adb uninstall com.sevenx.mygame

# Instale novamente

adb install -r target\aarch64-linux-android\release\examples\my_game.apk
```

### Performance ruim


```rust
// Ative modo economia
android.performance.enable_power_save();

// Reduza qualidade gráfica
android.performance.set_target_fps(30);
```

## 📱 Otimizações para Mobile


### 1. Bateria


```rust
// Ajuste automático baseado na bateria
if let Some(battery) = android.input.get_battery() {
    if battery.level < 0.2 && !battery.is_charging {
        android.performance.enable_power_save();
    }
}
```

### 2. Thermal Throttling


```rust
// Reduz FPS automaticamente se esquentar
android.performance.check_thermal_throttling(battery.temperature);
```

### 3. Conectividade


```rust
// Evite downloads grandes em dados móveis
if android.connectivity.is_mobile() && android.connectivity.is_metered() {
    println!("Adiando download de assets");
}
```

### 4. Resolução Adaptativa


```rust
let config = if android.performance.is_power_save_mode() {
    EngineConfig::new().with_size(640, 480) // Menor resolução
} else {
    EngineConfig::new().with_size(1280, 720) // Resolução normal
};
```

## 🎯 Próximos Passos


1. **Teste no dispositivo real** - Emuladores não suportam todos os sensores
2. **Otimize assets** - Use texturas comprimidas para mobile
3. **Implemente salvamento** - Use o StorageManager para persistência
4. **Adicione analytics** - Monitore performance em dispositivos reais
5. **Teste em múltiplos dispositivos** - Diferentes resoluções e capacidades

## 📚 Recursos Adicionais


- [Android NDK Guide](https://developer.android.com/ndk/guides)
- [cargo-apk Documentation](https://github.com/rust-mobile/cargo-apk)
- [SevenX Examples](./examples/)
- [API Reference](./API_REFERENCE.md)

## 🆘 Suporte


Problemas? Abra uma issue no GitHub:
https://github.com/sevenx777-dev/SevenX-Engine/issues

---

**SevenX Engine** - Build amazing mobile games with Rust! 🚀