[stable9.4] cherry pick on score events for game info category (#1354)

libs/game/docs/reference/info/change-score-by.md

@@ -45,4 +45,5 @@ if (info.player2.life() > 8) {
 ## See also #seealso
 
 [set score](/reference/info/set-score),
-[score](/reference/info/score)
+[score](/reference/info/score),
+[on score](/reference/info/on-score)

libs/game/docs/reference/info/on-score.md

@@ -0,0 +1,72 @@
+# on Score
+
+Run some code once when the player's score reaches the given value. This code will also run once if the score "passes" the given value after being changed by a value greater than 1.
+
+```sig
+info.onScore(100, function () {})
+```
+
+## Parameters
+
+* **score**: the target score value for this event to run
+* **handler**: the code to run when the score reaches or passes the target value.
+
+## Example #example
+
+### Clicker game #ex1
+
+Change the player's score by 1 each time a button is pressed and show some text when the score reaches 100!
+
+```blocks
+controller.A.onEvent(ControllerButtonEvent.Pressed, function () {
+    info.changeScoreBy(1)
+})
+info.onScore(100, function () {
+    game.splash("Score is " + info.score())
+})
+
+```
+
+### Multiplayer #ex2
+
+Randomly give either player 1 or player 2 a point on each game update. The first player to reach 100 wins!
+
+```blocks
+info.player2.onScore(100, function () {
+    game.splash("Player 2 wins!")
+    game.reset()
+})
+info.player1.onScore(100, function () {
+    game.splash("Player 1 wins!")
+    game.reset()
+})
+game.onUpdate(function () {
+    if (Math.percentChance(50)) {
+        info.player1.changeScoreBy(1)
+    } else {
+        info.player2.changeScoreBy(1)
+    }
+})
+
+```
+
+### Passing the target score #ex3
+
+This example demonstrates what happens when the score is changed by a value greater than 1. When the A button is pressed, the player's score
+changes by 10. The event still runs even though it's looking for a score of 5!
+
+```blocks
+controller.A.onEvent(ControllerButtonEvent.Pressed, function () {
+    info.changeScoreBy(10)
+})
+info.onScore(5, function () {
+    game.splash("Score is " + info.score())
+})
+
+```
+
+## See also #seealso
+
+[score](/reference/info/score),
+[set score](/reference/info/set-score),
+[change score by](/reference/info/change-score-by)

libs/game/docs/reference/info/score.md

@@ -45,4 +45,5 @@ if (info.player2.score() > 9999) {
 ## See also #seealso
 
 [set score](/reference/info/set-score),
-[change score by](/reference/info/change-score-by)
+[change score by](/reference/info/change-score-by),
+[on score](/reference/info/on-score)

libs/game/docs/reference/info/set-score.md

@@ -31,4 +31,5 @@ info.player2.setScore(110)
 ## See also #seealso
 
 [change score by](/reference/info/change-score-by),
-[score](/reference/info/score)
+[score](/reference/info/score),
+[on score](/reference/info/on-score)

libs/game/info.ts

@@ -20,12 +20,20 @@ namespace info {
         _ExplicitlySetLife = 1 << 7,
     }
 
+    class ScoreReachedHandler {
+        public isTriggered: boolean;
+        constructor(public score: number, public handler: () => void) {
+            this.isTriggered = false;
+        }
+    }
+
     export class PlayerState {
         public score: number;
         // undefined: not used
         // null: reached 0 and callback was invoked
         public life: number;
         public lifeZeroHandler: () => void;
+        public scoreReachedHandler: ScoreReachedHandler
 
         constructor() { }
     }
@@ -319,6 +327,24 @@ namespace info {
         player1.onLifeZero(handler);
     }
 
+    /**
+     * Runs code once each time the score reaches a given value. This will also
+     * run if the score "passes" the given value in either direction without ever
+     * having the exact value (e.g. if score is changed by more than 1)
+     *
+     * @param score the score to fire the event on
+     * @param handler code to run when the score reaches the given value
+     */
+    //% weight=10
+    //% blockId=gameonscore
+    //% block="on score $score"
+    //% score.defl=100
+    //% help=info/on-score
+    //% group="Score"
+    export function onScore(score: number, handler: () => void) {
+        player1.onScore(score, handler);
+    }
+
     /**
      * Start a countdown of the given duration in seconds
      * @param duration the duration of the countdown, eg: 10
@@ -605,7 +631,16 @@ namespace info {
             }
 
             this.score(); // invoked for side effects
+
+            const oldScore = state.score || 0;
             state.score = (value | 0);
+
+            if (state.scoreReachedHandler && (
+                (oldScore < state.scoreReachedHandler.score && state.score >= state.scoreReachedHandler.score) ||
+                (oldScore > state.scoreReachedHandler.score && state.score <= state.scoreReachedHandler.score)
+            )) {
+                state.scoreReachedHandler.handler();
+            }
         }
 
         /**
@@ -696,6 +731,24 @@ namespace info {
             state.lifeZeroHandler = handler;
         }
 
+        /**
+         * Runs code once each time the score reaches a given value. This will also
+         * run if the score "passes" the given value in either direction without ever
+         * having the exact value (e.g. if score is changed by more than 1)
+         *
+         * @param score the score to fire the event on
+         * @param handler code to run when the score reaches the given value
+         */
+        //% blockId=playerinfoonscore
+        //% block="on $this score $score"
+        //% score.defl=100
+        //% help=info/on-score
+        //% group="Multiplayer"
+        onScore(score: number, handler: () => void) {
+            const state = this.getState();
+            state.scoreReachedHandler = new ScoreReachedHandler(score, handler);
+        }
+
         raiseLifeZero(gameOver: boolean) {
             const state = this.getState();
             if (state.life !== null && state.life <= 0) {