Performance
How to keep a NEO game fast: measure in release builds, write cheap systems, use parallel queries and change detection, and keep rendering within budget, including on the web.
On this page
Most performance problems are one of a few kinds: a debug build, a system that does too much work every frame, too many draws, or effects the target GPU can't afford. This page is a checklist for each. Measure before and after every change; Profiling shows how.
Measure the right build#
| Do | Why |
|---|---|
Run with --release | A debug build of your own crates can be many times slower. NEO's dev profile already optimizes dependencies, but your code isn't. |
| Watch the frame time, not only FPS | Frame time adds up linearly: 16.7 ms is 60 fps, 33.3 ms is 30 fps. See Diagnostics. |
| Turn off vsync while measuring | With PresentMode::AutoNoVsync, a fast frame isn't hidden by waiting for the display. See Windows. |
| Test the slowest target | The browser runs on one thread, and phones have far less GPU. Measure there, not only on your desktop. |
Systems#
- Do less work per frame. Use change detection (
Changed<T>,Added<T>,Ref<T>::is_changed) so a system only handles what changed. - Run systems only when needed. Run conditions such as
in_state(...),resource_changed::<T>oron_timer(...)skip a system entirely. A skipped system costs almost nothing. - Use parallel iteration for big queries.
query.par_iter_mut().for_each(|mut t| ...)spreads thousands of entities over the threads. For a few hundred entities, a plain loop is usually faster. - Ask for read-only access when you can.
&TandRes<T>let systems run in parallel;&mut TandResMut<T>make systems that touch the same data run one after another. - Avoid allocating every frame. Keep reusable buffers in a
Local<Vec<_>>and clear them instead of making new ones. - Put simulation in
FixedUpdate. It runs at a steady rate however fast the frame rate is. See Fixed timestep. - Move long work off the frame. Pathfinding, generation and file parsing can run in a task. See Tasks.
fn wobble(time: Res<Time>, mut q: Query<&mut Transform, With<Wobble>>) {
let t = time.elapsed_secs();
q.par_iter_mut().for_each(|mut transform| {
transform.translation.y = (t + transform.translation.x).sin();
});
}Entities and transforms#
- Spawn in batches.
commands.spawn_batch(iter)is faster than many single spawns. - Keep hierarchies shallow. Transform propagation walks parent to child. Entities that don't move cost little: the engine skips subtrees where nothing changed (
StaticTransformOptimizations, on by default). - Despawn what's gone. Entities far off screen still run through your systems.
Rendering#
| Do | Why |
|---|---|
| Share meshes and materials | Entities with the same mesh and material are batched into fewer draws. Use one Handle for many entities instead of adding a new asset for each. |
| Keep culling on | Entities outside the camera aren't drawn. Only use NoFrustumCulling when a shader moves vertices outside the mesh's bounds. |
| Limit shadow casters | Shadows draw the scene again for each light. Mark small or distant objects with NotShadowCaster, and keep the number of shadowed lights low. |
| Use level of detail | VisibilityRange swaps or hides meshes by distance. See Visibility. |
| Budget post-processing | Bloom, depth of field, SSAO and similar effects cost GPU time on every frame. Check each one on your slowest target. |
| Choose anti-aliasing for the target | MSAA (Msaa::Sample4, the default) costs memory bandwidth; FXAA and SMAA are cheaper post-process passes. See Anti-aliasing. |
| Compress textures | KTX2 textures load faster and use less GPU memory than PNG. |
For thousands of copies of one kind of thing (grass, debris, crowds in the distance), NEO's neo_mass crate draws a whole kind in one draw per level of detail instead of one entity per thing.
Loading#
- Load early. Start loading a level's assets before you need them, and wait on their load state. See Loading assets.
- Reuse handles. Loading the same path twice returns the same asset; keep the
Handleinstead of loading it in a system every frame. - Keep web downloads small. Everything on the
web-preloadlist downloads before the game starts. See Web builds.
Power use#
Tools and menus don't need to draw continuously. WinitSettings::desktop_app() redraws only when there's input or a change, which saves battery on laptops. See Windows.