# 🎮 Guia Completo de 3D - SevenX Engine v0.2.6
## 📚 Índice
1. [Começando com 3D](#começando-com-3d)
2. [Criando Objetos 3D](#criando-objetos-3d)
3. [Câmera 3D](#câmera-3d)
4. [Renderização](#renderização)
5. [Partículas 3D](#partículas-3d)
6. [Shaders 3D](#shaders-3d)
7. [Exemplo Completo](#exemplo-completo)
---
## 🚀 Começando com 3D
### Estrutura Básica
```rust
use sevenx_engine::*;
use sevenx_engine::world::World;
struct Jogo3D {
renderer3d: Renderer3D,
cube: Mesh3D,
}
impl GameState for Jogo3D {
fn new() -> Self {
// Cria renderer 3D
let renderer3d = Renderer3D::new(800, 600);
// Cria um cubo
let cube = Mesh3D::cube(2.0);
Self { renderer3d, cube }
}
fn update(&mut self, dt: f32, input: &sevenx_engine::input::InputHandler, _world: &mut World) {
// Sua lógica aqui
}
fn draw(&mut self, _world: &World, frame: &mut [u8]) {
// Limpa tela
for pixel in frame.chunks_exact_mut(4) {
pixel.copy_from_slice(&[20, 30, 50, 255]);
}
// Renderiza o cubo
self.renderer3d.render_mesh(&self.cube, frame, 800, 600);
}
}
fn main() {
Engine::new().run::<Jogo3D>();
}
```
---
## 📦 Criando Objetos 3D
### Vec3 - Vetores 3D
```rust
use sevenx_engine::Vec3;
// Criar vetor
let pos = Vec3::new(1.0, 2.0, 3.0);
// Vetor zero
let zero = Vec3::zero();
// Operações
let length = pos.length(); // Comprimento
let normalized = pos.normalize(); // Normalizar
let dot = pos.dot(&other); // Produto escalar
let cross = pos.cross(&other); // Produto vetorial
```
### Mesh3D - Geometria 3D
#### Criar Cubo
```rust
// Cubo simples
let cube = Mesh3D::cube(2.0); // Tamanho 2.0
// Cubo com posição
let mut cube = Mesh3D::cube(2.0);
cube.position = Vec3::new(0.0, 0.0, 0.0);
// Cubo com rotação
cube.rotation = Vec3::new(0.0, 0.5, 0.0); // Radianos
// Cubo com escala
cube.scale = Vec3::new(1.0, 2.0, 1.0); // Alongado em Y
```
#### Criar Esfera
```rust
// Esfera simples
let sphere = Mesh3D::sphere(1.0, 16, 16);
// Parâmetros: raio, segmentos horizontais, segmentos verticais
// Esfera com posição
let mut sphere = Mesh3D::sphere(1.0, 16, 16);
sphere.position = Vec3::new(5.0, 0.0, 0.0);
```
#### Modificar Cores
```rust
let mut cube = Mesh3D::cube(2.0);
// Mudar cor de todos os vértices
for vertex in &mut cube.vertices {
vertex.color = [255, 0, 0, 255]; // Vermelho
}
```
#### Transformações
```rust
let mut obj = Mesh3D::cube(2.0);
// Posição (translação)
obj.position = Vec3::new(x, y, z);
// Rotação (em radianos)
obj.rotation.x = 0.5; // Rotação em X
obj.rotation.y = 1.0; // Rotação em Y
obj.rotation.z = 0.0; // Rotação em Z
// Escala
obj.scale = Vec3::new(2.0, 1.0, 1.0); // 2x em X, normal em Y e Z
```
---
## 📷 Câmera 3D
### Criar Câmera
```rust
use sevenx_engine::Camera3D;
// Câmera básica
let camera = Camera3D::new(800, 600);
// Câmera com posição e alvo
let mut camera = Camera3D::new(800, 600);
camera.position = Vec3::new(0.0, 5.0, 10.0); // Posição da câmera
camera.look_at(Vec3::zero()); // Olha para origem
```
### Controlar Câmera
```rust
// No update
fn update(&mut self, dt: f32, input: &sevenx_engine::input::InputHandler, _world: &mut World) {
// Mover câmera
if input.is_key_pressed(KeyCode::KeyW) {
self.renderer3d.camera.position.z -= 5.0 * dt;
}
if input.is_key_pressed(KeyCode::KeyS) {
self.renderer3d.camera.position.z += 5.0 * dt;
}
if input.is_key_pressed(KeyCode::KeyA) {
self.renderer3d.camera.position.x -= 5.0 * dt;
}
if input.is_key_pressed(KeyCode::KeyD) {
self.renderer3d.camera.position.x += 5.0 * dt;
}
// Subir/Descer
if input.is_key_pressed(KeyCode::KeyQ) {
self.renderer3d.camera.position.y += 5.0 * dt;
}
if input.is_key_pressed(KeyCode::KeyE) {
self.renderer3d.camera.position.y -= 5.0 * dt;
}
}
```
### Câmera FPS (First Person)
```rust
struct FPSCamera {
position: Vec3,
yaw: f32, // Rotação horizontal
pitch: f32, // Rotação vertical
}
impl FPSCamera {
fn update_camera(&self, renderer: &mut Renderer3D) {
renderer.camera.position = self.position;
let target = Vec3::new(
self.position.x + self.yaw.sin(),
self.position.y + self.pitch,
self.position.z + self.yaw.cos(),
);
renderer.camera.look_at(target);
}
fn move_forward(&mut self, amount: f32) {
self.position.x += self.yaw.sin() * amount;
self.position.z += self.yaw.cos() * amount;
}
fn move_right(&mut self, amount: f32) {
let right_yaw = self.yaw + std::f32::consts::FRAC_PI_2;
self.position.x += right_yaw.sin() * amount;
self.position.z += right_yaw.cos() * amount;
}
}
```
---
## 🎨 Renderização
### Renderer3D
```rust
// Criar renderer
let mut renderer3d = Renderer3D::new(800, 600);
// Configurações
renderer3d.wireframe = false; // Sólido ou wireframe
renderer3d.backface_culling = true; // Culling de faces traseiras
// Renderizar mesh
renderer3d.render_mesh(&mesh, frame, 800, 600);
```
### Múltiplos Objetos
```rust
struct Cena3D {
renderer3d: Renderer3D,
objetos: Vec<Mesh3D>,
}
impl Cena3D {
fn draw(&mut self, frame: &mut [u8]) {
// Limpa tela
for pixel in frame.chunks_exact_mut(4) {
pixel.copy_from_slice(&[20, 30, 50, 255]);
}
// Renderiza todos os objetos
for obj in &self.objetos {
self.renderer3d.render_mesh(obj, frame, 800, 600);
}
}
}
```
### Wireframe vs Sólido
```rust
// Toggle wireframe com SPACE
if input.is_key_pressed(KeyCode::Space) {
self.renderer3d.wireframe = !self.renderer3d.wireframe;
}
```
---
## ✨ Partículas 3D
### Criar Sistema
```rust
use sevenx_engine::ParticleSystem3D;
let mut particles = ParticleSystem3D::new(500);
particles.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
particles.explosion(position);
// Fogo
particles.fire(position);
// Magia
particles.magic(position);
// Fumaça
particles.smoke(position);
// Faíscas
particles.sparkles(position);
// Rastro
let direction = Vec3::new(1.0, 0.0, 0.0);
particles.trail(position, direction);
```
### Partículas Customizadas
```rust
use sevenx_engine::Particle3D;
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 RGBA
2.0, // Vida (segundos)
)
.with_acceleration(Vec3::new(0.0, -5.0, 0.0))
.with_rotation(0.0, 5.0)
.with_scale(1.0, -0.3)
.with_turbulence(0.2);
particles.particles.push(particle);
```
### Atualizar e Renderizar
```rust
// No update
particles.update(dt);
// No draw
renderer3d.render_particles(&particles, frame, 800, 600);
```
---
## 🎭 Shaders 3D
### Iluminação Phong
```rust
use sevenx_engine::{PhongShader, Light3D, Material};
// 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
));
// Usar com renderer
let mut renderer = Renderer3D::new(800, 600)
.with_lighting(phong);
```
### Materiais
```rust
use sevenx_engine::Material;
// Material padrão
let default_mat = Material::default();
// Material metálico
let metal = Material::metal();
// Material plástico
let plastic = Material::plastic();
```
### Fresnel (Rim Lighting)
```rust
use sevenx_engine::FresnelShader;
let fresnel = FresnelShader::new();
// Cria borda brilhante nos objetos
```
### Fog (Neblina)
```rust
use sevenx_engine::FogShader;
let mut fog = FogShader::new();
fog.fog_color = [200, 200, 220, 255];
fog.fog_start = 10.0;
fog.fog_end = 50.0;
fog.fog_density = 0.05;
```
### Toon Shader (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]);
```
---
## 🎮 Exemplo Completo
### Jogo 3D com Tudo
```rust
use sevenx_engine::*;
use sevenx_engine::world::World;
struct Jogo3DCompleto {
renderer3d: Renderer3D,
cubes: Vec<Mesh3D>,
particles: ParticleSystem3D,
camera_pos: Vec3,
rotation: f32,
}
impl GameState for Jogo3DCompleto {
fn new() -> Self {
// Renderer
let mut renderer3d = Renderer3D::new(800, 600);
renderer3d.camera.position = Vec3::new(0.0, 5.0, 15.0);
renderer3d.camera.look_at(Vec3::zero());
renderer3d.wireframe = false;
// Criar cubos
let mut cubes = Vec::new();
for i in 0..5 {
let mut cube = Mesh3D::cube(2.0);
cube.position = Vec3::new(i as f32 * 3.0 - 6.0, 0.0, 0.0);
// Cores diferentes
let color = match i {
0 => [255, 0, 0, 255],
1 => [0, 255, 0, 255],
2 => [0, 0, 255, 255],
3 => [255, 255, 0, 255],
_ => [255, 0, 255, 255],
};
for vertex in &mut cube.vertices {
vertex.color = color;
}
cubes.push(cube);
}
// Partículas
let particles = ParticleSystem3D::new(500);
Self {
renderer3d,
cubes,
particles,
camera_pos: Vec3::new(0.0, 5.0, 15.0),
rotation: 0.0,
}
}
fn update(&mut self, dt: f32, input: &sevenx_engine::input::InputHandler, _world: &mut World) {
// Rotaciona cubos
self.rotation += dt;
for cube in &mut self.cubes {
cube.rotation.y = self.rotation;
}
// Controles de câmera
let speed = 10.0;
if input.is_key_pressed(KeyCode::KeyW) {
self.camera_pos.z -= speed * dt;
}
if input.is_key_pressed(KeyCode::KeyS) {
self.camera_pos.z += speed * dt;
}
if input.is_key_pressed(KeyCode::KeyA) {
self.camera_pos.x -= speed * dt;
}
if input.is_key_pressed(KeyCode::KeyD) {
self.camera_pos.x += speed * dt;
}
self.renderer3d.camera.position = self.camera_pos;
self.renderer3d.camera.look_at(Vec3::zero());
// Explosão com SPACE
if input.is_key_pressed(KeyCode::Space) {
self.particles.explosion(Vec3::zero());
}
// Toggle wireframe
if input.is_key_pressed(KeyCode::KeyF) {
self.renderer3d.wireframe = !self.renderer3d.wireframe;
}
// Atualiza partículas
self.particles.update(dt);
}
fn draw(&mut self, _world: &World, frame: &mut [u8]) {
// Céu gradiente
for y in 0..600 {
let sky_color = 20 + (y as f32 / 600.0 * 60.0) as u8;
for x in 0..800 {
let idx = ((y * 800 + x) * 4) as usize;
if idx + 3 < frame.len() {
frame[idx] = sky_color / 2;
frame[idx + 1] = sky_color / 2;
frame[idx + 2] = sky_color;
frame[idx + 3] = 255;
}
}
}
// Renderiza cubos
for cube in &self.cubes {
self.renderer3d.render_mesh(cube, frame, 800, 600);
}
// Renderiza partículas
self.renderer3d.render_particles(&self.particles, frame, 800, 600);
}
}
fn main() {
let config = EngineConfig::default()
.with_title("Jogo 3D Completo")
.with_size(800, 600);
Engine::with_config(config).run::<Jogo3DCompleto>();
}
```
### Controles
- **WASD**: Mover câmera
- **SPACE**: Explosão de partículas
- **F**: Toggle wireframe
---
## 💡 Dicas de Performance
### Otimizações
- Mantenha meshes com < 1000 triângulos
- Use `backface_culling = true`
- Limite partículas 3D a 200-500
- Use wireframe para debug
### Boas Práticas
- Comece com objetos simples (cubos)
- Use wireframe para ver a estrutura
- Teste com poucos objetos primeiro
- Adicione complexidade gradualmente
---
## 🐛 Troubleshooting
### Nada aparece na tela?
- Verifique a posição da câmera (deve estar longe o suficiente)
- Verifique a posição dos objetos
- Tente usar wireframe
- Aumente o tamanho dos objetos
### Objetos muito pequenos?
```rust
// Aumente o tamanho
let cube = Mesh3D::cube(5.0); // Maior
// Ou aproxime a câmera
camera.position.z = 5.0; // Mais perto
```
### Performance ruim?
- Reduza número de objetos
- Reduza partículas
- Use backface culling
- Simplifique meshes
---
## 📚 Exemplos Incluídos
```bash
# 3D básico
cargo run --example 3d_demo_simple
# 3D com partículas
cargo run --example 3d_demo
# FPS completo
cargo run --example fps_3d_game
```
---
## 🎓 Próximos Passos
1. Comece com o exemplo básico
2. Adicione movimento
3. Adicione partículas
4. Experimente shaders
5. Crie seu próprio jogo!
**Boa sorte criando em 3D! 🚀✨**