Bevy Version: | 0.10 | (current) |
---|
Configuring Bevy
Bevy is very modular and configurable. It is implemented as many separate cargo crates, allowing you to remove the parts you don't need. Higher-level functionality is built on top of lower-level foundational crates, and can be disabled or replaced with alternatives.
The lower-level core crates (like the Bevy ECS) can also be used completely standalone, or integrated into otherwise non-Bevy projects.
Bevy Cargo Features
In Bevy projects, you can enable/disable various parts of Bevy using cargo features.
Many common features are enabled by default. If you want to disable some of them, note that, unfortunately, Cargo does not let you disable individual default features, so you need to disable all default bevy features and re-enable the ones you need.
Here is how you might configure your Bevy:
[dependencies.bevy]
version = "0.10"
# Disable the default features if there are any that you do not want
default-features = false
features = [
# These are the default features:
# (re-enable whichever you like)
# Bevy functionality:
"bevy_asset", # Assets management
"bevy_audio", # Builtin audio
"bevy_gilrs", # Gamepad input support
"bevy_scene", # Scenes management
"bevy_winit", # Window management
"bevy_render", # Rendering framework core
"bevy_core_pipeline", # Common rendering abstractions
"bevy_sprite", # 2D (sprites) rendering
"bevy_pbr", # 3D (physically-based) rendering
"bevy_gltf", # GLTF 3D assets format support
"bevy_text", # Text/font rendering
"bevy_ui", # UI toolkit
"animation", # Animation support
"tonemapping_luts", # Support different camera Tonemapping modes (embeds extra data)
"filesystem_watcher", # Asset hot-reloading
"x11", # Linux: Support X11 windowing system
"android_shared_stdcxx", # For Android builds, use shared C++ library
# File formats:
"png", # PNG image format for simple 2D images
"hdr", # HDR images
"ktx2", # Preferred format for GPU textures
"zstd", # ZSTD compression support in KTX2 files
"vorbis", # Audio: OGG Vorbis
# These are other features that may be of interest:
# (add any of these that you need)
# Bevy functionality:
"wayland", # Linux: Support Wayland windowing system
"subpixel_glyph_atlas", # Subpixel antialiasing for text/fonts
"serialize", # Support for `serde` Serialize/Deserialize
"bevy_dynamic_plugin", # Support for loading of `DynamicPlugin`s
"accesskit_unix", # AccessKit integration for UI Accessibility
# File formats:
"dds", # Alternative DirectX format for GPU textures, instead of KTX2
"jpeg", # JPEG lossy format for 2D photos
"bmp", # Uncompressed BMP image format
"tga", # Truevision Targa image format
"exr", # OpenEXR advanced image format
"basis-universal", # Basis Universal GPU texture compression format
"flac", # Audio: FLAC lossless format
"mp3", # Audio: MP3 format (not recommended)
"wav", # Audio: Uncompressed WAV
"symphonia-all", # All Audio formats supported by the Symphonia library
# Development/Debug features:
"dynamic_linking", # Dynamic linking for faster compile-times
"trace", # Enable tracing for performance measurement
"detailed_trace", # Make traces more verbose
"trace_tracy", # Tracing using `tracy`
"trace_chrome", # Tracing using the Chrome format
"wgpu_trace", # WGPU/rendering tracing
]
(See here for a full list of Bevy's cargo features.)
Graphics / Rendering
For a graphical application or game (most Bevy projects), you can include
bevy_winit
and your selection of Rendering features. For
Linux support, you need at least one of x11
or wayland
.
bevy_render
and bevy_core_pipeline
are required for any application using
Bevy rendering.
If you only need 2D and no 3D, add bevy_sprite
.
If you only need 3D and no 2D, add bevy_pbr
. If you are loading 3D models
from GLTF files, add bevy_gltf
.
If you are using Bevy UI, you need bevy_text
and bevy_ui
.
If you don't need any graphics (like for a dedicated game server, scientific simulation, etc.), you may remove all of these features.
Audio
Bevy's audio is very limited in functionality. If you want something with more
features, you can use the bevy_kira_audio
plugin
instead. Disable bevy_audio
and vorbis
.
File Formats
You can use the relevant cargo features to enable/disable support for loading assets with various different file formats.
See here for more information.
Input Devices
If you do not care about gamepad (controller/joystick)
support, you can disable bevy_gilrs
.
Linux Windowing Backend
On Linux, you can choose to support X11, Wayland,
or both. Only x11
is enabled by default, as it is the legacy system
that should be compatible with most/all distributions, to make your builds
smaller and compile faster. You might want to additionally enable wayland
,
to fully and natively support modern Linux environments. This will add a few
extra transitive dependencies to your project.
Development Features
While you are developing your project, these features might be useful:
Asset hot-reloading
The filesystem_watcher
feature controls support for hot-reloading of
assets, supported on desktop platforms.
Dynamic Linking
dynamic_linking
causes Bevy to be built and linked as a shared/dynamic
library. This will make incremental builds much faster.
This is only supported on desktop platforms. Known to work very well on Linux. Windows and macOS are also supported, but are less tested and have had issues in the past.
Do not enable this for release builds you intend to publish to other people, unless you have a very good special reason to and you know what you are doing. It introduces unneeded complexity (you need to bundle extra files) and potential for things to not work correctly. Use this only during development.
For this reason, it may be convenient to specify the feature as a commandline
option to cargo
, instead of putting it in your Cargo.toml
. Simply run your
project like this:
cargo run --features bevy/dynamic_linking
You could also add this to your IDE/editor configuration.
Tracing
The features trace
and wgpu_trace
may be useful for profiling and
diagnosing performance issues.
trace_chrome
and trace_tracy
choose the backend you want to use to
visualize the traces.
See Bevy's official docs on profiling to learn more.