Assets & Scenes

Carregue texturas, modelos e cenas no Bevy - handles, estados de assets e fluxos de trabalho de hot-reload.

Receita

fn setup(asset_server: Res<AssetServer>, mut commands: Commands) {
    let texture: Handle<Image> = asset_server.load("sprites/player.png");
    commands.spawn(Sprite::from_image(texture));
}

Quando usar isso:

Qualquer jogo com arte/áudio não gerado proceduralmente
Composição de níveis via arquivos de cena em vez de spawns apenas por código
Iteração em assets sem reiniciar o jogo (hot-reload de desenvolvimento)
Separação do pipeline de conteúdo do código de gameplay em Rust

Exemplo de Trabalho

use bevy::prelude::*;
 
fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Startup, load_scene)
        .add_systems(Update, watch_loading)
        .run();
}
 
#[derive(Resource)]
struct LevelHandle(Handle<Scene>);
 
fn load_scene(mut commands: Commands, asset_server: Res<AssetServer>) {
    let scene = asset_server.load("scenes/level1.scn.ron");
    commands.insert_resource(LevelHandle(scene));
}
 
fn watch_loading(
    level: Res<LevelHandle>,
    asset_server: Res<AssetServer>,
    mut scenes: ResMut<Assets<Scene>>,
    mut done: Local<bool>,
    mut commands: Commands,
) {
    if *done {
        return;
    }
    match asset_server.load_state(&level.0) {
        bevy::asset::LoadState::Loaded => {
            if scenes.get(&level.0).is_some() {
                commands.spawn(DynamicSceneRoot(level.0.clone()));
                *done = true;
            }
        }
        bevy::asset::LoadState::Failed(err) => eprintln!("load failed: {err:?}"),
        _ => {}
    }
}

O que isso demonstra:

Handle de cena armazenado como recurso
Verificação de LoadState antes de gerar DynamicSceneRoot
Registro de falhas para assets ausentes

Mergulho Profundo

Como Funciona

AssetServer a thread de IO carrega arquivos em armazenamentos Assets<T> tipados.
Handle<T> referência semelhante a UUID, segura para clonar e armazenar em componentes.
Arquivos de Scene listam componentes refletidos para gerar a árvore de entidades.
File watcher (dev) aciona o recarregamento quando o disco muda.

Layout da Pasta

Caminho	Conteúdo
`assets/sprites/`	Texturas PNG/WebP
`assets/audio/`	OGG/WAV
`assets/scenes/`	Níveis `.scn.ron`
`assets/models/`	3D GLTF/OBJ

Armadilhas

Caminho de asset com maiúsculas/minúsculas incorreto em builds Linux - funciona no macOS, falha em CI. Correção: caminhos consistentes em minúsculas.
Gerar antes da conclusão do carregamento - entidades invisíveis. Correção: controlar por LoadState::Loaded.
Texturas enormes não otimizadas - explosão de memória da GPU. Correção: comprimir, atlas, mipmaps.
Componentes não refletidos em cenas - omitidos silenciosamente. Correção: registrar Reflect em componentes personalizados.
Hot-reload em release - comportamento não intencional. Correção: desabilitar o watcher em builds de release.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Incorporar com `include_bytes!`	Binário de jam minúsculo	Pipeline de arte grande
Arquivos de pacote externos	DRM ou DLC	Mods simples abertos
Apenas Procedural	Brinquedos de shader	Conteúdo orientado por artista
Crate de streaming de assets	Mundo aberto	Níveis lineares pequenos

FAQs

Carregamento GLTF?

SceneRoot do caminho glTF gera malhas/materiais - caminho 3D comum em exemplos do Bevy.

Assets de áudio?

asset_server.load("audio/hit.ogg") -> Handle<AudioSource> em componentes AudioPlayer.

Rótulos de asset?

Estilo asset_server.load("player.png#Texture") para arquivos multi-asset como GLTF.

Tela de pré-carregamento?

Coletar handles no estado do menu; transicionar quando todos is_loaded_with_dependencies.

Modding?

Carregar assets do diretório do usuário com montagem separada de AssetSource - padrão de plugin avançado.

Versionamento de arte?

Hashear nomes de arquivos de conteúdo ou manifest JSON para invalidar cache em builds enviados.

Cena vs prefab?

Cenas são hierarquias serializadas; prefabs frequentemente funções de spawn Bundle personalizadas em código.

Pressão de memória?

Soltar handles quando o nível é descarregado; Assets::remove entradas não utilizadas em transições de cena.

CI sem GPU?

Usar plugins headless/minimal e simular handles para testes de lógica.

Integração Bevy?

Núcleo da arquitetura do plugin de assets do Bevy Engine.

Relacionados

Bevy Engine - Spawning ECS
Performance para Jogos - orçamentos de textura
Noções Básicas de Desenvolvimento de Jogos - exemplo de spawn de sprite
Física e Áudio - handles de áudio

Versões da Pilha: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.

Assets & Scenes

Carregue texturas, modelos e cenas no Bevy - handles, estados de assets e fluxos de trabalho de hot-reload.

Receita

fn setup(asset_server: Res<AssetServer>, mut commands: Commands) {
    let texture: Handle<Image> = asset_server.load("sprites/player.png");
    commands.spawn(Sprite::from_image(texture));
}

Quando usar isso:

Qualquer jogo com arte/áudio não gerado proceduralmente
Composição de níveis via arquivos de cena em vez de spawns apenas por código
Iteração em assets sem reiniciar o jogo (hot-reload de desenvolvimento)
Separação do pipeline de conteúdo do código de gameplay em Rust

Exemplo de Trabalho

use bevy::prelude::*;
 
fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Startup, load_scene)
        .add_systems(Update, watch_loading)
        .run();
}
 
#[derive(Resource)]
struct LevelHandle(Handle<Scene>);
 
fn load_scene(mut commands: Commands, asset_server: Res<AssetServer>) {
    let scene = asset_server.load("scenes/level1.scn.ron");
    commands.insert_resource(LevelHandle(scene));
}
 
fn watch_loading(
    level: Res<LevelHandle>,
    asset_server: Res<AssetServer>,
    mut scenes: ResMut<Assets<Scene>>,
    mut done: Local<bool>,
    mut commands: Commands,
) {
    if *done {
        return;
    }
    match asset_server.load_state(&level.0) {
        bevy::asset::LoadState::Loaded => {
            if scenes.get(&level.0).is_some() {
                commands.spawn(DynamicSceneRoot(level.0.clone()));
                *done = true;
            }
        }
        bevy::asset::LoadState::Failed(err) => eprintln!("load failed: {err:?}"),
        _ => {}
    }
}

O que isso demonstra:

Handle de cena armazenado como recurso
Verificação de LoadState antes de gerar DynamicSceneRoot
Registro de falhas para assets ausentes

Mergulho Profundo

Como Funciona

AssetServer a thread de IO carrega arquivos em armazenamentos Assets<T> tipados.
Handle<T> referência semelhante a UUID, segura para clonar e armazenar em componentes.
Arquivos de Scene listam componentes refletidos para gerar a árvore de entidades.
File watcher (dev) aciona o recarregamento quando o disco muda.

Layout da Pasta

Caminho	Conteúdo
`assets/sprites/`	Texturas PNG/WebP
`assets/audio/`	OGG/WAV
`assets/scenes/`	Níveis `.scn.ron`
`assets/models/`	3D GLTF/OBJ

Armadilhas

Caminho de asset com maiúsculas/minúsculas incorreto em builds Linux - funciona no macOS, falha em CI. Correção: caminhos consistentes em minúsculas.
Gerar antes da conclusão do carregamento - entidades invisíveis. Correção: controlar por LoadState::Loaded.
Texturas enormes não otimizadas - explosão de memória da GPU. Correção: comprimir, atlas, mipmaps.
Componentes não refletidos em cenas - omitidos silenciosamente. Correção: registrar Reflect em componentes personalizados.
Hot-reload em release - comportamento não intencional. Correção: desabilitar o watcher em builds de release.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Incorporar com `include_bytes!`	Binário de jam minúsculo	Pipeline de arte grande
Arquivos de pacote externos	DRM ou DLC	Mods simples abertos
Apenas Procedural	Brinquedos de shader	Conteúdo orientado por artista
Crate de streaming de assets	Mundo aberto	Níveis lineares pequenos

FAQs

Carregamento GLTF?

SceneRoot do caminho glTF gera malhas/materiais - caminho 3D comum em exemplos do Bevy.

Assets de áudio?

asset_server.load("audio/hit.ogg") -> Handle<AudioSource> em componentes AudioPlayer.

Rótulos de asset?

Estilo asset_server.load("player.png#Texture") para arquivos multi-asset como GLTF.

Tela de pré-carregamento?

Coletar handles no estado do menu; transicionar quando todos is_loaded_with_dependencies.

Modding?

Carregar assets do diretório do usuário com montagem separada de AssetSource - padrão de plugin avançado.

Versionamento de arte?

Hashear nomes de arquivos de conteúdo ou manifest JSON para invalidar cache em builds enviados.

Cena vs prefab?

Cenas são hierarquias serializadas; prefabs frequentemente funções de spawn Bundle personalizadas em código.

Pressão de memória?

Soltar handles quando o nível é descarregado; Assets::remove entradas não utilizadas em transições de cena.

CI sem GPU?

Usar plugins headless/minimal e simular handles para testes de lógica.

Integração Bevy?

Núcleo da arquitetura do plugin de assets do Bevy Engine.

Relacionados

Bevy Engine - Spawning ECS
Performance para Jogos - orçamentos de textura
Noções Básicas de Desenvolvimento de Jogos - exemplo de spawn de sprite
Física e Áudio - handles de áudio

Versões da Pilha: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.

Assets & Scenes

Buscar na documentação

Assets & Scenes