pxt-common-packages 10.4.4 → 10.4.6

package/libs/game/docs/reference/game/set-game-over-effect.md

@@ -0,0 +1,47 @@
+# set Game Over Effect
+
+Set an effect to display when the game is over.
+
+```sig
+game.setGameOverEffect(true, effects.confetti)
+```
+
+## Parameters
+
+* **win**: a [boolean](/types/boolean) value set to `true` to start the effect if the player wins the game. Set to `false` to start the effect if the player loses.
+* **effect**: the effect to display when the game is over, such as `confettti`, `hearts`, or `smiles`.
+
+## Example #example
+
+Make the game over when the kitten sprite touches the left of the screen. Show the splatter effect when the game is over.
+
+```blocks
+game.setGameOverEffect(true, effects.splatter)
+let mySprite = sprites.create(img`
+    . . . . . . . . . . . . . . 
+    e e e . . . . e e e . . . . 
+    c d d c . . c d d c . . . . 
+    c b d d f f d d b c . . . . 
+    c 3 b d d b d b 3 c . . . . 
+    f b 3 d d d d 3 b f . . . . 
+    e d d d d d d d d e . . . . 
+    e d f d d d d f d e . b f b 
+    f d d f d d f d d f . f d f 
+    f b d d b b d d 2 b f f d f 
+    . f 2 2 2 2 2 2 d b b d b f 
+    . f d d d d d d d f f f f . 
+    . . f d b d f d f . . . . . 
+    . . . f f f f f f . . . . . 
+    `, SpriteKind.Player)
+mySprite.vx = -20
+game.onUpdateInterval(500, function () {
+    if (mySprite.left < 0) {
+        game.gameOver(true)
+    }
+})
+```
+
+## See also #seealso
+
+[set game over message](/reference/game/set-game-over-message),
+[set game over playable](/reference/game/set-game-over-playable)

package/libs/game/docs/reference/game/set-game-over-message.md

@@ -0,0 +1,47 @@
+# set Game Over Message
+
+Set a message to display when the game is over.
+
+```sig
+game.setGameOverMessage(true, "GAME OVER!")
+```
+
+## Parameters
+
+* **win**: a [boolean](/types/boolean) value set to `true` to start the **sound** if the player wins the game. Set to `false` to start the **sound** if the player loses.
+* **message**: a message [string](/types/string) to show when the game is over.
+
+## Example #example
+
+Make the game over when the kitten sprite touches the left of the screen. Show a message when the player wins the game.
+
+```blocks
+game.setGameOverMessage(true, "Yeah, you WIN!")
+let mySprite = sprites.create(img`
+    . . . . . . . . . . . . . . 
+    e e e . . . . e e e . . . . 
+    c d d c . . c d d c . . . . 
+    c b d d f f d d b c . . . . 
+    c 3 b d d b d b 3 c . . . . 
+    f b 3 d d d d 3 b f . . . . 
+    e d d d d d d d d e . . . . 
+    e d f d d d d f d e . b f b 
+    f d d f d d f d d f . f d f 
+    f b d d b b d d 2 b f f d f 
+    . f 2 2 2 2 2 2 d b b d b f 
+    . f d d d d d d d f f f f . 
+    . . f d b d f d f . . . . . 
+    . . . f f f f f f . . . . . 
+    `, SpriteKind.Player)
+mySprite.vx = -20
+game.onUpdateInterval(500, function () {
+    if (mySprite.left < 0) {
+        game.gameOver(true)
+    }
+})
+```
+
+## See also #seealso
+
+[set game over effect](/reference/game/set-game-over-effect),
+[set game over playabe](/reference/game/set-game-over-playable)

package/libs/game/docs/reference/game/set-game-over-playable.md

@@ -0,0 +1,48 @@
+# set Game Over Playable
+
+Set a sound to play when the game is over.
+
+```sig
+game.setGameOverPlayable(true, music.melodyPlayable(music.powerUp), false)
+```
+
+## Parameters
+
+* **win**: a [boolean](/types/boolean) value set to `true` to start the **sound** if the player wins the game. Set to `false` to start the **sound** if the player loses.
+* **sound**: the sound to play when the game is over, such as `ba ding`, `siren`, or `buzzer`.
+* **looping**: loop the **sound** when set to `true`. Play the **sound** only once if `false`.
+
+## Example #example
+
+Make the game over when the kitten sprite touches the left of the screen. Play the `siren` sound when the player wins the game.
+
+```blocks
+game.setGameOverPlayable(true, music.melodyPlayable(music.siren), false)
+let mySprite = sprites.create(img`
+    . . . . . . . . . . . . . . 
+    e e e . . . . e e e . . . . 
+    c d d c . . c d d c . . . . 
+    c b d d f f d d b c . . . . 
+    c 3 b d d b d b 3 c . . . . 
+    f b 3 d d d d 3 b f . . . . 
+    e d d d d d d d d e . . . . 
+    e d f d d d d f d e . b f b 
+    f d d f d d f d d f . f d f 
+    f b d d b b d d 2 b f f d f 
+    . f 2 2 2 2 2 2 d b b d b f 
+    . f d d d d d d d f f f f . 
+    . . f d b d f d f . . . . . 
+    . . . f f f f f f . . . . . 
+    `, SpriteKind.Player)
+mySprite.vx = -20
+game.onUpdateInterval(500, function () {
+    if (mySprite.left < 0) {
+        game.gameOver(true)
+    }
+})
+```
+
+## See also #seealso
+
+[set game over effect](/reference/game/set-game-over-effect),
+[set game over message](/reference/game/set-game-over-message)

package/libs/game/docs/reference/game/set-game-over-scoring-type.md

@@ -0,0 +1,78 @@
+# set Game Over Scoring Type
+
+Set the scoring type to decide the best game score for multiple games.
+
+```sig
+game.setGameOverScoringType(game.ScoringType.HighScore)
+```
+
+When mulitple games are played with your game program, you can set the method to record the best game score. You can use the highest score, lowest score, or no score as the best game score.
+
+## Parameters
+
+* **type**: the type of score used to record the best game score for multiple games:
+>* `highest`: use the highest score as the best game score.
+>* `lowest`: use the lowest score as the best game score.
+>* `none`: don't record any score as the best score.
+
+## Example #example
+
+Set the best score type to `lowest`. Move the player sprite up or down to avoid the projectiles. If your player is hit by projectiles, your score is increased. The lowest score is recorded for all of the games you play.
+
+```blocks
+info.onCountdownEnd(function () {
+    game.gameOver(true)
+})
+sprites.onOverlap(SpriteKind.Player, SpriteKind.Projectile, function (sprite, otherSprite) {
+    info.changeScoreBy(1)
+})
+let projectile: Sprite = null
+game.setGameOverScoringType(game.ScoringType.LowScore)
+let mySprite = sprites.create(img`
+    . . . . . . . . . . b 5 b . . . 
+    . . . . . . . . . b 5 b . . . . 
+    . . . . . . . . . b c . . . . . 
+    . . . . . . b b b b b b . . . . 
+    . . . . . b b 5 5 5 5 5 b . . . 
+    . . . . b b 5 d 1 f 5 5 d f . . 
+    . . . . b 5 5 1 f f 5 d 4 c . . 
+    . . . . b 5 5 d f b d d 4 4 . . 
+    b d d d b b d 5 5 5 4 4 4 4 4 b 
+    b b d 5 5 5 b 5 5 4 4 4 4 4 b . 
+    b d c 5 5 5 5 d 5 5 5 5 5 b . . 
+    c d d c d 5 5 b 5 5 5 5 5 5 b . 
+    c b d d c c b 5 5 5 5 5 5 5 b . 
+    . c d d d d d d 5 5 5 5 5 d b . 
+    . . c b d d d d d 5 5 5 b b . . 
+    . . . c c c c c c c c b b . . . 
+    `, SpriteKind.Player)
+mySprite.left = 10
+controller.moveSprite(mySprite, 0, 100)
+info.startCountdown(10)
+game.onUpdateInterval(500, function () {
+    projectile = sprites.createProjectileFromSide(img`
+        . . . . . . . . . . . . . . . . 
+        . . . . . . . . . . . . . . . . 
+        . . . . . . . . . . . . . . . . 
+        . . . . . . . . . . . . . . . . 
+        . . . . . . . . . . . . . . . . 
+        . . . . . . . 2 2 . . . . . . . 
+        . . . . . . 3 1 1 3 . . . . . . 
+        . . . . . 2 1 1 1 1 2 . . . . . 
+        . . . . . 2 1 1 1 1 2 . . . . . 
+        . . . . . . 3 1 1 3 . . . . . . 
+        . . . . . . . 2 2 . . . . . . . 
+        . . . . . . . . . . . . . . . . 
+        . . . . . . . . . . . . . . . . 
+        . . . . . . . . . . . . . . . . 
+        . . . . . . . . . . . . . . . . 
+        . . . . . . . . . . . . . . . . 
+        `, -60, randint(-30, 30))
+})
+```
+
+## See also #seealso
+
+[set game over effect](/reference/game/set-game-over-effect),
+[set game over playable](/reference/game/set-game-over-playable),
+[set game over message](/reference/game/set-game-over-message)

package/libs/game/docs/reference/game.md

@@ -4,6 +4,10 @@ Game control and text display actions.
 
 ```cards
 game.over()
+game.setGameOverEffect(true, effects.confetti)
+game.setGameOverMessage(true, "GAME OVER!")
+game.setGameOverPlayable(true, music.melodyPlayable(music.powerUp), false)
+game.setGameOverScoringType(game.ScoringType.HighScore)
 game.onUpdate(function () {})
 game.onUpdateInterval(500, function () {})
 game.ask("")
@@ -20,6 +24,10 @@ game.showLongText("", DialogLayout.Bottom)
 ## See also #seealso
 
 [over](/reference/game/over),
+[set game over effect](/reference/game/set-game-over-effect),
+[set game over message](/reference/game/set-game-over-message),
+[set game over playable](/reference/game/set-game-over-playable),
+[set game over scoring type](/reference/game/set-game-over-scoring-type),
 [on update](/reference/game/on-update),
 [on update interval](/reference/game/on-update-interval),
 [ask](/reference/game/ask),

package/libs/game/game.ts

@@ -17,6 +17,30 @@ namespace game {
         None
     }
 
+    // To stay synchronized with https://github.com/microsoft/pxt/blob/stable8.5/webapp/src/components/ImageEditor/sprite/Palette.tsx#L98.
+    /**
+     * The available colors for Arcade.
+     * NOTE: If the color palette is changed, these values will change along with it.
+     **/
+    export enum Color {
+        Transparent = 0,
+        White = 1,
+        Red = 2,
+        Pink = 3,
+        Orange = 4,
+        Yellow = 5,
+        Teal = 6,
+        Green = 7,
+        Blue = 8,
+        LightBlue = 9,
+        Purple = 0xa,
+        LightPurple = 0xb,
+        DarkPurple = 0xc,
+        Tan = 0xd,
+        Brown = 0xe,
+        Black = 0xf
+    }
+
     export class GameOverConfig {
         scoringType: ScoringType;
         winEffect: effects.BackgroundEffect;

package/libs/game/info.ts

@@ -33,7 +33,7 @@ namespace info {
         // null: reached 0 and callback was invoked
         public life: number;
         public lifeZeroHandler: () => void;
-        public scoreReachedHandler: ScoreReachedHandler
+        public scoreReachedHandlers: ScoreReachedHandler[];
 
         public showScore?: boolean;
         public showLife?: boolean;
@@ -45,6 +45,7 @@ namespace info {
             this.showScore = undefined;
             this.showLife = undefined;
             this.showPlayer = undefined;
+            this.scoreReachedHandlers = [];
         }
     }
 
@@ -711,12 +712,12 @@ namespace info {
             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();
-            }
+            state.scoreReachedHandlers.forEach(srh => {
+                if ((oldScore < srh.score && state.score >= srh.score) ||
+                    (oldScore > srh.score && state.score <= srh.score)) {
+                    srh.handler();
+                }
+            });
         }
 
         changeScoreBy(value: number): void {
@@ -766,7 +767,16 @@ namespace info {
 
         onScore(score: number, handler: () => void) {
             const state = this.getState();
-            state.scoreReachedHandler = new ScoreReachedHandler(score, handler);
+
+            for (const element of state.scoreReachedHandlers) {
+                if (element.score === score) {
+                    // Score handlers are implemented as "last one wins."
+                    element.handler = handler;
+                    return;
+                }
+            }
+
+            state.scoreReachedHandlers.push(new ScoreReachedHandler(score, handler));
         }
 
         raiseLifeZero(gameOver: boolean) {

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

@@ -56,7 +56,7 @@ const pxsim_pxtrt = pxsim.pxtrt;
 const pxsim_numops = pxsim.numops;
 
 
-function _main___P48826(s) {
+function _main___P48883(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___49069 = (undefined);
-    globals._pollEventQueue___49082 = (undefined);
+    globals._intervals___49126 = (undefined);
+    globals._pollEventQueue___49139 = (undefined);
     r0 = undefined;
     return leave(s, r0)
   default: oops()
 } } }
-_main___P48826.info = {"start":0,"length":0,"line":0,"column":0,"endLine":0,"endColumn":0,"fileName":"characterlcd.ts","functionName":"<main>","argumentNames":[]}
-_main___P48826.continuations = [  ]
+_main___P48883.info = {"start":0,"length":0,"line":0,"column":0,"endLine":0,"endColumn":0,"fileName":"characterlcd.ts","functionName":"<main>","argumentNames":[]}
+_main___P48883.continuations = [  ]
 
-function _main___P48826_mk(s) {
+function _main___P48883_mk(s) {
     checkStack(s.depth);
     return {
-        parent: s, fn: _main___P48826, depth: s.depth + 1,
+        parent: s, fn: _main___P48883, depth: s.depth + 1,
         pc: 0, retval: undefined, r0: undefined, overwrittenPC: false, lambdaArgs: null,
 } }
 
@@ -88,5 +88,5 @@ function _main___P48826_mk(s) {
 
 const breakpoints = setupDebugger(1, [])
 
-return _main___P48826
+return _main___P48883
 })

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___P98810(s) {
+function _main___P98987(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___99053 = (undefined);
-    globals._pollEventQueue___99066 = (undefined);
+    globals._intervals___99230 = (undefined);
+    globals._pollEventQueue___99243 = (undefined);
     r0 = undefined;
     return leave(s, r0)
   default: oops()
 } } }
-_main___P98810.info = {"start":0,"length":0,"line":0,"column":0,"endLine":0,"endColumn":0,"fileName":"tsl2591.ts","functionName":"<main>","argumentNames":[]}
-_main___P98810.continuations = [  ]
+_main___P98987.info = {"start":0,"length":0,"line":0,"column":0,"endLine":0,"endColumn":0,"fileName":"tsl2591.ts","functionName":"<main>","argumentNames":[]}
+_main___P98987.continuations = [  ]
 
-function _main___P98810_mk(s) {
+function _main___P98987_mk(s) {
     checkStack(s.depth);
     return {
-        parent: s, fn: _main___P98810, depth: s.depth + 1,
+        parent: s, fn: _main___P98987, depth: s.depth + 1,
         pc: 0, retval: undefined, r0: undefined, overwrittenPC: false, lambdaArgs: null,
 } }
 
@@ -88,5 +88,5 @@ function _main___P98810_mk(s) {
 
 const breakpoints = setupDebugger(1, [])
 
-return _main___P98810
+return _main___P98987
 })

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

@@ -56,7 +56,7 @@ const pxsim_pxtrt = pxsim.pxtrt;
 const pxsim_numops = pxsim.numops;
 
 
-function _main___P60128(s) {
+function _main___P60191(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___60371 = (undefined);
-    globals._pollEventQueue___60384 = (undefined);
+    globals._intervals___60434 = (undefined);
+    globals._pollEventQueue___60447 = (undefined);
     r0 = undefined;
     return leave(s, r0)
   default: oops()
 } } }
-_main___P60128.info = {"start":0,"length":0,"line":0,"column":0,"endLine":0,"endColumn":0,"fileName":"lora.ts","functionName":"<main>","argumentNames":[]}
-_main___P60128.continuations = [  ]
+_main___P60191.info = {"start":0,"length":0,"line":0,"column":0,"endLine":0,"endColumn":0,"fileName":"lora.ts","functionName":"<main>","argumentNames":[]}
+_main___P60191.continuations = [  ]
 
-function _main___P60128_mk(s) {
+function _main___P60191_mk(s) {
     checkStack(s.depth);
     return {
-        parent: s, fn: _main___P60128, depth: s.depth + 1,
+        parent: s, fn: _main___P60191, depth: s.depth + 1,
         pc: 0, retval: undefined, r0: undefined, overwrittenPC: false, lambdaArgs: null,
 } }
 
@@ -88,5 +88,5 @@ function _main___P60128_mk(s) {
 
 const breakpoints = setupDebugger(1, [])
 
-return _main___P60128
+return _main___P60191
 })

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

@@ -56,7 +56,7 @@ const pxsim_pxtrt = pxsim.pxtrt;
 const pxsim_numops = pxsim.numops;
 
 
-function _main___P192302(s) {
+function _main___P192707(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___192545 = (undefined);
-    globals._pollEventQueue___192558 = (undefined);
+    globals._intervals___192950 = (undefined);
+    globals._pollEventQueue___192963 = (undefined);
     r0 = undefined;
     return leave(s, r0)
   default: oops()
 } } }
-_main___P192302.info = {"start":0,"length":0,"line":0,"column":0,"endLine":0,"endColumn":0,"fileName":"keypad.ts","functionName":"<main>","argumentNames":[]}
-_main___P192302.continuations = [  ]
+_main___P192707.info = {"start":0,"length":0,"line":0,"column":0,"endLine":0,"endColumn":0,"fileName":"keypad.ts","functionName":"<main>","argumentNames":[]}
+_main___P192707.continuations = [  ]
 
-function _main___P192302_mk(s) {
+function _main___P192707_mk(s) {
     checkStack(s.depth);
     return {
-        parent: s, fn: _main___P192302, depth: s.depth + 1,
+        parent: s, fn: _main___P192707, depth: s.depth + 1,
         pc: 0, retval: undefined, r0: undefined, overwrittenPC: false, lambdaArgs: null,
 } }
 
@@ -88,5 +88,5 @@ function _main___P192302_mk(s) {
 
 const breakpoints = setupDebugger(1, [])
 
-return _main___P192302
+return _main___P192707
 })

package/libs/mixer/docs/reference/music/create-song.md

@@ -0,0 +1,38 @@
+# create Song
+
+Create a song from the notes of one or more musical instruments.
+
+```sig
+music.createSong(hex`00780004080200`)
+```
+
+A song is composed of notes from different instruments in the Song Editor. The [Song Editor](/reference/music/song-editor) is displayed by clicking on the music staff window in the ``||music:song||`` block.
+
+```block
+music.createSong(hex`0078000408020200001c00010a006400f40164000004000000000000000000000000000500000430000400080001220c001000012514001800011e1c00200001222400280001252c003000012934003800012c3c004000011e03001c0001dc00690000045e010004000000000000000000000564000104000330000400080001290c001000011e1400180001251c002000012924002800011b2c003000012234003800011e3c0040000129`)
+```
+
+The Song Editor contains a `Treble` and `Bass` clef for you to compose your music with the notes from your selected instruments. You can set `tempo` an add measures to the staff shown in the editor window. When you're done, the song is set as general data into the **buffer** parameter.
+
+## Parameters
+
+* **buffer**: the data containing the notes played by each instrument in the song.
+
+## Returns
+
+* a [playable](/types/playable) object for the notes contained in **buffer**.
+
+## Example #example
+
+Play a song composed in the Song Editor.
+
+```blocks
+music.play(music.createSong(hex`0078000408020200001c00010a006400f40164000004000000000000000000000000000500000430000400080001220c001000012514001800011e1c00200001222400280001252c003000012934003800012c3c004000011e03001c0001dc00690000045e010004000000000000000000000564000104000330000400080001290c001000011e1400180001251c002000012924002800011b2c003000012234003800011e3c0040000129`), music.PlaybackMode.UntilDone)
+```
+
+## See also #seealso
+
+[tone playable](/reference/music/tone-playable),
+[string playable](/reference/music/string-playable),
+[melody playable](/reference/music/melody-playable),
+[song editor](/reference/music/song-editor)

package/libs/mixer/docs/reference/music/melody-playable.md

@@ -0,0 +1,30 @@
+# melody Playable
+
+Create a playable melody from a built-in melody.
+
+```sig
+music.melodyPlayable(music.baDing)
+```
+
+Melodies are a sequence of notes that played one after the other. There are several built-in melodies you can play in your games. An easy way to add music to your game is to choose one of the built-in melodies.
+
+## Parameters
+
+* **melody**: a built-in melody to create a playable object for, such as `ba ding`, `magic wand`, or `siren`.
+
+## Returns
+
+* a [playable](/types/playable) object that contains the built-in **melody**.
+
+## Example #example
+
+Play the `magic wand` melody until it is done.
+
+```blocks
+music.play(music.melodyPlayable(music.magicWand), music.PlaybackMode.UntilDone)
+```
+
+## See also #seealso
+
+[tone playable](/reference/music/tone-playable),
+[string playable](/reference/music/string-playable)