# 📖 Referência Rápida da API - SevenX Engine
## 🎯 Guia de Início Rápido
### Estrutura Mínima
```rust
use sevenx_engine::*;
struct MeuJogo;
impl GameState for MeuJogo {
fn new() -> Self { MeuJogo }
fn update(&mut self, dt: f32, input: &InputHandler, world: &mut World) {
// Sua lógica aqui
}
fn draw(&mut self, _world: &World, _pixels: &mut [u8]) {
// Desenho customizado (opcional)
}
}
fn main() {
Engine::new().run::<MeuJogo>();
}
```
---
## 🎮 Input (Teclado)
### Verificar Teclas
```rust
// No método update
if input.is_key_pressed(KeyCode::Space) {
println!("SPACE pressionado!");
}
// Teclas comuns
KeyCode::Space
KeyCode::Enter
KeyCode::Escape
KeyCode::ArrowUp, ArrowDown, ArrowLeft, ArrowRight
KeyCode::KeyA, KeyB, KeyC... KeyZ
KeyCode::Digit1, Digit2... Digit9, Digit0
```
### Exemplo de Movimento
```rust
let speed = 200.0;
if input.is_key_pressed(KeyCode::ArrowLeft) {
player_x -= speed * dt;
}
if input.is_key_pressed(KeyCode::ArrowRight) {
player_x += speed * dt;
}
```
---
## 🎨 Desenhar na Tela (UI)
### Texto
```rust
use sevenx_engine::ui::render_text;
// No método draw
render_text(
"HELLO WORLD", // Texto
100, // X
100, // Y
[255, 255, 255, 255], // Cor RGBA (branco)
pixels, // Buffer
800 // Largura da tela
);
```
### Retângulos
```rust
use sevenx_engine::ui;
// Retângulo preenchido
ui::render_rect(
100, // X
100, // Y
50, // Largura
50, // Altura
[255, 0, 0, 255], // Cor RGBA (vermelho)
pixels,
800
);
// Borda de retângulo
ui::render_rect_outline(
100, 100, // X, Y
50, 50, // Largura, Altura
2, // Espessura da borda
[255, 255, 255, 255], // Cor
pixels,
800
);
```
---
## 🌍 World e GameObjects
### Criar Objetos
```rust
use sevenx_engine::game_object::{GameObject, ObjectType};
// No método update ou new
let player = GameObject::new(100.0, 100.0, ObjectType::Player);
world.add_object(player);
```
### Encontrar Objetos
```rust
// Encontrar o jogador
if let Some(player) = world.game_objects.iter_mut()
.find(|obj| obj.object_type == ObjectType::Player)
{
// Fazer algo com o jogador
player.transform.position.0 += 10.0;
}
```
### Remover Objetos
```rust
// Marcar como inativo
obj.active = false;
// Limpar inativos
world.cleanup_inactive();
// Ou remover diretamente
world.game_objects.remove(index);
```
---
## 🎯 Transform (Posição, Rotação, Escala)
### Posição
```rust
// Ler posição
let (x, y) = obj.transform.position;
// Definir posição
obj.transform.position = (100.0, 200.0);
// Mover (relativo)
obj.transform.translate(10.0, 5.0);
```
### Rotação
```rust
// Rotação em radianos
obj.transform.rotation = 1.57; // 90 graus
// Rotação em graus
obj.transform.set_rotation_degrees(90.0);
// Rotar (relativo)
obj.transform.rotate(0.1);
// Ler em graus
let degrees = obj.transform.get_rotation_degrees();
```
### Flip (Espelhar)
```rust
// Flip horizontal
obj.transform.flip_h = true;
// Flip vertical
obj.transform.flip_v = true;
```
---
## ⚡ Física
### Adicionar Física
```rust
use sevenx_engine::Physics;
let player = GameObject::new(100.0, 100.0, ObjectType::Player)
.with_physics(Physics::new()
.with_gravity(1.0) // Afetado pela gravidade
.with_drag(0.1)); // Resistência do ar
```
### Aplicar Força
```rust
if let Some(physics) = &mut player.physics {
physics.apply_force(0.0, -500.0); // Pulo
}
```
### Velocidade
```rust
if let Some(physics) = &mut player.physics {
physics.velocity = (100.0, 0.0); // Velocidade direta
}
```
---
## 💥 Colisão
### Adicionar Collider
```rust
use sevenx_engine::Collider;
let player = GameObject::new(100.0, 100.0, ObjectType::Player)
.with_collider(Collider::new(32.0, 32.0));
```
### Verificar Colisão
```rust
use sevenx_engine::collision::Rect;
let rect1 = Rect::new(x1, y1, w1, h1);
let rect2 = Rect::new(x2, y2, w2, h2);
if rect1.intersects(&rect2) {
println!("Colisão!");
}
```
### Trigger (Não Bloqueia)
```rust
let coin = GameObject::new(100.0, 100.0, ObjectType::Coin)
.with_collider(Collider::new(32.0, 32.0).as_trigger());
```
---
## 🎨 Sprites
### Carregar Sprite
```rust
use sevenx_engine::sprite::SpriteSheet;
// Carregar de arquivo
let sprite = SpriteSheet::load("assets/player.png", 32, 32)?;
// Ou usar placeholder
let sprite = SpriteSheet::create_placeholder();
```
### Adicionar ao Objeto
```rust
use sevenx_engine::game_object::PlayerAction;
player.sheets.insert(PlayerAction::Idle, sprite);
```
---
## ✨ Partículas 2D (v0.2.6 - ATUALIZADO)
### Criar Sistema
```rust
use sevenx_engine::{ParticleSystem, ParticleConfig, BlendMode};
let mut particles = ParticleSystem::new(1000)
.with_blend_mode(BlendMode::Additive) // Brilho aditivo
.with_drag(0.5); // Arrasto do ar
```
### Emitir Partículas (Presets)
```rust
// Explosão
let config = ParticleConfig::explosion();
particles.emit_burst(x, y, 50, config);
// Fumaça
let config = ParticleConfig::smoke();
particles.emit_burst(x, y, 30, config);
// Brilho/Faíscas
let config = ParticleConfig::sparkle();
particles.emit_burst(x, y, 40, config);
// Fogo
let config = ParticleConfig::fire();
particles.emit_stream(x, y, 10.0, dt, config);
// Magia
let config = ParticleConfig::magic();
particles.emit_burst(x, y, 20, config);
// Sangue
let config = ParticleConfig::blood();
particles.emit_burst(x, y, 15, config);
// Neve
let config = ParticleConfig::snow();
particles.emit_stream(x, y, 5.0, dt, config);
// Chuva
let config = ParticleConfig::rain();
particles.emit_stream(x, y, 20.0, dt, config);
```
### 🆕 Partículas Customizadas Avançadas (v0.2.6)
```rust
use sevenx_engine::Particle;
use rand::Rng;
let mut rng = rand::thread_rng();
// Partícula com todos os recursos avançados
let particle = Particle::new(
x, y, // Posição
vx, vy, // Velocidade
2.0, // Vida (segundos)
[255, 100, 200, 255], // Cor RGBA
5.0, // Tamanho
)
.with_turbulence(5.0) // 🆕 Movimento caótico
.with_color_shift([-100.0, 50.0, 100.0, 0.0]) // 🆕 Muda de cor
.with_acceleration(0.0, 50.0) // 🆕 Aceleração constante
.with_scale(1.0, -0.3) // Encolhe com o tempo
.with_rotation(0.0, 5.0) // Rotaciona
.with_fade(0.1, 0.2); // Fade in/out
particles.emit(particle);
```
### Recursos Avançados de Partículas
```rust
// Turbulência - movimento aleatório/caótico
.with_turbulence(10.0) // Intensidade
// Color Shift - transição gradual de cor durante a vida
.with_color_shift([
-100.0, // R: diminui 100 ao longo da vida
50.0, // G: aumenta 50
100.0, // B: aumenta 100
0.0 // A: sem mudança
])
// Aceleração - força constante
.with_acceleration(
10.0, // X: empurra para direita
-20.0 // Y: empurra para cima
)
// Escala dinâmica
.with_scale(
1.0, // Escala inicial
-0.5 // Velocidade de mudança (negativo = encolhe)
)
// Rotação
.with_rotation(
0.0, // Rotação inicial (radianos)
5.0 // Velocidade de rotação
)
```
### Blend Modes
```rust
use sevenx_engine::BlendMode;
// Normal - blend padrão
let particles = ParticleSystem::new(1000)
.with_blend_mode(BlendMode::Normal);
// Additive - brilho intenso (ideal para fogo, magia)
let particles = ParticleSystem::new(1000)
.with_blend_mode(BlendMode::Additive);
// Multiply - escurecimento (ideal para fumaça)
let particles = ParticleSystem::new(1000)
.with_blend_mode(BlendMode::Multiply);
```
### Atualizar e Renderizar
```rust
// No update
particles.update(dt, 200.0); // dt, gravidade
// No draw
particles.render(pixels, camera_x, camera_y, 800, 600);
// Limpar todas as partículas
particles.clear();
// Verificar quantidade
let count = particles.count();
```
---
## 🌟 Partículas 3D (v0.2.6 - NOVO)
### Criar Sistema 3D
```rust
use sevenx_engine::{ParticleSystem3D, Particle3D, Vec3};
let mut particles_3d = ParticleSystem3D::new(500);
particles_3d.gravity = Vec3::new(0.0, -9.8, 0.0);
```
### Efeitos Pré-configurados
```rust
let position = Vec3::new(0.0, 0.0, 0.0);
// Explosão (50 partículas)
particles_3d.explosion(position);
// Fogo realista
particles_3d.fire(position);
// Magia multicolorida
particles_3d.magic(position);
// Fumaça com turbulência
particles_3d.smoke(position);
// Faíscas brilhantes
particles_3d.sparkles(position);
// Rastro de movimento
let direction = Vec3::new(1.0, 0.0, 0.0);
particles_3d.trail(position, direction);
```
### Partículas 3D Customizadas
```rust
use rand::Rng;
let mut rng = rand::thread_rng();
let particle = Particle3D::new(
Vec3::new(0.0, 0.0, 0.0), // Posição
Vec3::new(1.0, 2.0, 0.5), // Velocidade
[255, 100, 50, 255], // Cor
2.0, // Vida
)
.with_acceleration(Vec3::new(0.0, -5.0, 0.0)) // 🆕 Aceleração
.with_rotation(0.0, 5.0) // 🆕 Rotação
.with_scale(1.0, -0.3) // 🆕 Escala
.with_color_shift([-80.0, -50.0, 0.0, 0.0]) // 🆕 Mudança de cor
.with_turbulence(0.2); // 🆕 Turbulência
particles_3d.particles.push(particle);
```
### Atualizar Partículas 3D
```rust
// No update
particles_3d.update(dt);
// Limpar
particles_3d.clear();
```
---
## 💬 Diálogos
### Criar Diálogo
```rust
use sevenx_engine::dialogue::{DialogueBuilder, DialogueSystem};
let mut dialogue_system = DialogueSystem::new();
let dialogue = DialogueBuilder::new("npc1", "Guarda")
.add_node("Olá, viajante!")
.add_node_with_choices(
"O que deseja?",
vec![
("Informações", 2),
("Tchau", 3),
],
)
.add_node("Aqui estão as informações...")
.add_node("Até logo!")
.build();
dialogue_system.add_dialogue(dialogue);
```
### Usar Diálogo
```rust
// Iniciar
dialogue_system.start_dialogue("npc1");
// Avançar
dialogue_system.advance();
// Escolher opção
dialogue_system.choose(0); // Primeira opção
// Obter texto atual
if let Some(node) = dialogue_system.get_current_node() {
println!("{}", node.text);
}
```
---
## 💾 Save/Load
### Salvar Jogo
```rust
use sevenx_engine::save_system::GameSave;
let mut save = GameSave::new();
// Modificar dados
save.player_data.name = "Jogador".to_string();
save.player_data.level = 5;
save.game_progress.score = 1000;
// Salvar
save.save_json("saves/save1.json")?;
```
### Carregar Jogo
```rust
let save = GameSave::load_json("saves/save1.json")?;
// Usar dados
println!("Level: {}", save.player_data.level);
println!("Score: {}", save.game_progress.score);
```
---
## ⚙️ Configuração
### Configurar Engine
```rust
use sevenx_engine::EngineConfig;
let config = EngineConfig::new()
.with_title("Meu Jogo")
.with_size(1024, 768)
.with_gravity(980.0)
.with_clear_color(20, 20, 40, 255);
Engine::with_config(config).run::<MeuJogo>();
```
---
## 🎮 Gamepad
### Verificar Botões
```rust
use sevenx_engine::{GamepadManager, GamepadButton};
let gamepad = GamepadManager::new();
if gamepad.is_button_pressed(GamepadButton::South) {
println!("Botão A/Cross pressionado!");
}
```
### Eixos Analógicos
```rust
use sevenx_engine::GamepadAxis;
let axis_x = gamepad.get_axis(GamepadAxis::LeftStickX);
let axis_y = gamepad.get_axis(GamepadAxis::LeftStickY);
player_x += axis_x * speed * dt;
player_y += axis_y * speed * dt;
```
---
## 📋 Eventos
### Criar Sistema de Eventos
```rust
use sevenx_engine::{EventSystem, EventData, EventType};
let mut events = EventSystem::new();
// Registrar listener
});
// Emitir evento
let event = EventData::new(EventType::CoinCollected)
.with_data("points", "10");
events.emit(event);
```
---
## 🗺️ Tilemap
### Criar Tilemap
```rust
use sevenx_engine::{Tilemap, Tile};
let mut tilemap = Tilemap::new(20, 15, 32, 32);
// Definir tiles
tilemap.set_tile(0, 0, Some(Tile::new(0).with_solid(true)));
// Renderizar
tilemap.render(pixels, camera_x, camera_y, 800, 600);
```
---
## 🎨 Shaders 2D (v0.2.6 - ATUALIZADO)
### Aplicar Shaders
```rust
use sevenx_engine::{Shader, ShaderManager, ShaderType};
let mut shader_manager = ShaderManager::new();
// Bloom (brilho intenso)
shader_manager.add_shader(
Shader::new(ShaderType::Bloom)
.with_parameter("threshold", 200.0)
.with_parameter("bloom_intensity", 1.5)
);
// Motion Blur (desfoque de movimento)
shader_manager.add_shader(
Shader::new(ShaderType::MotionBlur)
.with_parameter("direction", 0.0) // radianos
.with_parameter("samples", 5.0)
);
// No draw
shader_manager.apply_all(pixels, 800, 600);
```
### Shaders Básicos
```rust
ShaderType::Grayscale // Preto e branco
ShaderType::Sepia // Tom sépia vintage
ShaderType::Invert // Inverte cores
ShaderType::Blur // Desfoque simples
ShaderType::Pixelate // Efeito pixelado
ShaderType::ChromaticAberration // Aberração cromática
ShaderType::Vignette // Escurecimento nas bordas
ShaderType::Scanlines // Linhas de varredura
ShaderType::CRT // Efeito de TV antiga
```
### 🆕 Shaders Avançados (v0.2.6)
```rust
// Detecção de bordas
ShaderType::EdgeDetect // Detecta bordas (Sobel)
ShaderType::Emboss // Efeito de relevo 3D
ShaderType::Sharpen // Aumenta nitidez
// Efeitos artísticos
ShaderType::OilPainting // Pintura a óleo
ShaderType::Posterize // Redução de cores
// Efeitos de iluminação
ShaderType::Bloom // Brilho intenso
ShaderType::MotionBlur // Desfoque de movimento
ShaderType::GaussianBlur // Desfoque suave
// Manipulação de cor
ShaderType::HueShift // Rotação de matiz
ShaderType::Saturation // Controle de saturação
ShaderType::Contrast // Controle de contraste
ShaderType::Brightness // Controle de brilho
// Efeitos especiais
ShaderType::Glitch // Efeito de falha digital
ShaderType::Pixelize // Pixelização por blocos
ShaderType::WaveDistortion // Distorção em onda
```
### Shaders com Parâmetros Avançados
```rust
// Bloom (brilho)
let bloom = Shader::new(ShaderType::Bloom)
.with_parameter("threshold", 180.0) // Limiar de brilho
.with_parameter("bloom_intensity", 2.0); // Intensidade
// Motion Blur
let motion_blur = Shader::new(ShaderType::MotionBlur)
.with_parameter("direction", 1.57) // Direção em radianos
.with_parameter("samples", 7.0); // Qualidade
// Hue Shift (mudança de cor)
let hue_shift = Shader::new(ShaderType::HueShift)
.with_parameter("shift", 180.0); // Graus (0-360)
// Gaussian Blur
let gaussian = Shader::new(ShaderType::GaussianBlur)
.with_parameter("radius", 3.0)
.with_parameter("sigma", 1.5);
// Edge Detection
let edges = Shader::new(ShaderType::EdgeDetect)
.with_parameter("threshold", 50.0);
// Oil Painting
let oil = Shader::new(ShaderType::OilPainting)
.with_parameter("radius", 3.0);
// Glitch
let glitch = Shader::new(ShaderType::Glitch)
.with_parameter("glitch_intensity", 0.1);
// Wave Distortion
let wave = Shader::new(ShaderType::WaveDistortion)
.with_parameter("amplitude", 10.0)
.with_parameter("frequency", 0.05);
```
### Combinar Múltiplos Shaders
```rust
let mut shader_manager = ShaderManager::new();
// Bloom + Hue Shift + Saturation
shader_manager.add_shader(
Shader::new(ShaderType::Bloom)
.with_parameter("threshold", 200.0)
.with_parameter("bloom_intensity", 1.5)
);
shader_manager.add_shader(
Shader::new(ShaderType::HueShift)
.with_parameter("shift", 30.0)
);
shader_manager.add_shader(
Shader::new(ShaderType::Saturation)
.with_parameter("saturation", 1.3)
);
// Aplica todos em sequência
shader_manager.apply_all(pixels, 800, 600);
```
---
## 🏆 Conquistas (v0.2.5)
### Criar Sistema de Conquistas
```rust
use sevenx_engine::{Achievement, AchievementSystem};
let mut achievements = AchievementSystem::new();
// Conquista simples
let first_kill = Achievement::new(
"first_kill",
"Primeira Morte",
"Derrote seu primeiro inimigo",
10
);
achievements.add_achievement(first_kill);
// Conquista com progresso
let coin_collector = Achievement::new(
"coin_collector",
"Colecionador",
"Colete 100 moedas",
50
).with_progress(100);
achievements.add_achievement(coin_collector);
// Conquista oculta
let secret = Achievement::new(
"secret",
"???",
"Descubra o segredo",
100
).as_hidden();
achievements.add_achievement(secret);
```
### Usar Conquistas
```rust
// Adicionar progresso
if achievements.add_progress("coin_collector", 1) {
println!("Conquista desbloqueada!");
}
// Desbloquear diretamente
achievements.unlock("first_kill");
// Verificar se está desbloqueada
if achievements.is_unlocked("first_kill") {
println!("Já desbloqueada!");
}
// Estatísticas
println!("Pontos: {}", achievements.total_points());
println!("Progresso: {:.1}%", achievements.completion_percentage());
```
### Salvar/Carregar
```rust
// Salvar
achievements.save_json("achievements.json")?;
// Carregar
let achievements = AchievementSystem::load_json("achievements.json")?;
```
---
## 🌐 Networking (v0.2.5)
### Criar Host
```rust
use sevenx_engine::NetworkManager;
let mut network = NetworkManager::create_host("player1", "Host");
println!("Host criado!");
```
### Conectar ao Host
```rust
let mut network = NetworkManager::connect_to_host(
"player2",
"Cliente",
"127.0.0.1:8080"
);
```
### Enviar Mensagens
```rust
// Atualizar posição
network.update_player_position(player_x, player_y);
// Enviar ação
network.send_player_action("jump");
// Chat
network.send_chat("Olá pessoal!");
```
### Processar Mensagens
```rust
// No update
network.process_messages();
// Verificar jogadores
println!("Jogadores: {}", network.player_count());
```
---
## ✨ Partículas Avançadas (v0.2.5)
### Novos Presets
```rust
use sevenx_engine::ParticleConfig;
// Fogo
let fire = ParticleConfig::fire();
particles.emit_burst(x, y, 30, fire);
// Magia
let magic = ParticleConfig::magic();
particles.emit_burst(x, y, 40, magic);
// Sangue
let blood = ParticleConfig::blood();
particles.emit_burst(x, y, 20, blood);
// Neve
let snow = ParticleConfig::snow();
particles.emit_stream(x, y, 10.0, dt, snow);
// Chuva
let rain = ParticleConfig::rain();
particles.emit_stream(x, y, 50.0, dt, rain);
```
### Blend Modes
```rust
use sevenx_engine::{ParticleSystem, BlendMode};
// Normal (padrão)
let particles = ParticleSystem::new(500)
.with_blend_mode(BlendMode::Normal);
// Aditivo (brilho)
let particles = ParticleSystem::new(500)
.with_blend_mode(BlendMode::Additive);
// Multiplicativo (sombra)
let particles = ParticleSystem::new(500)
.with_blend_mode(BlendMode::Multiply);
```
### Arrasto
```rust
// Partículas com resistência do ar
let particles = ParticleSystem::new(500)
.with_drag(0.5); // 0.0 = sem arrasto, 1.0 = para rápido
```
---
## 💡 Dicas Rápidas
### Delta Time (dt)
```rust
// SEMPRE use dt para movimento suave
let speed = 100.0; // pixels por segundo
player_x += speed * dt; // Movimento independente de FPS
```
### Cores RGBA
```rust
[255, 0, 0, 255] // Vermelho
[0, 255, 0, 255] // Verde
[0, 0, 255, 255] // Azul
[255, 255, 255, 255] // Branco
[0, 0, 0, 255] // Preto
[255, 255, 0, 255] // Amarelo
[255, 0, 255, 255] // Magenta
[0, 255, 255, 255] // Ciano
```
### Debug
```rust
// Imprimir FPS
println!("FPS: {:.0}", 1.0 / dt);
// Imprimir posição
println!("Pos: {:?}", player.transform.position);
// Contar objetos
println!("Objetos: {}", world.game_objects.len());
```
---
## 🆘 Problemas Comuns
### "cannot find type InputHandler"
```rust
// Adicione os imports corretos
use sevenx_engine::{
input::InputHandler,
world::World,
Engine, EngineConfig, GameState, KeyCode,
};
```
### "method not found in World"
```rust
// World começa vazio, você precisa adicionar objetos
if world.game_objects.is_empty() {
self.setup_world(world);
}
```
### Sprite não aparece
```rust
// Certifique-se de:
// 1. Adicionar o sprite ao objeto
player.sheets.insert(PlayerAction::Idle, sprite);
// 2. Adicionar o objeto ao mundo
world.add_object(player);
// 3. Marcar como ativo
player.active = true;
```
---
## 📚 Mais Recursos
- **GUIDE.md** - Guia completo
- **GAME_TUTORIAL.md** - Tutoriais de jogos
- **ASSETS_GUIDE.md** - Como usar assets
- **PATTERNS.md** - Padrões de design
- **Exemplos** - `cargo run --example nome_exemplo`
---
## 🎯 Template Completo
```rust
use sevenx_engine::*;
use sevenx_engine::{
input::InputHandler,
ui::{self, render_text},
world::World,
Engine, EngineConfig, GameState, KeyCode,
};
struct MeuJogo {
player_x: f32,
player_y: f32,
score: u32,
}
impl GameState for MeuJogo {
fn new() -> Self {
MeuJogo {
player_x: 400.0,
player_y: 300.0,
score: 0,
}
}
fn update(&mut self, dt: f32, input: &InputHandler, _world: &mut World) {
let speed = 200.0;
if input.is_key_pressed(KeyCode::ArrowLeft) {
self.player_x -= speed * dt;
}
if input.is_key_pressed(KeyCode::ArrowRight) {
self.player_x += speed * dt;
}
if input.is_key_pressed(KeyCode::ArrowUp) {
self.player_y -= speed * dt;
}
if input.is_key_pressed(KeyCode::ArrowDown) {
self.player_y += speed * dt;
}
}
fn draw(&mut self, _world: &World, pixels: &mut [u8]) {
// Desenha jogador
ui::render_rect(
self.player_x as i32,
self.player_y as i32,
32,
32,
[0, 255, 0, 255],
pixels,
800,
);
// HUD
let score_text = format!("SCORE: {}", self.score);
render_text(&score_text, 10, 10, [255, 255, 255, 255], pixels, 800);
}
}
fn main() {
let config = EngineConfig::new()
.with_title("Meu Jogo")
.with_size(800, 600);
Engine::with_config(config).run::<MeuJogo>();
}
```
**Copie e cole este template para começar! 🚀**
---
## 🆕 v0.2.6 - Features Avançadas
### 🎲 Renderização 3D Experimental
#### Vec3 - Vetores 3D
```rust
use sevenx_engine::Vec3;
let v = Vec3::new(1.0, 2.0, 3.0);
let zero = Vec3::zero();
// Operações
let length = v.length();
let normalized = v.normalize();
let dot = v.dot(&other);
let cross = v.cross(&other);
```
#### Mesh3D - Geometria 3D
```rust
use sevenx_engine::Mesh3D;
// Primitivas
let cube = Mesh3D::cube(2.0);
let sphere = Mesh3D::sphere(1.5, 16);
// Transformações
cube.position = Vec3::new(0.0, 0.0, -5.0);
cube.rotation = Vec3::new(0.0, 1.57, 0.0); // radianos
cube.scale = Vec3::new(1.0, 2.0, 1.0);
```
#### Camera3D - Câmera 3D
```rust
use sevenx_engine::Camera3D;
let mut camera = Camera3D::new(800, 600);
camera.position = Vec3::new(0.0, 2.0, 10.0);
camera.look_at(Vec3::zero());
// Movimento
camera.move_forward(5.0);
camera.rotate_around_target(0.1, 0.2);
// Configuração
camera.fov = 60.0;
camera.near = 0.1;
camera.far = 100.0;
```
#### Renderer3D - Renderizador 3D
```rust
use sevenx_engine::Renderer3D;
let mut renderer = Renderer3D::new(800, 600);
renderer.wireframe = false;
renderer.backface_culling = true;
// Renderizar
renderer.render_mesh(&mesh, frame, 800, 600);
```
### 🎨 Shaders 3D (v0.2.6 - NOVO)
#### PhongShader - Iluminação Phong
```rust
use sevenx_engine::{PhongShader, Light3D, Material, Vec3};
// Criar shader
let mut phong = PhongShader::new();
phong.ambient_light = [0.1, 0.1, 0.1];
// Adicionar luzes
phong.add_light(Light3D::new(
Vec3::new(5.0, 10.0, 5.0), // Posição
[1.0, 1.0, 1.0], // Cor RGB (0-1)
1.5 // Intensidade
));
phong.add_light(Light3D::new(
Vec3::new(-5.0, 5.0, -5.0),
[0.5, 0.5, 1.0], // Luz azulada
0.8
));
// Materiais
let metal = Material::metal();
let plastic = Material::plastic();
let default = Material::default();
// Calcular iluminação
let lit_color = phong.calculate_lighting(
&position,
&normal,
&view_dir,
&material,
base_color
);
```
#### FresnelShader - Rim Lighting
```rust
use sevenx_engine::FresnelShader;
let fresnel = FresnelShader::new();
// fresnel.rim_color = [1.0, 1.0, 1.0];
// fresnel.rim_power = 3.0;
// fresnel.rim_intensity = 1.0;
let color = fresnel.calculate(&normal, &view_dir, base_color);
```
#### ToonShader - Cel Shading
```rust
use sevenx_engine::ToonShader;
let toon = ToonShader::new(4) // 4 níveis de cor
.with_outline(0.1, [0, 0, 0, 255]);
// Aplicar quantização
let toon_color = toon.apply(color, light_intensity);
// Verificar se deve desenhar contorno
if toon.should_outline(normal_dot_view) {
// Desenha contorno preto
}
```
#### ReflectionShader - Reflexões
```rust
use sevenx_engine::ReflectionShader;
let mut reflection = ReflectionShader::new();
reflection.reflectivity = 0.5;
reflection.environment_color = [0.5, 0.7, 1.0]; // Céu azul
let color = reflection.calculate(&normal, &view_dir, base_color);
```
#### FogShader - Neblina
```rust
use sevenx_engine::FogShader;
let mut fog = FogShader::new();
fog.fog_color = [200, 200, 220, 255];
fog.fog_density = 0.05;
fog.fog_start = 10.0;
fog.fog_end = 50.0;
let color = fog.apply(base_color, distance);
```
#### NormalMapShader - Bump Mapping
```rust
use sevenx_engine::NormalMapShader;
let normal_map = NormalMapShader::new(0.5); // Força do bump
// Perturba a normal baseado em coordenadas UV
let perturbed_normal = normal_map.perturb_normal(&normal, u, v);
```
#### WireframeShader - Wireframe Colorido
```rust
use sevenx_engine::WireframeShader;
let wireframe = WireframeShader::new()
.with_colors(
[255, 255, 255, 255], // Cor das linhas
[50, 50, 50, 255] // Cor de preenchimento
)
.with_line_width(2.0);
```
#### Exemplo Completo - Combinando Shaders 3D
```rust
// Setup
let mut phong = PhongShader::new();
phong.add_light(Light3D::new(
Vec3::new(5.0, 10.0, 5.0),
[1.0, 1.0, 1.0],
1.5
));
let fresnel = FresnelShader::new();
let fog = FogShader::new();
let material = Material::metal();
// Renderização
for vertex in mesh.vertices {
// 1. Iluminação Phong
let mut color = phong.calculate_lighting(
&vertex.position,
&vertex.normal,
&view_dir,
&material,
base_color
);
// 2. Adiciona Fresnel (rim lighting)
color = fresnel.calculate(&vertex.normal, &view_dir, color);
// 3. Aplica Fog
let distance = (vertex.position - camera_pos).length();
color = fog.apply(color, distance);
// Desenha pixel
draw_pixel(color);
}
```
### 💡 Sistema de Iluminação 2D
#### Light - Luzes
```rust
use sevenx_engine::{Light, LightType};
// Point Light
let point = Light::point(400.0, 300.0, 200.0)
.with_color(255, 200, 100)
.with_intensity(1.0);
// Spot Light
let spot = Light::spot(
400.0, // x
300.0, // y
90.0, // direção (graus)
45.0, // ângulo do cone
250.0 // raio
)
.with_color(255, 50, 50)
.with_intensity(0.8);
// Calcular intensidade em um ponto
let intensity = light.calculate_intensity(x, y);
```
#### LightingSystem - Sistema de Iluminação
```rust
use sevenx_engine::LightingSystem;
let mut lighting = LightingSystem::new();
// Luz ambiente
lighting.set_ambient(30, 30, 50, 0.3);
// Adicionar luzes
let light_id = lighting.add_light(point_light);
lighting.remove_light(light_id);
// Aplicar iluminação
let lit_color = lighting.apply_lighting(x, y, base_color);
```
### 🎨 Post-Processing
#### PostEffect - Efeitos
```rust
use sevenx_engine::PostEffect;
// Bloom
let bloom = PostEffect::Bloom {
threshold: 0.7,
intensity: 0.5,
};
// Vignette
let vignette = PostEffect::Vignette {
intensity: 0.8,
radius: 0.8,
};
// Color Grading
let grading = PostEffect::ColorGrading {
contrast: 1.5,
saturation: 1.3,
brightness: 0.1,
};
```
#### PostProcessor - Processador
```rust
use sevenx_engine::PostProcessor;
let mut processor = PostProcessor::new();
// Adicionar efeitos
processor.add_effect(bloom);
processor.add_effect(vignette);
// Aplicar
processor.apply(frame, width, height);
// Controle
processor.set_enabled(true);
processor.clear_effects();
```
### 🗺️ Pathfinding A*
#### GridPos - Posição no Grid
```rust
use sevenx_engine::GridPos;
let pos = GridPos::new(10, 20);
// Distâncias
let euclidean = pos.distance(&other);
let manhattan = pos.manhattan_distance(&other);
```
#### Pathfinder - Sistema de Navegação
```rust
use sevenx_engine::Pathfinder;
let mut pathfinder = Pathfinder::new(40, 30);
// Obstáculos
pathfinder.add_obstacle(10, 10);
pathfinder.remove_obstacle(10, 10);
// Configuração
pathfinder.allow_diagonal = true;
// Verificar posição
if pathfinder.is_walkable(&pos) {
// Posição válida
}
// Encontrar caminho
if let Some(path) = pathfinder.find_path(start, goal) {
for pos in path {
println!("Passo: ({}, {})", pos.x, pos.y);
}
}
```
---
## 🎮 Exemplos Completos v0.2.6
### Exemplo 3D Básico
```rust
use sevenx_engine::*;
struct Game3D {
renderer3d: Renderer3D,
cube: Mesh3D,
}
impl GameState for Game3D {
fn new() -> Self {
let mut renderer3d = Renderer3D::new(800, 600);
renderer3d.camera.position = Vec3::new(0.0, 2.0, 8.0);
renderer3d.camera.look_at(Vec3::zero());
let cube = Mesh3D::cube(2.0);
Self { renderer3d, cube }
}
fn update(&mut self, dt: f32, input: &InputHandler, _world: &mut World) {
self.cube.rotation.y += dt;
if input.is_key_pressed(KeyCode::KeyW) {
self.renderer3d.camera.move_forward(5.0 * dt);
}
}
fn draw(&mut self, _world: &World, frame: &mut [u8]) {
// Limpa tela
for pixel in frame.chunks_exact_mut(4) {
pixel.copy_from_slice(&[20, 20, 40, 255]);
}
self.renderer3d.render_mesh(&self.cube, frame, 800, 600);
}
}
```
### Exemplo de Iluminação
```rust
use sevenx_engine::*;
struct LightingGame {
lighting: LightingSystem,
player_pos: (f32, f32),
torch_light: usize,
}
impl GameState for LightingGame {
fn new() -> Self {
let mut lighting = LightingSystem::new();
lighting.set_ambient(20, 20, 30, 0.2);
let torch = Light::point(400.0, 300.0, 200.0)
.with_color(255, 200, 100);
let torch_light = lighting.add_light(torch);
Self {
lighting,
player_pos: (400.0, 300.0),
torch_light,
}
}
fn update(&mut self, dt: f32, input: &InputHandler, _world: &mut World) {
let speed = 200.0;
if input.is_key_pressed(KeyCode::ArrowUp) {
self.player_pos.1 -= speed * dt;
}
self.lighting.lights[self.torch_light].position = self.player_pos;
}
fn draw(&mut self, _world: &World, frame: &mut [u8]) {
let width = 800;
let height = 600;
for y in 0..height {
for x in 0..width {
let idx = ((y * width + x) * 4) as usize;
let base_color = [80, 80, 80, 255];
let lit_color = self.lighting.apply_lighting(
x as f32,
y as f32,
base_color
);
frame[idx..idx + 4].copy_from_slice(&lit_color);
}
}
}
}
```
### Exemplo de Pathfinding
```rust
use sevenx_engine::*;
struct PathfindingGame {
pathfinder: Pathfinder,
player_pos: GridPos,
enemy_pos: GridPos,
path: Option<Vec<GridPos>>,
}
impl GameState for PathfindingGame {
fn new() -> Self {
let mut pathfinder = Pathfinder::new(40, 30);
// Adiciona obstáculos
for x in 10..30 {
pathfinder.add_obstacle(x, 15);
}
let player_pos = GridPos::new(5, 5);
let enemy_pos = GridPos::new(35, 25);
let path = pathfinder.find_path(enemy_pos, player_pos);
Self {
pathfinder,
player_pos,
enemy_pos,
path,
}
}
fn update(&mut self, dt: f32, input: &InputHandler, _world: &mut World) {
// Move jogador
if input.is_key_just_pressed(KeyCode::ArrowRight) {
let new_pos = GridPos::new(self.player_pos.x + 1, self.player_pos.y);
if self.pathfinder.is_walkable(&new_pos) {
self.player_pos = new_pos;
self.path = self.pathfinder.find_path(self.enemy_pos, self.player_pos);
}
}
// Move inimigo ao longo do caminho
if let Some(path) = &self.path {
if path.len() > 1 {
self.enemy_pos = path[1];
}
}
}
fn draw(&mut self, _world: &World, frame: &mut [u8]) {
// Renderiza grid, caminho, jogador e inimigo
}
}
```
---
## 📚 Guias Detalhados
Para mais informações sobre as novas features:
- **3D Rendering**: Veja `3D_GUIDE.md`
- **Lighting System**: Veja `LIGHTING_GUIDE.md`
- **Pathfinding**: Veja `PATHFINDING_GUIDE.md`
---
## 🎯 Dicas de Performance v0.2.6
### Renderização 3D
- Mantenha meshes com < 1000 triângulos
- Use `backface_culling = true`
- Considere wireframe para debug
### Iluminação
- Limite a < 10 luzes ativas
- Desabilite luzes fora da tela
- Use raios menores quando possível
### Pathfinding
- Cache caminhos quando possível
- Atualize a cada 0.5s, não todo frame
- Limite distância de busca
### Post-Processing
- Combine efeitos com cuidado
- Desabilite em hardware lento
- Use intensidades moderadas