├── .gitignore
├── src
    ├── lib.rs
    ├── background_timer.rs
    ├── background_worker.rs
    └── background_listener.rs
├── Cargo.toml
├── LICENSE
└── README.md


/.gitignore:
--------------------------------------------------------------------------------
 1 | # Generated by Cargo
 2 | # will have compiled files and executables
 3 | debug/
 4 | target/
 5 | 
 6 | # Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
 7 | # More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
 8 | Cargo.lock
 9 | 
10 | # These are backup files generated by rustfmt
11 | **/*.rs.bk
12 | 
13 | # MSVC Windows builds of rustc generate these, which store debugging information
14 | *.pdb
15 | 


--------------------------------------------------------------------------------
/src/lib.rs:
--------------------------------------------------------------------------------
 1 | #![cfg_attr(docsrs, feature(doc_cfg))]
 2 | 
 3 | #[cfg(feature = "listener")]
 4 | mod background_listener;
 5 | #[cfg(feature = "listener")]
 6 | #[cfg_attr(docsrs, doc(cfg(feature = "listener")))]
 7 | pub use background_listener::{VisibilityChangeListenerPlugin, WindowVisibility};
 8 | 
 9 | #[cfg(feature = "timer")]
10 | mod background_timer;
11 | #[cfg(feature = "timer")]
12 | #[cfg_attr(docsrs, doc(cfg(feature = "timer")))]
13 | pub use background_timer::{BackgroundTimer, BackgroundTimerPlugin};
14 | 
15 | mod background_worker;
16 | pub use background_worker::{KeepaliveSettings, WebKeepalivePlugin};
17 | 


--------------------------------------------------------------------------------
/Cargo.toml:
--------------------------------------------------------------------------------
 1 | [package]
 2 | name = "bevy_web_keepalive"
 3 | version = "0.4.0"
 4 | authors = ["Nulled"]
 5 | edition = "2021"
 6 | rust-version = "1.76"
 7 | description = "Bevy plugins to keep a bevy app running in the browser despite not being visible"
 8 | readme = "README.md"
 9 | repository = "https://github.com/Nul-led/bevy_web_keepalive"
10 | keywords = ["bevy", "wasm", "web", "gamedev"]
11 | categories = ["game-development", "game-engines"]
12 | license = "MIT OR Apache-2.0"
13 | 
14 | [package.metadata.docs.rs]
15 | all-features = true
16 | rustdoc-args = ["--cfg", "docsrs"]
17 | default-target = "wasm32-unknown-unknown"
18 | 
19 | [features]
20 | listener = []
21 | timer = []
22 | 
23 | [dependencies]
24 | bevy_winit = "0.17"
25 | bevy_app = "0.17"
26 | bevy_ecs = "0.17"
27 | bevy_time = "0.17"
28 | wasm-bindgen = "0.2.104"
29 | web-sys = { version = "0.3.81", features = [
30 |   "Window",
31 |   "Document",
32 |   "Worker",
33 |   "Blob",
34 |   "Url",
35 | ] }
36 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2024 Nulled
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/src/background_timer.rs:
--------------------------------------------------------------------------------
 1 | use bevy_app::{App, Plugin, Update};
 2 | use bevy_ecs::{
 3 |     resource::Resource,
 4 |     system::{Res, ResMut},
 5 | };
 6 | use bevy_time::{Stopwatch, Time};
 7 | use web_sys::window;
 8 | 
 9 | /// The `BackgroundTimerPlugin` plugin creates a timer that keeps track of the time the app isn't in focus (aka in background).
10 | ///
11 | /// To function properly running a background worker is REQUIRED.
12 | ///
13 | /// It may prove to be useful to establish timeouts for inactive users in multiplayer games.
14 | #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
15 | pub struct BackgroundTimerPlugin;
16 | 
17 | impl Plugin for BackgroundTimerPlugin {
18 |     fn build(&self, app: &mut App) {
19 |         app.insert_resource(BackgroundTimer::default());
20 | 
21 |         app.add_systems(Update, system_background_timer);
22 |     }
23 | }
24 | 
25 | /// The `BackgroundTimer` contains a `Stopwatch` that keeps track of the time bevy ran in the background
26 | #[derive(Clone, Debug, PartialEq, Default, Resource)]
27 | pub struct BackgroundTimer(pub Stopwatch);
28 | 
29 | /// The `system_background_timer` system updates the `Stopwatch` based on the documents visibility
30 | fn system_background_timer(mut timer: ResMut<BackgroundTimer>, time: Res<Time>) {
31 |     match window()
32 |         .and_then(|w| w.document())
33 |         .is_some_and(|d| d.hidden())
34 |     {
35 |         true => _ = timer.0.tick(time.delta()),
36 |         false => timer.0.reset(),
37 |     };
38 | }
39 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # bevy_web_keepalive
 2 | 
 3 | [![crates.io](https://img.shields.io/crates/v/bevy_web_keepalive)](https://crates.io/crates/bevy_web_keepalive)
 4 | [![docs.rs](https://docs.rs/bevy_web_keepalive/badge.svg)](https://docs.rs/bevy_web_keepalive)
 5 | 
 6 | Library of bevy plugins to keep a bevy app running in the browser despite despite not being visible
 7 | 
 8 | ## WebKeepalivePlugin
 9 | 
10 | The `WebKeepalivePlugin` plugin creates a web worker that runs the main schedule to keep bevy running in the background (eg. when the user is on another browser tab).
11 | 
12 | Usage:
13 | 
14 | ```rust
15 | // To add the worker, use add_plugins
16 | app.add_plugins(WebKeepalivePlugin::default())
17 | 
18 | // Configure the worker like this:
19 | app.add_plugins(WebKeepalivePlugin {
20 |     initial_wake_delay: 1000.0, // 1 sec delay
21 | })
22 | 
23 | // To change the wake_delay at run-time, access the `KeepaliveSettings` resource in a system
24 | fn system_a(mut settings: ResMut<KeepaliveSettings>) {
25 |     settings.wake_delay = 16.667; // 60Hz updates
26 | }
27 | 
28 | // To terminate the web worker remove the `KeepaliveSettings` resource
29 | fn system_b(world: &mut World) {
30 |     world.remove_resource::<KeepaliveSettings>();
31 | }
32 | ```
33 | 
34 | Reasoning: `bevy_winit` runs it's event loop via requestAnimationFrame. This works well for apps that don't need to run if they are in the background. However there are situations where this is unwanted such as multiplayer games that require a constant connection and cannot rely on reconnecting.
35 | 
36 | ## VisibilityChangeListenerPlugin
37 | 
38 | The `VisibilityChangeListenerPlugin` plugin registers a listener that fires whenever the app's visibility has changed and updates the `WindowVisibility` resource while also allowing the `Main` schedule to run a last time after the app is hidden.
39 | 
40 | Usage:
41 | 
42 | ```rust
43 | // To add the listener, use add_plugins
44 | app.add_plugins(VisibilityChangeListenerPlugin::default())
45 | 
46 | // To actually run the main schedule, configure the plugin like this:
47 | app.add_plugins(VisibilityChangeListenerPlugin { run_main_schedule_on_hide: true })
48 | 
49 | // To use the `WindowVisibility` resource, access it in a system
50 | fn system_a(window_visibility: Res<WindowVisibility>) {
51 |     if !window_visibility.0 {
52 |         // Do something that you want to do whenever the window is hidden
53 |     }
54 | }
55 | ```
56 | 
57 | Reasoning: This may be used to notify internal or external services of user inactivity.
58 | 
59 | Feature Requirements: `listener`
60 | 
61 | ## BackgroundTimerPlugin
62 | 
63 | The `BackgroundTimerPlugin` plugin adds a utility resource which contains a timer that keeps track of time spent in the background. This plugin needs to be paired with the `WebKeepalivePlugin` to function properly (frame delta time is capped at 250ms in bevy_time by default)
64 | 
65 | Usage:
66 | 
67 | ```rust
68 | // To add the listener, use add_plugins, please note that the WebKeepalivePlugin.initial_wake_delay should be < 250.0 so that we can ensure that the frame delta time won't be capped at 250ms
69 | app.add_plugins((WebKeepalivePlugin::default(), BackgroundTimerPlugin))
70 | 
71 | // To use the `BackgroundTimer` resource, access it in a system
72 | fn system_a(timer: Res<BackgroundTimer>) {
73 |     if !timer.0.elapsed_secs() > 60.0 {
74 |         // Clientside-timeout the user or something similar
75 |     }
76 | }
77 | ```
78 | 
79 | Reasoning: Can be used to collect analytics about user behavior regarding window visibility or (clientside) timeout a player in multiplayer games after a certain time of inactivity.
80 | 
81 | Feature Requirements: `timer`
82 | 


--------------------------------------------------------------------------------
/src/background_worker.rs:
--------------------------------------------------------------------------------
  1 | use bevy_app::{App, Plugin, Startup};
  2 | use bevy_ecs::{resource::Resource, world::World};
  3 | use bevy_winit::{EventLoopProxyWrapper, WakeUp};
  4 | use std::rc::Rc;
  5 | use wasm_bindgen::{closure::Closure, JsCast, JsValue};
  6 | use web_sys::{js_sys::Array, window, Blob, Url, Worker};
  7 | 
  8 | /// The `WebKeepalivePlugin` plugin creates a web worker that runs the main schedule even when the tab is not visible.
  9 | /// This allows a game  to keep bevy running in the background (eg. when the user is on another browser tab).
 10 | #[derive(Clone, Copy, Debug, PartialEq)]
 11 | pub struct WebKeepalivePlugin {
 12 |     /// The interval of time, in milliseconds, to run the `Main` schedule when a tab is hidden.
 13 |     ///
 14 |     /// This interval timer can be changed after the initial value is set through the [`KeepaliveSettings`] resource.
 15 |     ///
 16 |     /// The default is 16.667, or 60 updates per seconds.
 17 |     pub wake_delay: f64,
 18 | }
 19 | 
 20 | impl Default for WebKeepalivePlugin {
 21 |     fn default() -> Self {
 22 |         Self {
 23 |             wake_delay: 1000.0 / 60.0,
 24 |         }
 25 |     }
 26 | }
 27 | 
 28 | impl Plugin for WebKeepalivePlugin {
 29 |     fn build(&self, app: &mut App) {
 30 |         app.insert_resource(KeepaliveSettings {
 31 |             wake_delay: self.wake_delay,
 32 |             worker: None,
 33 |         });
 34 | 
 35 |         app.add_systems(Startup, system_init_background_worker);
 36 |     }
 37 | }
 38 | 
 39 | /// The `KeepaliveSettings` resource can be used to control at runtime how the background worker operates.
 40 | ///
 41 | /// Please note that it currently isn't possible to change from `setTimeout` to `setInterval`.
 42 | #[derive(Clone, Debug, PartialEq, Default, Resource)]
 43 | pub struct KeepaliveSettings {
 44 |     /// The interval of time, in milliseconds, to run the `Main` schedule when a tab is hidden.
 45 |     ///
 46 |     /// The default is 16.667, or 60 updates per seconds.
 47 |     pub wake_delay: f64,
 48 | 
 49 |     worker: Option<Worker>,
 50 | }
 51 | 
 52 | // These are safe to implement as we are in a single threaded environment, they are only needed to satisfy bevy's trait requirements for resources
 53 | unsafe impl Send for KeepaliveSettings {}
 54 | unsafe impl Sync for KeepaliveSettings {}
 55 | 
 56 | impl Drop for KeepaliveSettings {
 57 |     fn drop(&mut self) {
 58 |         if let Some(worker) = &self.worker {
 59 |             worker.terminate();
 60 |         }
 61 |     }
 62 | }
 63 | 
 64 | /// The `system_init_timeout_background_worker` system runs at `Startup` and launches the web worker with a tick loop based on `setInterval`
 65 | fn system_init_background_worker(world: &mut World) {
 66 |     let mut settings = world.resource_mut::<KeepaliveSettings>();
 67 |     let script = Blob::new_with_str_sequence(
 68 |         &Array::of1(&JsValue::from_str(&format!(
 69 |             "
 70 |             let interval = setInterval(() => self.postMessage(null), {});
 71 |             self.onmessage = v => {{
 72 |                 const delay = parseInt(v);
 73 |                 if (isNaN(delay)) return;
 74 |                 clearInterval(interval);
 75 |                 interval = setInterval(() => self.postMessage(null), delay);
 76 |             }};
 77 |             ",
 78 |             settings.wake_delay
 79 |         )))
 80 |         .unchecked_into(),
 81 |     )
 82 |     .unwrap();
 83 | 
 84 |     let worker = Worker::new(&Url::create_object_url_with_blob(&script).unwrap()).unwrap();
 85 | 
 86 |     settings.worker = Some(worker.clone()); // only clones the js heap ref
 87 | 
 88 |     let world_ptr = Rc::new(world as *mut World);
 89 |     let closure = Closure::<dyn FnMut()>::new({
 90 |         let world = world_ptr.clone();
 91 |         move || {
 92 |             if window()
 93 |                 .and_then(|w| w.document())
 94 |                 .is_some_and(|d| !d.hidden())
 95 |             {
 96 |                 return;
 97 |             }
 98 |             unsafe {
 99 |                 let Some(world) = world.as_mut() else {
100 |                     return;
101 |                 };
102 | 
103 |                 if let Some(proxy) = world.get_resource::<EventLoopProxyWrapper<WakeUp>>() {
104 |                     let _ = proxy.send_event(WakeUp);
105 |                 }
106 |             }
107 |         }
108 |     });
109 | 
110 |     worker.set_onmessage(Some(closure.as_ref().unchecked_ref()));
111 | 
112 |     closure.forget();
113 | }
114 | 


--------------------------------------------------------------------------------
/src/background_listener.rs:
--------------------------------------------------------------------------------
  1 | use bevy_app::{App, Main, Plugin, Startup};
  2 | use bevy_ecs::{event::Event, resource::Resource, world::World};
  3 | use std::rc::Rc;
  4 | use wasm_bindgen::{closure::Closure, JsCast};
  5 | use web_sys::window;
  6 | 
  7 | /// The `VisibilityChangeListenerPlugin` plugin registers a listener that fires when bevy's visibility is changed (eg. the user switches to a different browser tab)
  8 | ///
  9 | /// The user may decide to run the `Main` schedule once after the visibility changes to hidden.
 10 | ///
 11 | /// ## Panics
 12 | /// Panics if used in a headless environment (aka there is no access to window.document available)
 13 | #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
 14 | pub struct VisibilityChangeListenerPlugin {
 15 |     pub run_main_schedule_on_hide: bool,
 16 | }
 17 | 
 18 | impl Plugin for VisibilityChangeListenerPlugin {
 19 |     fn build(&self, app: &mut App) {
 20 |         app.insert_resource::<WindowVisibility>(WindowVisibility(true));
 21 | 
 22 |         app.add_systems(
 23 |             Startup,
 24 |             match self.run_main_schedule_on_hide {
 25 |                 true => system_init_active_background_listener,
 26 |                 false => system_init_passive_background_listener,
 27 |             },
 28 |         );
 29 |     }
 30 | }
 31 | 
 32 | /// The `WindowVisibility` resource keeps track of the app's visibility
 33 | #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, Resource, Event)]
 34 | pub struct WindowVisibility(bool);
 35 | 
 36 | /// The `system_init_active_background_listener` system initializes the visibilitychange listener which runs the `Main` schedule once when hidden
 37 | fn system_init_active_background_listener(world: &mut World) {
 38 |     let world_ptr = Rc::new(world as *mut World);
 39 |     let closure = Closure::<dyn FnMut()>::new({
 40 |         let world = world_ptr.clone();
 41 |         move || {
 42 |             let window = window().expect("Unable to access the window");
 43 |             let document = window
 44 |                 .document()
 45 |                 .expect("Unable to access the document, is the app running in headless mode?");
 46 |             let is_hidden = document.hidden();
 47 | 
 48 |             unsafe {
 49 |                 let Some(world) = world.as_mut() else {
 50 |                     return;
 51 |                 };
 52 | 
 53 |                 world.resource_mut::<WindowVisibility>().0 = !is_hidden;
 54 | 
 55 |                 world.trigger(*world.resource::<WindowVisibility>());
 56 | 
 57 |                 if is_hidden {
 58 |                     world.run_schedule(Main);
 59 |                 }
 60 |             }
 61 |         }
 62 |     });
 63 | 
 64 |     let window = window().expect("Unable to access the window");
 65 |     let document = window
 66 |         .document()
 67 |         .expect("Unable to access the document, is the app running in headless mode?");
 68 | 
 69 |     document
 70 |         .add_event_listener_with_callback("visibilitychange", closure.as_ref().unchecked_ref())
 71 |         .expect("Unable to register event listener");
 72 | 
 73 |     closure.forget();
 74 | }
 75 | 
 76 | /// The `system_init_active_background_listener` system initializes the visibilitychange listener which doesn't run the `Main` schedule
 77 | fn system_init_passive_background_listener(world: &mut World) {
 78 |     let world_ptr = Rc::new(world as *mut World);
 79 |     let closure = Closure::<dyn FnMut()>::new({
 80 |         let world = world_ptr.clone();
 81 |         move || {
 82 |             let window = window().expect("Unable to access the window");
 83 |             let document = window
 84 |                 .document()
 85 |                 .expect("Unable to access the document, is the app running in headless mode?");
 86 | 
 87 |             unsafe {
 88 |                 let Some(world) = world.as_mut() else {
 89 |                     return;
 90 |                 };
 91 | 
 92 |                 world.resource_mut::<WindowVisibility>().0 = !document.hidden();
 93 | 
 94 |                 world.trigger(*world.resource::<WindowVisibility>());
 95 |             }
 96 |         }
 97 |     });
 98 | 
 99 |     let window = window().expect("Unable to access the window");
100 |     let document = window
101 |         .document()
102 |         .expect("Unable to access the document, is the app running in headless mode?");
103 | 
104 |     document
105 |         .add_event_listener_with_callback("visibilitychange", closure.as_ref().unchecked_ref())
106 |         .expect("Unable to register event listener");
107 | 
108 |     closure.forget();
109 | }
110 | 


--------------------------------------------------------------------------------