Especialista em Bevy ECS

Visão Geral

Um guia para construir lógica de jogo de alta performance usando a arquitetura ECS orientada a dados do Bevy. Aprenda como estruturar sistemas, otimizar consultas, gerenciar recursos e alavancar a execução paralela.

Quando Usar Esta Habilidade

• Use ao desenvolver jogos com o motor Bevy em Rust.
• Use ao projetar sistemas de jogo que precisam rodar em paralelo.
• Use ao otimizar a performance do jogo minimizando falhas de cache.
• Use ao refatorar lógica orientada a objetos para padrões ECS orientados a dados.

Guia Passo a Passo

1. Definindo Componentes

Use structs simples para dados. Importe bevy::prelude::*; adicione Reflect apenas quando a reflexão/inspeção for necessária. Os trechos são alternativas e não duplicam definições de Player/Velocity em um único escopo.

#[derive(Component, Reflect, Default)]
#[reflect(Component)]
struct Velocity {
    x: f32,
    y: f32,
}

#[derive(Component)]
struct Player;

2. Escrevendo Sistemas

Sistemas são funções Rust regulares que consultam componentes.

fn movement_system(
    time: Res<Time>,
    mut query: Query<(&mut Transform, &Velocity), With<Player>>,
) {
    for (mut transform, velocity) in &mut query {
        transform.translation.x += velocity.x * time.delta_secs();
        transform.translation.y += velocity.y * time.delta_secs();
    }
}

3. Gerenciando Recursos

Use Resource para dados globais (pontuação, estado do jogo).

#[derive(Resource, Default)]
struct GameState {
    score: u32,
}

fn score_system(mut game_state: ResMut<GameState>) {
    game_state.score += 10;
}

O sistema de pontuação de exemplo incrementa a cada Update; use eventos de gameplay ou um timer explícito para pontuação significativa, em vez de implicar comportamento de pontuação independente da taxa de quadros.

4. Agendando Sistemas

Adicione sistemas ao construtor App, definindo a ordem de execução se necessário.

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .init_resource::<GameState>()
        .add_systems(Update, (movement_system, score_system).chain())
        .run();
}

Exemplos

Exemplo 1: Spawnando Entidades com Componente Obrigatório

use bevy::prelude::*;

#[derive(Component, Reflect, Default)]
#[require(Velocity, Sprite)]
struct Player;

#[derive(Component, Default)]
struct Velocity {
    x: f32,
    y: f32,
}

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn((
        Player,
        Velocity { x: 10.0, y: 0.0 },
        Sprite::from_image(asset_server.load("player.png")), 
    ));
}

Exemplo 2: Filtros de Consulta

Use With e Without para filtrar entidades eficientemente.

fn enemy_behavior(
    query: Query<&Transform, (With<Enemy>, Without<Dead>)>,
) {
    for transform in &query {
        // Only active enemies processed here
    }
}

Melhores Práticas

• ✅ Faça: Use filtros Query (With, Without, Changed) para reduzir a contagem de iteração.
• ✅ Faça: Prefira Res em vez de ResMut quando o acesso somente leitura for suficiente para permitir a execução paralela.
• ✅ Faça: Use Bundle para spawnar entidades complexas atomicamente.
• ❌ Não faça: Armazene lógica pesada dentro de Componentes; mantenha-os como dados puros.
• ❌ Não faça: Use RefCell ou mutabilidade interna dentro de componentes; prefira o empréstimo normal do ECS; qualquer design de mutabilidade interna ainda precisa de Send/Sync válidos e uma razão clara de sincronização.

Solução de Problemas

Problema: Pânico do sistema com erro "Conflito". Solução: O agendador normalmente ordena sistemas conflitantes. Bevy B0001 frequentemente se refere a consultas incompatíveis dentro de um único sistema; use filtros disjoint With/Without ou ParamSet conforme apropriado. Encadear dois sistemas não repara parâmetros conflitantes dentro de um sistema. Veja Bevy B0001.

Limitações

• Fixe a versão do Bevy do projeto e verifique seu guia de migração/API. Exemplos atuais usam delta_secs e componentes obrigatórios; versões mais antigas do Bevy podem diferir. Enemy/Dead são marcadores de componente de propriedade da aplicação e player.png é um asset da aplicação, não um arquivo empacotado. Nenhum benchmark de compilação/performance do motor é reivindicado aqui.
• Não trate a saída como substituta para validação específica do ambiente, testes ou revisão de especialistas.
• Pare e peça esclarecimentos se os inputs necessários, permissões, limites de segurança ou critérios de sucesso estiverem ausentes.