# Guia de Uso - SevenX Engine
## Índice
1. [Conceitos Básicos](#conceitos-básicos)
2. [Sistema de Componentes](#sistema-de-componentes)
3. [Física e Movimento](#física-e-movimento)
4. [Colisões](#colisões)
5. [Câmera](#câmera)
6. [Sprites e Animações](#sprites-e-animações)
7. [Gerenciamento de Recursos](#gerenciamento-de-recursos)
## Conceitos Básicos
### Estrutura de um Jogo
Todo jogo na SevenX Engine segue esta estrutura:
```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) {
// Lógica do jogo
}
fn draw(&mut self, world: &World, pixels: &mut [u8]) {
// Desenho customizado (opcional)
}
}
fn main() {
Engine::new().run::<MeuJogo>();
}
```
### Delta Time (dt)
O `dt` representa o tempo decorrido desde o último frame em segundos. Use-o para movimentos suaves:
```rust
// Movimento independente de framerate
let speed = 100.0; // pixels por segundo
player.transform.translate(speed * dt, 0.0);
```
## Sistema de Componentes
### Transform
Controla posição, rotação e escala:
```rust
use sevenx_engine::Transform;
let mut transform = Transform::new(100.0, 200.0)
.with_scale(2.0, 2.0)
.with_rotation(std::f32::consts::PI / 4.0);
// Movimentação
transform.translate(10.0, 5.0);
// Rotação
transform.rotate(0.1);
// Acesso direto
let (x, y) = transform.position;
```
### Physics
Adiciona física realista aos objetos:
```rust
use sevenx_engine::Physics;
let physics = Physics::new()
.with_velocity(100.0, 0.0) // Velocidade inicial
.with_gravity(1.0) // Afetado pela gravidade
.with_drag(0.05); // Resistência do ar
// Aplicar força
physics.apply_force(50.0, -200.0);
```
### Collider
Define área de colisão:
```rust
use sevenx_engine::Collider;
// Collider básico
let collider = Collider::new(32.0, 32.0);
// Collider com offset
let collider = Collider::new(32.0, 32.0)
.with_offset(4.0, 8.0);
// Trigger (não bloqueia movimento)
let trigger = Collider::new(32.0, 32.0)
.as_trigger();
```
## Física e Movimento
### Movimento Básico
```rust
// Movimento direto (sem física)
if input.is_key_pressed(KeyCode::ArrowRight) {
player.transform.translate(speed * dt, 0.0);
}
```
### Movimento com Física
```rust
// Cria objeto com física
let mut player = GameObject::new(100.0, 100.0, ObjectType::Player)
.with_physics(Physics::new()
.with_gravity(1.0)
.with_drag(0.1));
// No update, aplica forças
if input.is_key_pressed(KeyCode::Space) {
if let Some(physics) = &mut player.physics {
physics.apply_force(0.0, -500.0); // Pulo
}
}
```
### Gravidade
```rust
// Configurar gravidade global
let config = EngineConfig::new()
.with_gravity(980.0); // pixels/s²
// Objeto afetado pela gravidade
let obj = GameObject::new(x, y, ObjectType::Player)
.with_physics(Physics::new().with_gravity(1.0));
// Objeto não afetado
let obj = GameObject::new(x, y, ObjectType::Player)
.with_physics(Physics::new().with_gravity(0.0));
```
## Colisões
### Detecção Básica
```rust
// Verifica colisão entre dois objetos
if let (Some(rect1), Some(rect2)) = (obj1.get_collision_rect(), obj2.get_collision_rect()) {
if rect1.intersects(&rect2) {
println!("Colisão detectada!");
}
}
```
### Triggers
Triggers detectam colisões mas não bloqueiam movimento (útil para itens colecionáveis):
```rust
let coin = GameObject::new(x, y, ObjectType::Coin)
.with_collider(Collider::new(32.0, 32.0).as_trigger());
```
### Resposta a Colisão
```rust
// Calcula sobreposição
if let Some((overlap_x, overlap_y)) = rect1.overlap(&rect2) {
// Empurra objeto para fora da colisão
if overlap_x < overlap_y {
player.transform.position.0 += overlap_x;
} else {
player.transform.position.1 += overlap_y;
}
}
```
## Câmera
### Seguir Jogador
```rust
// No update do GameState
if let Some(player) = world.game_objects.iter()
.find(|obj| obj.object_type == ObjectType::Player)
{
let (px, py) = player.transform.position;
// Acesso à câmera (precisa ser passado do Engine)
// camera.follow(px, py, 5.0, dt);
}
```
### Zoom
```rust
camera.set_zoom(2.0); // 2x zoom
camera.set_zoom(0.5); // Zoom out
```
### Conversão de Coordenadas
```rust
// Mundo para tela
let (screen_x, screen_y) = camera.world_to_screen(world_x, world_y);
// Tela para mundo
let (world_x, world_y) = camera.screen_to_world(screen_x, screen_y);
```
## Sprites e Animações
### Carregar Sprite Sheet
```rust
use sevenx_engine::sprite::SpriteSheet;
let sprite = SpriteSheet::load("assets/player.png", 32, 32)?;
```
### Configurar Animações
```rust
use sevenx_engine::animation::Animation;
use sevenx_engine::game_object::{Direction, PlayerAction};
let mut player = GameObject::new(x, y, ObjectType::Player);
// Adiciona sprite sheets
player.sheets.insert(PlayerAction::Idle, idle_sheet);
player.sheets.insert(PlayerAction::Walk, walk_sheet);
// Configura animações (linha, num_frames, delay)
player.animations.insert(Direction::Down, Animation::new(0, 4, 0.15));
player.animations.insert(Direction::Up, Animation::new(1, 4, 0.15));
player.animations.insert(Direction::Left, Animation::new(2, 4, 0.15));
player.animations.insert(Direction::Right, Animation::new(3, 4, 0.15));
```
### Controlar Animação
```rust
// Muda ação
player.current_action = PlayerAction::Walk;
// Muda direção
player.facing_direction = Direction::Right;
// A animação é atualizada automaticamente pelo World
```
## Gerenciamento de Recursos
### Resource Manager
```rust
use sevenx_engine::ResourceManager;
let mut resources = ResourceManager::new();
// Carrega sprites (são cacheados)
resources.load_sprite_sheet("player_idle", "assets/idle.png", 32, 32)?;
resources.load_sprite_sheet("enemy_walk", "assets/enemy.png", 48, 48)?;
// Reutiliza do cache
if let Some(sprite) = resources.get_sprite_sheet("player_idle") {
// Usa o sprite
}
// Remove do cache
resources.unload_sprite_sheet("enemy_walk");
// Limpa tudo
resources.clear();
```
## Dicas e Boas Práticas
### Performance
1. **Use Z-Index**: Ordene objetos por profundidade para renderização correta
2. **Desative Objetos**: Use `object.active = false` em vez de remover
3. **Cache de Recursos**: Sempre use ResourceManager para sprites reutilizados
4. **Cleanup**: Remova objetos inativos periodicamente com `world.cleanup_inactive()`
### Organização
```rust
// Separe lógica em funções
impl MyGame {
fn handle_player_input(&mut self, input: &InputHandler, world: &mut World) {
// ...
}
fn spawn_enemies(&mut self, world: &mut World) {
// ...
}
fn check_game_over(&self, world: &World) -> bool {
// ...
}
}
impl GameState for MyGame {
fn update(&mut self, dt: f32, input: &InputHandler, world: &mut World) {
self.handle_player_input(input, world);
self.spawn_enemies(world);
if self.check_game_over(world) {
// Reset ou game over
}
}
}
```
### Debug
```rust
// Imprime informações úteis
println!("FPS: {}", 1.0 / dt);
println!("Player pos: {:?}", player.transform.position);
println!("Objects: {}", world.game_objects.len());
```
## Exemplos Completos
Veja os exemplos na pasta `examples/`:
- `jogo_teste.rs` - Exemplo básico de movimento
- `physics_demo.rs` - Demo de física e gravidade