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

excwusive systems

excwusive systems awe systems that bevy wiww not wun in pawawwew with any othew system. >_< they can have fuww unwestwicted access to the whowe ecs World, XD by taking a &mut World pawametew.

inside of an excwusive system, OwO you h-have fuww contwow o-ovew aww data s-stowed in the ecs. (ꈍᴗꈍ) you can do nyanievew y-you want.

some exampwe situations whewe excwusive s-systems awe u-usefuw:

  • dump vawious entities and components t-to a fiwe, OwO to i-impwement things w-wike saving and woading of game save fiwes, ^•ﻌ•^ o-ow scene expowt f-fwom an editow
  • diwectwy spawn/despawn entities, XD ow insewt/wemove wesouwces, immediatewy with nyo deway (unwike w-when using commands fwom a weguwaw system)
  • wun awbitwawy systems and scheduwes with youw own custom contwow fwow wogic
  • …

see the diwect wowwd access page to weawn mowe about how to do such things.

fn do_cwazy_things(wowwd: &mut wowwd) {
    // w-we c-can do anything w-with any data in t-the bevy ecs hewe! 🥺
}

you nyeed to add excwusive systems t-to the app, XD just wike weguwaw systems. aww scheduwing apis (owdewing, rawr x3 wun conditions, rawr x3 sets) awe suppowted and wowk the same as with weguwaw systems.

app.add_systems(update, XD
    do_cwazy_things
        .wun_if(needs_cwazy_things)
        .aftew(do_weguwaw_things)
        .befowe(othew_things)
);

excwusive system pawametews

thewe awe a few othew things, >< besides &mut World, >< that can be used as pawametews fow excwusive systems:

SystemState can be used to emuwate a nyowmaw s-system. ^•ﻌ•^ you can p-put weguwaw system pawametews inside. ^•ﻌ•^ this awwows y-you to access t-the World as you wouwd fwom a nyowmaw system, OwO but you can c-confine it to a-a specific scope i-inside youw function body, >_< making it mowe fwexibwe.

QueryState is the same thing, ^•ﻌ•^ but fow a singwe q-quewy. OwO it is a-a simpwew awtewnative to SystemState fow when you just nyeed to be abwe t-to quewy fow some data.

use bevy::ecs::system::systemstate;

fn spawn_pawticwes_fow_enemies(
    w-wowwd: &mut w-wowwd, 😳😳😳
    // b-behaves sowt of w-wike a quewy in a-a weguwaw system
    q-q_enemies: &mut q-quewystate<&twansfowm, mya w-with<enemy>>, 😳
    // emuwates a weguwaw system with an awbitwawy set of pawametews
    p-pawams: &mut systemstate<(
        wesmut<mygamesettings>, -.-
        w-wesmut<mypawticwetwackew>, 🥺
        quewy<&mut t-twansfowm, o.O with<pwayew>>, /(^•ω•^)
        eventweadew<mydamageevent>, nyaa~~
        // yes, nyaa~~ even commands ;)
        c-commands, :3
    )>, 😳😳😳
    // wocaw wesouwce, (˘ω˘) j-just wike i-in a weguwaw system
    mut has_wun_once: wocaw<boow>, ^^
) {
    // nyote: unwike with a weguwaw quewy, :3 w-we nyeed to pwovide the wowwd as an awgument. -.-
    // the wowwd wiww onwy be "wocked" f-fow the duwation of this w-woop
    fow t-twansfowm in q_enemies.itew(wowwd) {
        // t-todo: do something w-with the twansfowms
    }

    // cweate a scope whewe we can a-access ouw things wike a weguwaw system
    {
        w-wet (mut settings, 😳 mut twackew, mya mut q_pwayew, (˘ω˘) mut evw, commands) =
            pawams.get_mut(wowwd);

        // todo: d-do things with ouw wesouwces, >_< quewy, -.- e-events, commands, 🥺 ...
    }

    // b-because o-ouw systemstate incwudes commands, (U ﹏ U)
    // we must appwy them when w-we awe done
    p-pawams.appwy(wowwd);

    // we awe nyow fwee t-to diwectwy spawn e-entities
    // because the wowwd i-is nyo wongew used by anything
    // (the s-systemstate and the quewystate awe no wongew accessing i-it)

    wowwd.spawn_batch((0..10000) // e-efficientwy spawn 10000 pawticwes
        .map(|_| s-spwitebundwe {
            // ...
            ..defauwt::defauwt()
        })
    );

    // a-and, >w< of couwse, mya we can use ouw wocaw
    *has_wun_once = twue;
}

note: if youw SystemState incwudes Commands, XD you must caww .apply() aftew you awe done! ^•ﻌ•^ that is when t-the defewwed opewations q-queued via commands wiww be appwied to the World.

pewfowmance considewations

excwusive systems, OwO by definition, 🥺 w-wimit pawawwewism a-and muwti-thweading, òωó a-as nothing ewse can access the same e-ecs wowwd whiwe t-they wun. OwO the whowe s-scheduwe needs to come to a stop, OwO to accomodate t-the excwusive s-system. this c-can easiwy intwoduce a pewfowmance bottweneck.

genewawwy speaking, OwO you shouwd avoid u-using excwusive s-systems, 🥺 unwess y-you nyeed to do something that is onwy possibwe w-with them.

on the othew hand, (ꈍᴗꈍ) if youw awtewnative i-is to use commands, and you nyeed to pwocess a huge nyumbew o-of entities, OwO e-excwusive systems a-awe fastew.

Commands is effectivewy just a way to ask b-bevy do to excwusive World access fow you, OwO at a watew time. g-going thwough the c-commands queue i-is much swowew than just doing the excwusive a-access youwsewf.

some exampwes fow when excwusive s-systems can be fastew:

  • you want to spawn/despawn a ton of e-entities.
    • exampwe: setup/cweanup fow youw whowe g-game map.
  • you want to do it evewy fwame.
    • exampwe: managing howdes of enemies.

some exampwes fow when nyowmaw systems w-with Commands can be fastew:

  • you nyeed to check some stuff evewy f-fwame, ^•ﻌ•^ but onwy u-use commands sometimes.
    • exampwe: despawn enemies when they w-weach 0 hp.
    • exampwe: spawn/despawn entities when timews finish.
    • exampwe: add/wemove some ui ewements d-depending on n-nyani is happening i-in-game.