pxt-common-packages 10.4.1 → 10.4.2

package/libs/multiplayer/docs/types/player.md

@@ -0,0 +1,82 @@
+# Player
+
+A **Player** is a game object representing one of the players in a [multiplayer](/reference/multiplayer)
+game. A Player object has entities, information, and actions associated with it related to an actual player's state in a game.
+
+Typically, a Player object is assigned a character [Sprite](/types/sprite) and keeps track of it's current score, life points, etc. Actions like controller inputs and connection status are tracked for a Player also.
+
+Player objects are usually referenced using a selector named as the player's number.
+
+```block
+let myPlayer = mp.playerSelector(mp.PlayerNumber.One)
+```
+
+Similarly in Javascript, `myPlayer` is a `Player` object and is set using the selector for ``||mp:player 1||``:
+
+```typescript-ignore
+let myPlayer: mp.Player = null
+
+myPlayer = mp.playerSelector(mp.PlayerNumber.One)
+```
+
+## Example #example
+
+```blocks
+namespace MultiplayerState {
+    export const gems = MultiplayerState.create()
+}
+mp.onControllerEvent(ControllerEvent.Connected, function (player) {
+    if (player == mp.playerSelector(mp.PlayerNumber.Two)) {
+        mp.getPlayerSprite(player).sayText("Player 2 is on!")
+    }
+})
+mp.onScore(100, function (player) {
+    if (player == mp.playerSelector(mp.PlayerNumber.One)) {
+        mp.gameOverPlayerWin(mp.playerSelector(mp.PlayerNumber.One))
+    }
+})
+mp.setPlayerSprite(mp.playerSelector(mp.PlayerNumber.Two), sprites.create(img`
+    . . 4 4 4 . . . . 4 4 4 . . . . 
+    . 4 5 5 5 e . . e 5 5 5 4 . . . 
+    4 5 5 5 5 5 e e 5 5 5 5 5 4 . . 
+    4 5 5 4 4 5 5 5 5 4 4 5 5 4 . . 
+    e 5 4 4 5 5 5 5 5 5 4 4 5 e . . 
+    . e e 5 5 5 5 5 5 5 5 e e . . . 
+    . . e 5 f 5 5 5 5 f 5 e . . . . 
+    . . f 5 5 5 4 4 5 5 5 f . . f f 
+    . . f 4 5 5 f f 5 5 6 f . f 5 f 
+    . . . f 6 6 6 6 6 6 4 4 f 5 5 f 
+    . . . f 4 5 5 5 5 5 5 4 4 5 f . 
+    . . . f 5 5 5 5 5 4 5 5 f f . . 
+    . . . f 5 f f f 5 f f 5 f . . . 
+    . . . f f . . f f . . f f . . . 
+    `, SpriteKind.Player))
+mp.moveWithButtons(mp.playerSelector(mp.PlayerNumber.One))
+mp.setPlayerSprite(mp.playerSelector(mp.PlayerNumber.Two), sprites.create(img`
+    . . . . f f f f f . . . . . . . 
+    . . . f e e e e e f . . . . . . 
+    . . f d d d d e e e f . . . . . 
+    . c d f d d f d e e f f . . . . 
+    . c d f d d f d e e d d f . . . 
+    c d e e d d d d e e b d c . . . 
+    c d d d d c d d e e b d c . . . 
+    c c c c c d d e e e f c . . . . 
+    . f d d d d e e e f f . . . . . 
+    . . f f f f f e e e e f . . . . 
+    . . . . f f e e e e e e f . f f 
+    . . . f e e f e e f e e f . e f 
+    . . f e e f e e f e e e f . e f 
+    . f b d f d b f b b f e f f e f 
+    . f d d f d d f d d b e f f f f 
+    . . f f f f f f f f f f f f f . 
+    `, SpriteKind.Player))
+mp.moveWithButtons(mp.playerSelector(mp.PlayerNumber.Two))
+```
+
+# See also #seealso
+
+[multiplayer](/reference/multiplayer)
+
+```package
+multiplayer
+```

package/libs/multiplayer/fieldEditors.ts

@@ -9,6 +9,7 @@ namespace mp {
     //% kindMemberName=value
     //% kindPromptHint="e.g. Cooldown, Speed, Attack..."
     //% blockHidden
+    //% help=multiplayer/multiplayer-state
     export function _multiplayerState(kind: number): number {
         return kind;
     }

package/libs/multiplayer/ns.ts

@@ -1,6 +1,6 @@
 //% color="#207a77" weight=96 icon="\uf0c0"
 //% blockGap=8
 //% block="Multiplayer"
-//% groups='["Sprites", "Controller", "Info", "Game", "Utility"]'
+//% groups='["Player", "Controller", "Info", "Game", "Utility"]'
 namespace mp {
 }

package/libs/multiplayer/player.ts

@@ -409,8 +409,8 @@ namespace mp {
     //% blockId=mp_getPlayerSprite
     //% block="$player sprite"
     //% player.shadow=mp_playerSelector
-    //% group=Sprites
-    //% weight=100
+    //% group=Player
+    //% weight=80
     //% blockGap=8
     //% help=multiplayer/get-player-sprite
     //% parts="multiplayer"
@@ -428,8 +428,8 @@ namespace mp {
     //% block="set $player sprite to $sprite"
     //% player.shadow=mp_playerSelector
     //% sprite.shadow=spritescreate
-    //% group=Sprites
-    //% weight=100
+    //% group=Player
+    //% weight=120
     //% blockGap=8
     //% help=multiplayer/set-player-sprite
     //% parts="multiplayer"
@@ -438,6 +438,58 @@ namespace mp {
         player.setSprite(sprite);
     }
 
+    /**
+     * Selects one of the players by number
+     * @param number The player number
+     * @returns The player
+     */
+    //% blockId=mp_playerSelector
+    //% block="player $number"
+    //% group=Player
+    //% weight=100
+    //% blockGap=8
+    //% help=multiplayer/player-selector
+    //% parts="multiplayer"
+    export function playerSelector(number: PlayerNumber): Player {
+        const index = number - 1;
+        return getPlayerByIndex(index);
+    }
+
+    /**
+     * Returns an array of all players
+     */
+    //% blockId=mp_allPlayers
+    //% block="array of all players"
+    //% group=Player
+    //% weight=90
+    //% blockGap=8
+    //% help=multiplayer/get-all-players
+    //% parts="multiplayer"
+    export function allPlayers(): Player[] {
+        return _mpstate().players.slice();
+    }
+
+    /**
+     * Gets the player the sprite is assigned to
+     * @param sprite the sprite
+     * @returns Player, or undefined if not found
+     */
+    //% blockId=mp_getPlayerBySprite
+    //% block="$sprite player"
+    //% sprite.shadow=variables_get
+    //% sprite.defl=mySprite
+    //% group=Player
+    //% weight=70
+    //% blockGap=8
+    //% help=multiplayer/get-player-by-sprite
+    //% parts="multiplayer"
+    export function getPlayerBySprite(sprite: Sprite): Player {
+        for (const player of _mpstate().players) {
+            if (player.getSprite() === sprite) return player;
+        }
+        return undefined;
+    }
+
     /**
      * Control a player's sprite with directional buttons
      * @param player The player to control
@@ -456,7 +508,7 @@ namespace mp {
     //% group=Controller
     //% weight=100
     //% blockGap=8
-    //% help=controller/move-sprite
+    //% help=multiplayer/move-with-buttons
     //% parts="multiplayer"
     export function moveWithButtons(player: Player, vx?: number, vy?: number) {
         if (!player) return;
@@ -475,7 +527,7 @@ namespace mp {
     //% group=Controller
     //% weight=90
     //% blockGap=8
-    //% help=controller/on-button-event
+    //% help=multiplayer/on-button-event
     //% parts="multiplayer"
     export function onButtonEvent(button: MultiplayerButton, event: ControllerButtonEvent, handler: (player: Player) => void) {
         _mpstate().onButtonEvent(button, event, handler);
@@ -493,7 +545,7 @@ namespace mp {
     //% group=Controller
     //% weight=80
     //% blockGap=8
-    //% help=controller/button/is-pressed
+    //% help=multiplayer/is-button-pressed
     //% parts="multiplayer"
     export function isButtonPressed(player: Player, button: MultiplayerButton): boolean {
         if (!player) return false;
@@ -511,12 +563,30 @@ namespace mp {
     //% group=Controller
     //% weight=70
     //% blockGap=8
-    //% help=controller/on-event
+    //% help=multiplayer/on-controller-event
     //% parts="multiplayer"
     export function onControllerEvent(event: ControllerEvent, handler: (player: Player) => void) {
         _mpstate().onControllerEvent(event, handler);
     }
 
+    /**
+     * Queries the connected state of the player
+     * @param player The player to query
+     * @returns true if the player is connected
+     */
+    //% blockId=mp_isConnected
+    //% block="$player connected"
+    //% player.shadow=mp_playerSelector
+    //% group=Controller
+    //% weight=60
+    //% blockGap=8
+    //% help=multiplayer/is-connected
+    //% parts="multiplayer"
+    export function isConnected(player: Player): boolean {
+        if (!player) return false;
+        return player._getController().connected;
+    }
+
     /**
      * Gets the value of the specified player state
      * @param player The player to get the state for
@@ -609,7 +679,7 @@ namespace mp {
     //% group=Info
     //% weight=70
     //% blockGap=8
-    //% help=info/on-score
+    //% help=multiplayer/on-score
     //% parts="multiplayer"
     export function onScore(score: number, handler: (player: Player) => void) {
         _mpstate().onReachedScore(score, handler);
@@ -625,7 +695,7 @@ namespace mp {
     //% group=Info
     //% weight=60
     //% blockGap=8
-    //% help=info/on-life-zero
+    //% help=multiplayer/on-life-zero
     //% parts="multiplayer"
     export function onLifeZero(handler: (player: Player) => void) {
         _mpstate().onLifeZero(handler);
@@ -682,44 +752,6 @@ namespace mp {
         return _mpstate().players[index];
     }
 
-    /**
-     * Selects one of the players by number
-     * @param number The player number
-     * @returns The player
-     */
-    //% blockId=mp_playerSelector
-    //% block="player $number"
-    //% group=Utility
-    //% weight=80
-    //% blockGap=8
-    //% help=multiplayer/player-selector
-    //% parts="multiplayer"
-    export function playerSelector(number: PlayerNumber): Player {
-        const index = number - 1;
-        return getPlayerByIndex(index);
-    }
-
-    /**
-     * Gets the player the sprite is assigned to
-     * @param sprite the sprite
-     * @returns Player, or undefined if not found
-     */
-    //% blockId=mp_getPlayerBySprite
-    //% block="$sprite player"
-    //% sprite.shadow=variables_get
-    //% sprite.defl=mySprite
-    //% group=Sprites
-    //% weight=90
-    //% blockGap=8
-    //% help=multiplayer/get-player-by-sprite
-    //% parts="multiplayer"
-    export function getPlayerBySprite(sprite: Sprite): Player {
-        for (const player of _mpstate().players) {
-            if (player.getSprite() === sprite) return player;
-        }
-        return undefined;
-    }
-
     /**
      * Turns player indicators on or off
      * @param visible indicator visibility