# 📖 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
### Criar Sistema
```rust
use sevenx_engine::{ParticleSystem, ParticleConfig};
let mut particles = ParticleSystem::new(500); // Max 500 partículas
```
### Emitir Partículas
```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
let config = ParticleConfig::sparkle();
particles.emit_burst(x, y, 40, config);
```
### Atualizar e Renderizar
```rust
// No update
particles.update(dt, world.gravity);
// No draw
particles.render(pixels, 0.0, 0.0, 800, 600);
```
---
## 💬 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);
```
---
## 💡 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! 🚀**