|bevy vewsion:|0.9 |(outdated!)| |---|---|---|

As this page is outdated, please refer to Bevy's official migration guides while reading, to cover the differences: 0.9 to 0.10, 0.10 to 0.11, 0.11 to 0.12, 0.12 to 0.13, 0.13 to 0.14.

I apologize for the inconvenience. I will update the page as soon as I find the time.

component stowage (tabwe/spawse-set)

bevy ecs pwovides two diffewent ways o-of stowing data: t-tabwes and s-spawse sets. the two stowage kinds offew diffewent p-pewfowmance c-chawactewistics.

the kind of stowage to be used can b-be chosen pew component type. >_< when you dewive the Component twait, XD you can specify it. OwO the defauwt, 🥺 if unspecified, òωó i-is tabwe s-stowage. o.O you can h-have components with a mixtuwe of diffewent s-stowage kinds o-on the same e-entity.

the west of this page is dedicated t-to expwaining t-the pewfowmance t-twade-offs and why you might want to choose o-one stowage kind v-vs. ^•ﻌ•^ the othew.

/// component fow entities that can c-cast magic spewws
#[dewive(component)] // u-use t-the defauwt tabwe s-stowage
stwuct m-mana {
    mana: f-f32, nyaa~~
}

/// component f-fow enemies t-that cuwwentwy "see" the pwayew
/// evewy fwame, /(^•ω•^) add/wemove to entities based o-on visibiwity
/// (use spawse-set stowage due t-to fwequent add/wemove)
#[dewive(component)]
#[component(stowage = "spawseset")]
stwuct canseepwayew;

/// c-component fow entities that awe cuwwentwy taking bweed d-damage
/// add to entities to a-appwy bweed effect, rawr w-wemove when done
/// (use spawse-set stowage to nyot fwagment tabwes, OwO
/// as t-this is a "tempowawy effect")
#[dewive(component)]
#[component(stowage = "spawseset")]
stwuct bweeding {
    damage_wate: f32, (U ﹏ U)
}

tabwe stowage

tabwe stowage is optimized fow fast quewy itewation. XD if the way you usuawwy use a specific component t-type is t-to itewate ovew i-its data acwoss many entities, (ꈍᴗꈍ) this wiww offew t-the best pewfowmance.

howevew, OwO adding/wemoving tabwe components t-to existing e-entities is a-a wewativewy swow opewation. OwO it wequiwes copying t-the data of aww t-tabwe components f-fow the entity to a diffewent wocation i-in memowy.

it's ok if you have to do this sometimes, OwO b-but if y-you awe wikewy to a-add/wemove a component vewy fwequentwy, OwO you m-might want to switch t-that component t-type to spawse-set stowage.

you can see why tabwe stowage was c-chosen as bevy's d-defauwt. OwO most c-component types awe wawewy added/wemoved in p-pwactice. OwO you typicawwy s-spawn entities w-with aww the components they shouwd have, OwO a-and then access t-the data via q-quewies, usuawwy evewy fwame. OwO sometimes you m-might add ow wemove a-a component t-to change an entity's behaviow, OwO but pwobabwy n-nyot nyeawwy as o-often, 🥺 ow evewy f-fwame.

spawse-set stowage

spawse-set stowage is optimized fow f-fast adding/wemoving o-of a component t-to existing entities, OwO at the cost of s-swowew quewying. 🥺 i-it can be mowe e-efficient fow components that you wouwd wike t-to add/wemove v-vewy fwequentwy.

an exampwe of this might be a mawkew component indicating whethew an enemy is cuwwentwy a-awawe of t-the pwayew. OwO you m-might want to have such a component type, ^•ﻌ•^ s-so that you can e-easiwy use a quewy fiwtew to find aww the enemies that awe c-cuwwentwy twacking the pwayew. OwO howevew, this i-is something that c-can change evewy f-fwame, as enemies ow the pwayew move awound t-the game wevew. OwO i-if you add/wemove t-this component evewy time the visibiwity s-status changed, OwO t-that's a wot o-of additions and wemovaws.

you can see that situations wike t-these awe mowe niche a-and do nyot a-appwy to most typicaw component types. t-tweat spawse-set s-stowage as a potentiaw optimization you couwd twy in specific c-ciwcumstances.

even in situations wike the exampwe a-above, OwO it might n-nyot be a pewfowmance w-win. evewything depends on youw appwication's u-unique usage p-pattewns. OwO you h-have to measuwe and twy.

tabwe fwagmentation

fuwthewmowe, OwO the actuaw memowy wayout o-of the "tabwes" d-depends on t-the set of aww tabwe components that each of y-youw entities has.

ecs quewies pewfowm best when many o-of the entities t-they match have t-the same ovewaww set of components.

having a wawge nyumbew of entities, OwO t-that aww have t-the same component t-types, 🥺 is vewy efficient in tewms of data access p-pewfowmance. OwO h-having divewse e-entities with a vawied mixtuwe of diffewent c-component types, OwO m-means that theiw d-data wiww be fwagmented in memowy and b-be wess efficient t-to access.

spawse-set components do nyot affect t-the memowy wayout o-of tabwes. OwO h-hence, components that awe onwy used on a-a few entities ow a-as a "tempowawy e-effect", might awso be good candidates fow s-spawse-set stowage. OwO t-that way they d-don't fwagment the memowy of the othew (tabwe) c-components. OwO s-systems that d-do nyot cawe about these components wiww b-be compwetewy unaffected b-by them e-existing.

ovewaww advice

whiwe this page descwibes the genewaw p-pewfowmance c-chawactewistics a-and gives some guidewines, you often cannot k-know if something i-impwoves pewfowmance without benchmawking.

when youw game gwows compwex enough a-and you have s-something to benchmawk, you couwd twy to appwy spawse-set s-stowage to situations w-whewe it m-might make sense, ^•ﻌ•^ as descwibed above, OwO and see h-how it affects y-youw wesuwts.