pxt-common-packages 9.5.12 → 10.1.2

package/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)

package/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)

package/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)

package/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)

package/libs/game/docs/reference/tiles/tile-image-at-location.md

@@ -0,0 +1,65 @@
+# tile Image At Location
+
+Get the image of the tile at a location in the tilemap.
+
+```sig
+tiles.tileImageAtLocation(tiles.getTileAtLocation(0, 0))
+```
+
+## Parameters
+
+* **location**: the [location](/reference/tiles/location) object for the tile to return it's image.
+
+## Returns
+
+* the [image](/types/image) of the tile at the **location** in the tilemap.
+
+## Example #example
+
+Make a tilemap with some smiley face tiles. Create a new sprite using the image from one of the smiley face tiles. Have the new sprite move across the screen and back.
+
+```blocks
+scene.onHitWall(SpriteKind.Player, function (sprite, location) {
+    sprite.startEffect(effects.bubbles, 500)
+})
+tiles.setCurrentTilemap(tilemap`level1`)
+let tileImage = tiles.tileImageAtLocation(tiles.getTileLocation(0, 0))
+let mySprite = sprites.create(tileImage, SpriteKind.Player)
+mySprite.setBounceOnWall(true)
+mySprite.vx = 50
+```
+
+## See also #seealso
+
+[location](/reference/tiles/location)
+
+```jres
+{
+    "transparency16": {
+        "data": "hwQQABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true
+    },
+    "tile1": {
+        "data": "hwQQABAAAABERERERERERERERERERERERPT/RET/RERE9PRERERPRET0/0RERPRERERERERE9ERERERERET0RERERPRPRPRERERE9E9E9ERERERERET0RERERERERPRERPT/RERE9ERE9PRERERPRET0/0RE/0RERERERERERERERERERERERA==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile"
+    },
+    "level1": {
+        "id": "level1",
+        "mimeType": "application/mkcd-tilemap",
+        "data": "MTAwYTAwMDgwMDAxMDAwMTAwMDEwMDAxMDAwMTAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAxMDAwMTAwMDEwMDAxMDAwMTAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMA==",
+        "tileset": [
+            "myTiles.transparency16",
+            "myTiles.tile1"
+        ],
+        "displayName": "level1"
+    },
+    "*": {
+        "mimeType": "image/x-mkcd-f4",
+        "dataEncoding": "base64",
+        "namespace": "myTiles"
+    }
+}
+```

package/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() { }
     }
@@ -332,6 +340,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
@@ -618,7 +644,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();
+            }
         }
 
         /**
@@ -709,6 +744,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) {

package/libs/game/sim/keymap.ts

@@ -89,8 +89,8 @@ namespace pxsim {
             this.setSystemKeys(
                 80, // P - Screenshot
                 82, // R - Gif
-                0, // Menu - not mapped
-                0 // Reset - not mapped
+                192, // Menu - '`' (backtick) button
+                50 // Reset - Backspace button
             );
 
             // Player 1 alternate mapping. This is cleared when the game sets any player keys explicitly

package/libs/game/sprite.ts

@@ -857,6 +857,7 @@ class Sprite extends sprites.BaseSprite {
     //% this.shadow=variables_get
     //% this.defl=mySprite
     //% blockNamespace="scene" group="Locations" weight=90
+    //% help=scene/tilemap-location
     tilemapLocation(): tiles.Location {
         const scene = game.currentScene();
         if (!scene.tileMap) return undefined;

package/libs/game/tilemap.ts

@@ -110,7 +110,7 @@ namespace tiles {
         //% this.defl=location
         //% this.shadow=variables_get
         //% group="Locations" blockGap=8
-        //% weight=10
+        //% weight=10 help=tiles/get-neighboring-location
         public getNeighboringLocation(direction: CollisionDirection): Location {
             switch (direction) {
                 case CollisionDirection.Top:

package/libs/lcd/built/debug/binary.js

@@ -56,7 +56,7 @@ const pxsim_pxtrt = pxsim.pxtrt;
 const pxsim_numops = pxsim.numops;
 
 
-function _main___P48217(s) {
+function _main___P48222(s) {
 let r0 = s.r0, step = s.pc;
 s.pc = -1;
 
@@ -66,19 +66,19 @@ if (yieldSteps-- < 0 && maybeYield(s, step, r0) || runtime !== pxsim.runtime) re
 switch (step) {
   case 0:
 
-    globals._intervals___48460 = (undefined);
-    globals._pollEventQueue___48473 = (undefined);
+    globals._intervals___48465 = (undefined);
+    globals._pollEventQueue___48478 = (undefined);
     r0 = undefined;
     return leave(s, r0)
   default: oops()
 } } }
-_main___P48217.info = {"start":0,"length":0,"line":0,"column":0,"endLine":0,"endColumn":0,"fileName":"characterlcd.ts","functionName":"<main>","argumentNames":[]}
-_main___P48217.continuations = [  ]
+_main___P48222.info = {"start":0,"length":0,"line":0,"column":0,"endLine":0,"endColumn":0,"fileName":"characterlcd.ts","functionName":"<main>","argumentNames":[]}
+_main___P48222.continuations = [  ]
 
-function _main___P48217_mk(s) {
+function _main___P48222_mk(s) {
     checkStack(s.depth);
     return {
-        parent: s, fn: _main___P48217, depth: s.depth + 1,
+        parent: s, fn: _main___P48222, depth: s.depth + 1,
         pc: 0, retval: undefined, r0: undefined, overwrittenPC: false, lambdaArgs: null,
 } }
 
@@ -88,5 +88,5 @@ function _main___P48217_mk(s) {
 
 const breakpoints = setupDebugger(1, [])
 
-return _main___P48217
+return _main___P48222
 })

package/libs/light-spectrum-sensor/built/debug/binary.js

@@ -56,7 +56,7 @@ const pxsim_pxtrt = pxsim.pxtrt;
 const pxsim_numops = pxsim.numops;
 
 
-function _main___P96983(s) {
+function _main___P96998(s) {
 let r0 = s.r0, step = s.pc;
 s.pc = -1;
 
@@ -66,19 +66,19 @@ if (yieldSteps-- < 0 && maybeYield(s, step, r0) || runtime !== pxsim.runtime) re
 switch (step) {
   case 0:
 
-    globals._intervals___97226 = (undefined);
-    globals._pollEventQueue___97239 = (undefined);
+    globals._intervals___97241 = (undefined);
+    globals._pollEventQueue___97254 = (undefined);
     r0 = undefined;
     return leave(s, r0)
   default: oops()
 } } }
-_main___P96983.info = {"start":0,"length":0,"line":0,"column":0,"endLine":0,"endColumn":0,"fileName":"tsl2591.ts","functionName":"<main>","argumentNames":[]}
-_main___P96983.continuations = [  ]
+_main___P96998.info = {"start":0,"length":0,"line":0,"column":0,"endLine":0,"endColumn":0,"fileName":"tsl2591.ts","functionName":"<main>","argumentNames":[]}
+_main___P96998.continuations = [  ]
 
-function _main___P96983_mk(s) {
+function _main___P96998_mk(s) {
     checkStack(s.depth);
     return {
-        parent: s, fn: _main___P96983, depth: s.depth + 1,
+        parent: s, fn: _main___P96998, depth: s.depth + 1,
         pc: 0, retval: undefined, r0: undefined, overwrittenPC: false, lambdaArgs: null,
 } }
 
@@ -88,5 +88,5 @@ function _main___P96983_mk(s) {
 
 const breakpoints = setupDebugger(1, [])
 
-return _main___P96983
+return _main___P96998
 })

package/libs/lora/built/debug/binary.js

@@ -56,7 +56,7 @@ const pxsim_pxtrt = pxsim.pxtrt;
 const pxsim_numops = pxsim.numops;
 
 
-function _main___P59519(s) {
+function _main___P59524(s) {
 let r0 = s.r0, step = s.pc;
 s.pc = -1;
 
@@ -66,19 +66,19 @@ if (yieldSteps-- < 0 && maybeYield(s, step, r0) || runtime !== pxsim.runtime) re
 switch (step) {
   case 0:
 
-    globals._intervals___59762 = (undefined);
-    globals._pollEventQueue___59775 = (undefined);
+    globals._intervals___59767 = (undefined);
+    globals._pollEventQueue___59780 = (undefined);
     r0 = undefined;
     return leave(s, r0)
   default: oops()
 } } }
-_main___P59519.info = {"start":0,"length":0,"line":0,"column":0,"endLine":0,"endColumn":0,"fileName":"lora.ts","functionName":"<main>","argumentNames":[]}
-_main___P59519.continuations = [  ]
+_main___P59524.info = {"start":0,"length":0,"line":0,"column":0,"endLine":0,"endColumn":0,"fileName":"lora.ts","functionName":"<main>","argumentNames":[]}
+_main___P59524.continuations = [  ]
 
-function _main___P59519_mk(s) {
+function _main___P59524_mk(s) {
     checkStack(s.depth);
     return {
-        parent: s, fn: _main___P59519, depth: s.depth + 1,
+        parent: s, fn: _main___P59524, depth: s.depth + 1,
         pc: 0, retval: undefined, r0: undefined, overwrittenPC: false, lambdaArgs: null,
 } }
 
@@ -88,5 +88,5 @@ function _main___P59519_mk(s) {
 
 const breakpoints = setupDebugger(1, [])
 
-return _main___P59519
+return _main___P59524
 })

package/libs/matrix-keypad/built/debug/binary.js

@@ -56,7 +56,7 @@ const pxsim_pxtrt = pxsim.pxtrt;
 const pxsim_numops = pxsim.numops;
 
 
-function _main___P188039(s) {
+function _main___P188074(s) {
 let r0 = s.r0, step = s.pc;
 s.pc = -1;
 
@@ -66,19 +66,19 @@ if (yieldSteps-- < 0 && maybeYield(s, step, r0) || runtime !== pxsim.runtime) re
 switch (step) {
   case 0:
 
-    globals._intervals___188282 = (undefined);
-    globals._pollEventQueue___188295 = (undefined);
+    globals._intervals___188317 = (undefined);
+    globals._pollEventQueue___188330 = (undefined);
     r0 = undefined;
     return leave(s, r0)
   default: oops()
 } } }
-_main___P188039.info = {"start":0,"length":0,"line":0,"column":0,"endLine":0,"endColumn":0,"fileName":"keypad.ts","functionName":"<main>","argumentNames":[]}
-_main___P188039.continuations = [  ]
+_main___P188074.info = {"start":0,"length":0,"line":0,"column":0,"endLine":0,"endColumn":0,"fileName":"keypad.ts","functionName":"<main>","argumentNames":[]}
+_main___P188074.continuations = [  ]
 
-function _main___P188039_mk(s) {
+function _main___P188074_mk(s) {
     checkStack(s.depth);
     return {
-        parent: s, fn: _main___P188039, depth: s.depth + 1,
+        parent: s, fn: _main___P188074, depth: s.depth + 1,
         pc: 0, retval: undefined, r0: undefined, overwrittenPC: false, lambdaArgs: null,
 } }
 
@@ -88,5 +88,5 @@ function _main___P188039_mk(s) {
 
 const breakpoints = setupDebugger(1, [])
 
-return _main___P188039
+return _main___P188074
 })