docs/bevy/examples/asset/asset_settings.rs 3.6 K · 78 lines · raw · history

1 //! This example demonstrates the usage of '.meta' files and [`LoadBuilder::with_settings`](bevy::asset::LoadBuilder::with_settings) to override the default settings for loading an asset
2
3 use bevy::{
4 image::{ImageLoaderSettings, ImageSampler},
5 prelude::*,
6 };
7
8 fn main() {
9 App::new()
10 .add_plugins(
11 // This just tells the asset server to look in the right examples folder
12 DefaultPlugins.set(AssetPlugin {
13 file_path: "examples/asset/files".to_string(),
14 ..Default::default()
15 }),
16 )
17 .add_systems(Startup, setup)
18 .run();
19 }
20
21 fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
22 // Without any .meta file specifying settings, the default sampler [ImagePlugin::default()] is used for loading images.
23 // If you are using a very small image and rendering it larger like seen here, the default linear filtering will result in a blurry image.
24 // Useful note: The default sampler specified by the ImagePlugin is *not* the same as the default implementation of sampler. This is why
25 // everything uses linear by default but if you look at the default of sampler, it uses nearest.
26 commands.spawn((
27 Sprite {
28 image: asset_server.load("bevy_pixel_dark.png"),
29 custom_size: Some(Vec2 { x: 160.0, y: 120.0 }),
30 ..Default::default()
31 },
32 Transform::from_xyz(-100.0, 0.0, 0.0),
33 ));
34
35 // When a .meta file is added with the same name as the asset and a '.meta' extension
36 // you can (and must) specify all fields of the asset loader's settings for that
37 // particular asset, in this case [ImageLoaderSettings]. Take a look at
38 // examples/asset/files/bevy_pixel_dark_with_meta.png.meta
39 // for the format and you'll notice, the only non-default option is setting Nearest
40 // filtering. This tends to work much better for pixel art assets.
41 // A good reference when filling this out is to check out [ImageLoaderSettings::default()]
42 // and follow to the default implementation of each fields type.
43 // https://docs.rs/bevy/latest/bevy/image/struct.ImageLoaderSettings.html
44 commands.spawn((
45 Sprite {
46 image: asset_server.load("bevy_pixel_dark_with_meta.png"),
47 custom_size: Some(Vec2 { x: 160.0, y: 120.0 }),
48 ..Default::default()
49 },
50 Transform::from_xyz(100.0, 0.0, 0.0),
51 ));
52
53 // Another option is to use the LoadBuilder::with_settings function.
54 // With this you can specify the same settings upon loading your asset with a
55 // couple of differences. A big one is that you aren't required to set *every*
56 // setting, just modify the ones that you need. It works by passing in a function
57 // (in this case an anonymous closure) that takes a reference to the settings type
58 // that is then modified in the function.
59 // Do note that if you want to load the same asset with different settings, the
60 // settings changes from any loads after the first of the same asset will be ignored.
61 // This is why this one loads a differently named copy of the asset instead of using
62 // same one as without a .meta file.
63 commands.spawn((
64 Sprite {
65 image: asset_server
66 .load_builder()
67 .with_settings(|settings: &mut ImageLoaderSettings| {
68 settings.sampler = ImageSampler::nearest();
69 })
70 .load("bevy_pixel_dark_with_settings.png"),
71 custom_size: Some(Vec2 { x: 160.0, y: 120.0 }),
72 ..Default::default()
73 },
74 Transform::from_xyz(0.0, 150.0, 0.0),
75 ));
76
77 commands.spawn(Camera2d);
78 }