feat: add pause, unpause, show, hide events & hook it into broadphase

.vscode/settings.json

@@ -12,6 +12,8 @@
     "lerp",
     "minver",
     "mult",
+    "ohhi",
+    "unuse",
     "verts"
   ]
 }

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog
 
+<!-- markdownlint-disable no-duplicate-heading blanks-around-fences single-h1 -->
+
 All notable changes to this project will be documented in this file.
 
 The format is (mostly) based on
@@ -40,6 +42,13 @@ So your change should look like:
 
 ### Added
 
+- The `onHide` and `onShow` global handlers (which have been deprecated for a
+  while) are now actually removed, you must use `onTabHide` and `onTabShow`.
+  `onHide` and `onShow` still exist but now handle reacting to changes in the
+  `.hidden` property of game objects (#1041) - @dragoncoder047
+- Added `onPause()`, `onUnpause()`, `onHide()`, and `onShow()` events for
+  listening to the state of the `paused` and `hidden` properties on game objects
+  (#1041) - @dragoncoder047
 - Made random generator algorithm configurable using `setRNG()` (#1057) -
   @mflerackers
 - Added xorshift32 as random generator (#1057) - @mflerackers

src/api/eventHandlers.ts

@@ -211,6 +211,30 @@ export function onHoverUpdate(tag: Tag, action: (obj: GameObj) => void) {
     return on("hoverUpdate", tag, action);
 }
 
+export const onHide = overload2((cb: (x: GameObj) => void) => {
+    return _k.game.events.on("hide", cb);
+}, (tag: Tag, cb: (x: GameObj) => void) => {
+    return on("hide", tag, cb);
+});
+
+export const onShow = overload2((cb: (x: GameObj) => void) => {
+    return _k.game.events.on("show", cb);
+}, (tag: Tag, cb: (x: GameObj) => void) => {
+    return on("show", tag, cb);
+});
+
+export const onPause = overload2((cb: (obj: GameObj) => void) => {
+    return _k.game.events.on("pause", cb);
+}, (tag: Tag, cb: (obj: GameObj) => void) => {
+    return on("pause", tag, cb);
+});
+
+export const onUnpause = overload2((cb: (obj: GameObj) => void) => {
+    return _k.game.events.on("unpause", cb);
+}, (tag: Tag, cb: (obj: GameObj) => void) => {
+    return on("unpause", tag, cb);
+});
+
 // #region just ev handlers
 export function onError(action: (err: Error) => void) {
     return _k.game.events.on("error", action);

src/app/app.ts

@@ -672,11 +672,11 @@ export const initApp = (
     }
 
     function onTabHide(action: () => void): KEventController {
-        return state.events.on("show", action);
+        return state.events.on("tabHide", action);
     }
 
     function onTabShow(action: () => void): KEventController {
-        return state.events.on("show", action);
+        return state.events.on("tabShow", action);
     }
 
     const onGamepadButtonPress = overload2(
@@ -1245,11 +1245,11 @@ export const initApp = (
             // prevent a surge of dt when switch back after the tab being hidden for a while
             state.skipTime = true;
             state.isHidden = false;
-            state.events.trigger("show");
+            state.events.trigger("tabShow");
         }
         else {
             state.isHidden = true;
-            state.events.trigger("hide");
+            state.events.trigger("tabHide");
         }
     };
 

src/core/context.ts

@@ -460,8 +460,6 @@ export const createContext = (
         onTouchMove: defaultScope.onTouchMove,
         onTouchEnd: defaultScope.onTouchEnd,
         onScroll: defaultScope.onScroll,
-        onHide: defaultScope.onHide,
-        onShow: defaultScope.onShow,
         onTabShow: defaultScope.onTabShow,
         onTabHide: defaultScope.onTabHide,
         onGamepadButtonDown: defaultScope.onGamepadButtonDown,
@@ -496,6 +494,10 @@ export const createContext = (
         releaseButton: app.releaseButton,
         getLastInputDeviceType: app.getLastInputDeviceType,
         charInputted: app.charInputted,
+        onHide: defaultScope.onHide,
+        onShow: defaultScope.onShow,
+        onPause: defaultScope.onPause,
+        onUnpause: defaultScope.onUnpause,
         // timer
         loop,
         wait,

src/core/contextType.ts

@@ -2801,6 +2801,58 @@ export interface KAPLAYCtx {
      * @group Events
      */
     onTabShow(action: () => void): KEventController;
+    /**
+     * Register an event that runs when an object with the provided tag becomes visible, either directly or when a parent is un-hidden.
+     *
+     * (Note that "visible" just means "the draw handlers will run", it doesn't tell you anything about whether pixels will be drawn visibly on screen.)
+     *
+     * @param tag - The tag to listen for.
+     * @param action - The function that runs when an object is un-hidden.
+     *
+     * @example
+     * ```js
+     * onShow("player", () => {
+     *     debug.log("hi player");
+     * });
+     *
+     * const player = add([
+     *     pos(),
+     *     "player"
+     * ]);
+     * player.hidden = false;
+     * player.hidden = true; // Logs "hi player"
+     * ```
+     *
+     * @returns The event controller.
+     * @since v2000.0
+     * @group Events
+     */
+    onShow(tag: Tag, action: (obj: GameObj) => void): KEventController;
+    /**
+     * Register an event that runs when an object becomes visible, either directly or when a parent is un-hidden.
+     *
+     * (Note that "visible" just means "the draw handlers will run", it doesn't tell you anything about whether pixels will be drawn visibly on screen.)
+     *
+     * @param action - The function that runs when an object is un-hidden.
+     *
+     * @example
+     * ```js
+     * onShow(() => {
+     *     debug.log("ohhi");
+     * });
+     *
+     * const obj = add([
+     *     pos(),
+     * ]);
+     * obj.hidden = false;
+     * obj.hidden = true; // Logs "ohhi"
+     * ```
+     *
+     * @returns The event controller.
+     * @since v2000.0
+     * @group Events
+     */
+    onShow(action: (obj: GameObj) => void): KEventController;
     /**
      * Register an event that runs when tab is hidden.
      *
@@ -2832,57 +2884,159 @@ export interface KAPLAYCtx {
      */
     onTabHide(action: () => void): KEventController;
     /**
-     * @deprecated use `onTabHide` instead
+     * Register an event that runs when an object with the provided tag becomes invisible, either directly or when a parent is hidden.
      *
-     * Register an event that runs when tab is hidden.
+     * (Note that "invisible" just means "the draw handlers will not run", it doesn't tell you anything about whether pixels were being drawn visibly on screen.)
      *
-     * @param action - The function that is run what the tab is hidden.
+     * @param tag - The tag to listen for.
+     * @param action - The function that runs when an object is hidden.
      *
      * @example
      * ```js
-     * // spooky ghost
-     * let ghosty = add([
-     *     pos(center()),
-     *     sprite("ghosty"),
-     *     anchor("center"),
+     * onHide("player", () => {
+     *     debug.log("bye player");
+     * });
+     *
+     * const player = add([
+     *     pos(),
+     *     "player"
      * ]);
+     * player.hidden = true; // Logs "bye player"
+     * ```
      *
-     * // when switching tabs, this runs
+     * @returns The event controller.
+     * @since v2000.0
+     * @group Events
+     */
+    onHide(tag: Tag, action: (obj: GameObj) => void): KEventController;
+    /**
+     * Register an event that runs when an object becomes invisible, either directly or when a parent is hidden.
+     *
+     * (Note that "invisible" just means "the draw handlers will not run", it doesn't tell you anything about whether pixels were being drawn visibly on screen.)
+     *
+     * @param action - The function that runs when an object is hidden.
+     *
+     * @example
+     * ```js
      * onHide(() => {
-     *     destroy(ghosty);
-     *     add([
-     *         text("There was never aa ghosttttt"),
-     *         pos(center()),
-     *         anchor("center"),
-     *     ]);
+     *     debug.log("bye");
+     * });
+     *
+     * const obj = add([
+     *     pos(),
+     * ]);
+     * obj.hidden = true; // Logs "bye"
+     * ```
+     *
+     * @returns The event controller.
+     * @since v2000.0
+     * @group Events
+     */
+    onHide(action: (obj: GameObj) => void): KEventController;
+    /**
+     * Register an event that runs when an object with the provided tag becomes paused, either directly or when a parent is paused.
+     *
+     * ("Paused" simply means "the update and fixedUpdate handlers will not run.")
+     *
+     * @param tag - The tag to listen for.
+     * @param action - The function that runs when an object is paused.
+     *
+     * @example
+     * ```js
+     * onPause("player", () => {
+     *     debug.log("player is frozen");
      * });
+     *
+     * const player = add([
+     *     pos(),
+     *     "player"
+     * ]);
+     * player.paused = true; // Logs "player is frozen"
      * ```
      *
      * @returns The event controller.
-     * @since v3001.0
+     * @since v2000.0
      * @group Events
      */
-    onHide(action: () => void): KEventController;
+    onPause(tag: Tag, action: (obj: GameObj) => void): KEventController;
     /**
-     * @deprecated use `onTabShow` instead
+     * Register an event that runs when an object becomes paused, either directly or when a parent is paused.
      *
-     * Register an event that runs when tab is shown.
+     * ("Paused" simply means "the update and fixedUpdate handlers will not run.")
      *
-     * @param action - The function that is run when the tab is shown.
+     * @param action - The function that runs when an object is paused.
      *
      * @example
      * ```js
-     * // user has returned to this tab
-     * onShow(() => {
-     *     burp();
+     * onPause(() => {
+     *     debug.log("frozen");
      * });
+     *
+     * const obj = add([
+     *     pos(),
+     * ]);
+     * obj.paused = true; // Logs "frozen"
      * ```
      *
      * @returns The event controller.
-     * @since v3001.0
+     * @since v2000.0
+     * @group Events
+     */
+    onPause(action: (obj: GameObj) => void): KEventController;
+    /**
+     * Register an event that runs when an object with the provided tag becomes unpaused, either directly or when a parent is unpaused.
+     *
+     * ("Unpaused" simply means "the update and fixedUpdate handlers will run.")
+     *
+     * @param tag - The tag to listen for.
+     * @param action - The function that runs when an object is unpaused.
+     *
+     * @example
+     * ```js
+     * onUnpause("player", () => {
+     *     debug.log("player is melted");
+     * });
+     *
+     * const player = add([
+     *     pos(),
+     *     "player"
+     * ]);
+     * player.paused = false; // Logs nothing, player is already unpaused
+     * player.paused = true;
+     * player.paused = false; // Logs "player is melted"
+     * ```
+     *
+     * @returns The event controller.
+     * @since v2000.0
+     * @group Events
+     */
+    onUnpause(tag: Tag, action: (obj: GameObj) => void): KEventController;
+    /**
+     * Register an event that runs when an object becomes unpaused, either directly or when a parent is unpaused.
+     *
+     * ("Unpaused" simply means "the update and fixedUpdate handlers will run.")
+     *
+     * @param action - The function that runs when an object is unpaused.
+     *
+     * @example
+     * ```js
+     * onUnpause(() => {
+     *     debug.log("unfrozen");
+     * });
+     *
+     * const obj = add([
+     *     pos(),
+     * ]);
+     * obj.paused = false; // Logs nothing, obj is already unpaused
+     * obj.paused = true;
+     * obj.paused = false; // Logs "frozen"
+     * ```
+     *
+     * @returns The event controller.
+     * @since v2000.0
      * @group Events
      */
-    onShow(action: () => void): KEventController;
+    onUnpause(action: (obj: GameObj) => void): KEventController;
     /**
      * Register an event that runs at a fixed framerate.
      *