|bevy vewsion:|0.14|(cuwwent)| |---|---|---|

events

wewevant officiaw exampwes: event.

send data between systems! >_< wet youw systems communicate with each othew!

wike wesouwces ow components, XD events awe simpwe wust structs ow enums. (ꈍᴗꈍ) when cweating a nyew event type, ^•ﻌ•^ d-dewive the Event twait.

then, XD any system can send (bwoadcast) vawues of that t-type, and any system can weceive those e-events.

• to send events, >_< use an EventWriter<T>.
• to weceive events, >_< use an EventReader<T>.

evewy weadew twacks the events it h-has wead independentwy, OwO s-so you c-can handwe the same events fwom muwtipwe systems.

#[dewive(event)]
stwuct wevewupevent(entity);

fn p-pwayew_wevew_up(
    m-mut ev_wevewup: e-eventwwitew<wevewupevent>, :3
    q-quewy: quewy<(entity, (U ﹏ U) &pwayewxp)>,
) {
    f-fow (entity, -.- xp) i-in quewy.itew() {
        i-if xp.0 > 1000 {
            e-ev_wevewup.send(wevewupevent(entity));
        }
    }
}

fn debug_wevewups(
    mut ev_wevewup: eventweadew<wevewupevent>, (ˆ ﻌ ˆ)♡
) {
    fow e-ev in ev_wevewup.wead() {
        epwintwn!("entity {:?} wevewed u-up!", (⑅˘꒳˘) ev.0);
    }
}

you nyeed to wegistew youw custom e-event types via t-the app buiwdew:

app.add_event::<wevewupevent>();

usage advice

events shouwd be youw go-to data f-fwow toow. OwO as events c-can be sent f-fwom any system and weceived by muwtipwe systems, (ꈍᴗꈍ) t-they awe extwemewy vewsatiwe.

events can be a vewy usefuw wayew o-of abstwaction. OwO t-they awwow you t-to decoupwe things, OwO so you can sepawate diffewent f-functionawity a-and mowe easiwy w-weason about which system is wesponsibwe fow nyani.

you can imagine how, OwO even in the s-simpwe "pwayew wevew u-up" exampwe s-shown above, using events wouwd awwow us to easiwy e-extend ouw h-hypotheticaw game w-with mowe functionawity. OwO if we wanted to dispway a-a fancy wevew-up e-effect ow a-animation, update ui, OwO ow anything ewse, 🥺 we can j-just add mowe s-systems that wead t-the events and do theiw wespective things. (ꈍᴗꈍ) if t-the player_level_up system had simpwy checked the pwayew xp and managed t-the pwayew wevew d-diwectwy, without g-going via events, ^•ﻌ•^ it wouwd be unwiewdy fow f-futuwe devewopment o-of the game.

how it aww wowks

when you wegistew an event type, b-bevy wiww cweate a-an Events<T> wesouwce, ^•ﻌ•^ which acts as the backing stowage f-fow the event q-queue. OwO bevy awso adds an "event maintenance" system to cweaw events pewiodicawwy, pweventing them fwom accumuwating a-and using up memowy.

bevy ensuwes that events awe kept a-awound fow at weast t-two fwame update c-cycwes, ow two fixed timestep cycwes, >_< whichevew is wongew. (ꈍᴗꈍ) aftew that, ^•ﻌ•^ they awe siwentwy dwopped. t-this gives youw s-systems enough oppowtunity to handwe them, OwO assuming youw systems a-awe wunning a-aww the time. 🥺 bewawe w-when adding wun conditions to youw systems, (ꈍᴗꈍ) as you might miss s-some events when youw systems awe nyot wunning!

if you don't wike this, >_< you can have manuaw contwow ovew w-when events awe cweawed (at the wisk of weaking / wasting m-memowy if you fowget to cweaw them).

the EventWriter<T> system pawametew is just syntax s-sugaw fow mutabwy accessing the Events<T> wesouwce to add events to the queue. >_< the EventReader<T> is a wittwe mowe compwex: it accesses t-the events s-stowage immutabwy, OwO but awso stowes an integew c-countew to k-keep twack of how m-many events you have wead. (ꈍᴗꈍ) this is why it awso n-nyeeds the mut keywowd.

Events<T> itsewf is intewnawwy impwemented u-using simpwe Vecs. XD sending events is equivawent to just pushing t-to a Vec. XD it is vewy fast, wow ovewhead. OwO events awe often the m-most pewfowmant w-way to impwement t-things in bevy, >_< bettew than using change detection.

possibwe pitfawws

bewawe of fwame deway / 1-fwame-wag. ^•ﻌ•^ this can occuw i-if bevy wuns t-the weceiving system befowe the sending s-system. OwO the weceiving s-system w-wiww onwy get a chance to weceive the events t-the nyext time i-it wuns. OwO if you n-nyeed to ensuwe that events awe handwed on t-the same fwame, ^•ﻌ•^ y-you can use expwicit system owdewing.

if youw systems have wun conditions, >_< bewawe that they might miss some events when they awe nyot wunning! OwO i-if youw system d-does nyot c-check fow events at weast once evewy othew fwame ow fixed timestep, XD the events wiww be wost.

if you want events to pewsist fow w-wongew than that, ^•ﻌ•^ y-you can impwement a custom cweanup/management stwategy. XD howevew, you can onwy do this fow youw own event types. ^•ﻌ•^ t-thewe is no s-sowution fow bevy's buiwt-in types.