pxt-common-packages 9.5.4 → 9.5.7

package/libs/game/docs/reference/tiles/set-tilemap.md

@@ -0,0 +1,90 @@
+# set Tilemap
+
+Set a tilemap as the current tilemap for the game scene.
+
+```sig
+tiles.setTilemap(null)
+```
+
+A [tilemap](/reference/tiles/tilemap) is a data object that contains the dimensions, layers, and tile list for a tile mapping to set as the scene for a game. A game program can have more than one tilemap defined and the game's scene or _level_ can change by setting a different tilemap at certain times during a game.
+
+Tilemaps aren't coded by the user but are created using a tilemap editor. Each tilemap in a game project is a named resource and is contained within the project's **assets** collection. In code, a particular tilemap is specified with it's resource name like this:
+
+```typescript
+tiles.setTilemap(tilemap`level1`)
+```
+
+## Parameters
+
+* **tilemap**: the [tilemap](/reference/tiles/tilemap) data containing the tilemap layout and tiles to set for the game scene. The tilemap can be specified by it's resource name, such as: `` tilemap`level1` ``.
+
+## Example #example
+
+Create a maze tilemap for a sprite to travel through. Set the tilemap as the scene for the game. Create a sprite and start it travelling in the maze.
+
+```blocks
+tiles.setTilemap(tilemap`level1`)
+let mySprite = sprites.create(img`
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . 5 5 5 5 5 5 . . . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . . . 5 5 5 5 5 5 . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    `, SpriteKind.Player)
+mySprite.setPosition(0, 104)
+mySprite.vx = 16
+```
+
+## See also #seealso
+
+[tilemap](/reference/tiles/tilemap),
+[set tile at](/reference/scene/set-tile-at)
+
+```jres
+{
+    "transparency16": {
+        "data": "hwQQABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true
+    },
+    "tile1": {
+        "data": "hwQQABAAAADu7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7g==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile0"
+    },
+    "tile2": {
+        "data": "hwQQABAAAABERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERA==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile1"
+    },
+    "level1": {
+        "id": "level1",
+        "mimeType": "application/mkcd-tilemap",
+        "data": "MTAwYTAwMDgwMDAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMDAwMDAwMDAwMDAwMDAwMDEwMTAwMDIwMjAyMDAwMjAyMDAwMTAxMDAwMjAwMDIwMDAyMDIwMDAwMDEwMDAyMDAwMjAwMDIwMDAwMDEwMTAwMDIwMDAyMDIwMjAwMDIwMTAwMDAwMDAwMDAwMDAyMDAwMDAxMDEwMTAxMDEwMTAxMDEwMTAxMDEyMjIyMjIyMjIyMDIwMDAwMDAyMDAyMjIwMjIyMjAwMjAyMDIyMjAwMDIwMjAyMDIyMDAyMDIyMjAyMjIwMDAwMDAwMjIwMjIyMjIyMjIyMg==",
+        "tileset": [
+            "myTiles.transparency16",
+            "myTiles.tile1",
+            "myTiles.tile2"
+        ],
+        "displayName": "maze"
+    },
+    "*": {
+        "mimeType": "image/x-mkcd-f4",
+        "dataEncoding": "base64",
+        "namespace": "myTiles"
+    }
+}
+```

package/libs/game/docs/reference/tiles/set-wall-at.md

@@ -1,87 +1,86 @@
 # set Wall At
 
-Set a wall at a tile location in the tilemap.
+Set a tile as a wall tile in the tilemap.
 
 ```sig
-tiles.setWallAt(null, false)
+tiles.setWallAt(tiles.getTileLocation(0, 0), false)
 ```
 
-Tiles in a tilemap can serve as "wall" tiles to cause an action on a sprite that
-comes in contact with the tile. Sprites have flags ([boolean](/types/boolean)
-settings) that can set certain behavior when the contact a wall tile.
+Wall tiles create a barrier for sprites so that they can't pass through tilemap at the tile location. You can set a tile location in the tilemap as a wall or turn it back to a regular tile.
 
 ## Parameters
 
-* **tile**: the [tile](/types/tile) location.
-* **on**: a [boolean](/types/boolean) value that sets the wall **ON** if `true` or **OFF** if `false` at the tile location.
+* **loc**: a tile [location](/reference/tiles/location) in the tilemap.
+* **on**: a [boolean](/types/boolean) value to set the tile location be a wall tile if `true` or a regular tile if `false`.
 
 ## Example #example
 
-Create a scene with two horizontal walls. Bounce a sprite between the walls.
+Make a column of tiles from top to bottom of the screen. Set a sprite in motion and set it to bounce on walls. Every `5` seconds, set the tiles  in the column to be wall tiles or regular tiles.
 
 ```blocks
-namespace myTiles {
-    //% blockIdentity=images._tile
-    export const tile0 = img`
-. . . . . . . . . . . . . . . . 
-. . . . . . . . . . . . . . . . 
-. . . . . . . . . . . . . . . . 
-. . . . . . . . . . . . . . . . 
-. . . . . . . . . . . . . . . . 
-. . . . . . . . . . . . . . . . 
-. . . . . . . . . . . . . . . . 
-. . . . . . . . . . . . . . . . 
-. . . . . . . . . . . . . . . . 
-. . . . . . . . . . . . . . . . 
-. . . . . . . . . . . . . . . . 
-. . . . . . . . . . . . . . . . 
-. . . . . . . . . . . . . . . . 
-. . . . . . . . . . . . . . . . 
-. . . . . . . . . . . . . . . . 
-. . . . . . . . . . . . . . . . 
-`
-}
-tiles.setTilemap(tiles.createTilemap(
-            hex`0a0008000000000000000000000009090909090909090909000000000000000000000000000000000000000000000000000000000000000000000000000000000909090909090909090900000000000000000000`,
-            img`
-. . . . . . . . . . 
-. . . . . . . . . . 
-. . . . . . . . . . 
-. . . . . . . . . . 
-. . . . . . . . . . 
-. . . . . . . . . . 
-. . . . . . . . . . 
-. . . . . . . . . . 
-`,
-            [myTiles.tile0,sprites.castle.tilePath4,sprites.castle.tilePath3,sprites.castle.tilePath1,sprites.castle.tilePath9,sprites.castle.tilePath6,sprites.castle.tilePath8,sprites.castle.tilePath7,sprites.castle.tilePath2,sprites.castle.tilePath5],
-            TileScale.Sixteen
-        ))
-for (let index = 0; index <= 9; index++) {
-    tiles.setWallAt(tiles.getTileLocation(index, 1), true)
-    tiles.setWallAt(tiles.getTileLocation(index, 6), true)
-}
+let isWall = false
+tiles.setTilemap(tilemap`level1`)
 let mySprite = sprites.create(img`
-2 5 5 5 5 5 5 5 5 5 5 5 5 5 2 2 
-2 2 2 5 5 5 5 5 5 5 5 5 5 2 2 3 
-7 7 2 2 5 5 5 5 5 5 5 5 2 2 3 3 
-7 7 7 2 2 5 5 5 5 5 5 2 2 3 3 3 
-7 7 7 7 2 5 5 5 5 5 2 2 3 3 3 3 
-7 7 7 7 7 2 5 5 5 5 2 3 3 3 3 3 
-7 7 7 7 7 2 2 5 5 2 2 3 3 3 3 3 
-7 7 7 7 7 7 2 2 2 2 3 3 3 3 3 3 
-7 7 7 7 7 7 7 2 2 3 3 3 3 3 3 3 
-7 7 7 7 7 7 7 2 2 2 2 3 3 3 3 3 
-7 7 7 7 7 7 2 2 4 4 4 2 2 3 3 3 
-7 7 7 7 7 2 4 4 4 4 4 4 2 2 3 3 
-7 7 7 2 2 4 4 4 4 4 4 4 4 2 3 3 
-7 7 2 2 4 4 4 4 4 4 4 4 4 2 2 3 
-7 2 2 4 4 4 4 4 4 4 4 4 4 4 2 3 
-2 2 4 4 4 4 4 4 4 4 4 4 4 4 2 2 
-`, SpriteKind.Player)
-mySprite.setVelocity(50, 50)
-mySprite.setFlag(SpriteFlag.BounceOnWall, true)
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . 1 1 1 1 1 1 . . . . . 
+    . . . 1 1 2 2 2 2 2 2 1 1 . . . 
+    . . . 1 2 2 2 2 2 2 2 2 1 . . . 
+    . . 1 2 2 2 2 2 2 2 2 2 2 1 . . 
+    . . 1 2 2 2 2 2 2 2 2 2 2 1 . . 
+    . . 1 2 2 2 2 2 2 2 2 2 2 1 . . 
+    . . 1 2 2 2 2 2 2 2 2 2 2 1 . . 
+    . . 1 2 2 2 2 2 2 2 2 2 2 1 . . 
+    . . 1 2 2 2 2 2 2 2 2 2 2 1 . . 
+    . . . 1 2 2 2 2 2 2 2 2 1 . . . 
+    . . . 1 1 2 2 2 2 2 2 1 1 . . . 
+    . . . . . 1 1 1 1 1 1 . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    `, SpriteKind.Player)
+mySprite.setBounceOnWall(true)
+mySprite.vx = 80
+mySprite.vy = 70
+game.onUpdateInterval(5000, function () {
+    isWall = !(isWall)
+    for (let wallTile of tiles.getTilesByType(assets.tile`myTile`)) {
+        tiles.setWallAt(wallTile, isWall)
+    }
+})
 ```
 
 ## See also #seealso
 
-[set tile](/reference/tiles/set-tile), [get tile location](/reference/tiles/get-tile-location)
+[get tile location](/reference/tiles/get-tile-location),
+[on hit wall](/reference/scene/on-hit-wall)
+
+```jres
+{
+    "transparency16": {
+        "data": "hwQQABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true
+    },
+    "tile1": {
+        "data": "hwQQABAAAADu7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7g==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile"
+    },
+    "level1": {
+        "id": "level1",
+        "mimeType": "application/mkcd-tilemap",
+        "data": "MTAwYTAwMDgwMDAwMDAwMDAwMDEwMDAwMDAwMDAwMDAwMDAwMDAwMDAxMDAwMDAwMDAwMDAwMDAwMDAxMDAwMDAwMDAwMDAwMDAwMDAwMDAwMTAwMDAwMDAwMDAwMDAwMDAwMTAwMDAwMDAwMDAwMDAwMDAwMDAwMDEwMDAwMDAwMDAwMDAwMDAwMDEwMDAwMDAwMDAwMDAwMDAwMDAwMDAxMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMA==",
+        "tileset": [
+            "myTiles.transparency16",
+            "myTiles.tile1"
+        ],
+        "displayName": "level1"
+    },
+    "*": {
+        "mimeType": "image/x-mkcd-f4",
+        "dataEncoding": "base64",
+        "namespace": "myTiles"
+    }
+}
+```

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

@@ -0,0 +1,97 @@
+# tile At Location Equals
+
+Check if a location in the tilemap contains the tile you're looking for.
+
+```sig
+tiles.tileAtLocationEquals(tiles.getTileLocation(0, 0), null)
+```
+
+## Parameters
+
+* **location**: a [location](/reference/scene/location) in the tilemap.
+* **tile**: an [image](/types/image) that matches the tile you're looking for.
+
+## Returns
+
+* a [boolean](/types/boolean) value that is `true` if the tile at **location** matches the **tile** you want to check for. If not, `false` is returned.
+
+## Example #example
+
+Make a tilemap with two columns of wall tiles with a different color for each.  Set a sprite in motion and cause it to bounce on walls. When the sprite contacts a tile, check to see what color the tile is.
+
+```blocks
+scene.onHitWall(SpriteKind.Player, function (sprite, location) {
+    if (tiles.tileAtLocationEquals(location, assets.tile`myTile0`)) {
+        mySprite.sayText("Blue", 500, false)
+    } else if (tiles.tileAtLocationEquals(location, assets.tile`myTile1`)) {
+        mySprite.sayText("Green", 500, false)
+    } else {
+        mySprite.startEffect(effects.fire, 200)
+    }
+})
+let mySprite: Sprite = null
+tiles.setTilemap(tilemap`level1`)
+mySprite = sprites.create(img`
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . 1 1 1 1 1 1 . . . . . 
+    . . . 1 1 2 2 2 2 2 2 1 1 . . . 
+    . . . 1 2 2 2 2 2 2 2 2 1 . . . 
+    . . 1 2 2 2 2 2 2 2 2 2 2 1 . . 
+    . . 1 2 2 2 2 2 2 2 2 2 2 1 . . 
+    . . 1 2 2 2 2 2 2 2 2 2 2 1 . . 
+    . . 1 2 2 2 2 2 2 2 2 2 2 1 . . 
+    . . 1 2 2 2 2 2 2 2 2 2 2 1 . . 
+    . . 1 2 2 2 2 2 2 2 2 2 2 1 . . 
+    . . . 1 2 2 2 2 2 2 2 2 1 . . . 
+    . . . 1 1 2 2 2 2 2 2 1 1 . . . 
+    . . . . . 1 1 1 1 1 1 . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    `, SpriteKind.Player)
+mySprite.setBounceOnWall(true)
+mySprite.vx = 40
+mySprite.vy = 35
+```
+
+## See also #seealso
+
+[get tile location](/reference/tiles/get-tile-location)
+
+```jres
+{
+    "transparency16": {
+        "data": "hwQQABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true
+    },
+    "tile1": {
+        "data": "hwQQABAAAACIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiA==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile0"
+    },
+    "tile2": {
+        "data": "hwQQABAAAAB3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3dw==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile1"
+    },
+    "level1": {
+        "id": "level1",
+        "mimeType": "application/mkcd-tilemap",
+        "data": "MTAwYTAwMDgwMDAyMDAwMDAwMDAwMDAwMDAwMDAxMDIwMDAwMDAwMDAwMDAwMDAwMDEwMjAwMDAwMDAwMDAwMDAwMDAwMTAyMDAwMDAwMDAwMDAwMDAwMDAxMDIwMDAwMDAwMDAwMDAwMDAwMDEwMjAwMDAwMDAwMDAwMDAwMDAwMTAyMDAwMDAwMDAwMDAwMDAwMDAxMDIwMDAwMDAwMDAwMDAwMDAwMDEwMjAwMDAwMDIwMDIwMDAwMDAyMDAyMDAwMDAwMjAwMjAwMDAwMDIwMDIwMDAwMDAyMDAyMDAwMDAwMjAwMjAwMDAwMDIwMDIwMDAwMDAyMA==",
+        "tileset": [
+            "myTiles.transparency16",
+            "myTiles.tile1",
+            "myTiles.tile2"
+        ],
+        "displayName": "level1"
+    },
+    "*": {
+        "mimeType": "image/x-mkcd-f4",
+        "dataEncoding": "base64",
+        "namespace": "myTiles"
+    }
+}
+```

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

@@ -0,0 +1,98 @@
+# tile At Location Is Wall
+
+Check if a tile at a location in the tilemap is also a wall tile.
+
+```sig
+tiles.tileAtLocationIsWall(null)
+```
+
+The tile in the tilemap at the location selected is checked to see if it is set as a wall. After they are placed in the tilemap with the Tilemap Editor, tiles can be set as _wall_ tiles.
+
+## Parameters
+
+* **location**: the [location](/reference/tiles/location) object for the tile to check if it's a wall.
+
+## Returns
+
+* a [boolean](/types/boolean) value that is `true` if the tile at **location** is a wall. The value is `false` if the tile is not a wall.
+
+## Example #example
+
+Set a tilemap with two columns of the same tile. Make one of the columns be all wall tiles. Send a ghost sprite across both colunms so it can detect which one is the wall.
+
+```blocks
+scene.onOverlapTile(SpriteKind.Player, assets.tile`myTile0`, function (sprite, location) {
+    if (tiles.tileAtLocationIsWall(location)) {
+        mySprite.sayText("That's a wall!")
+    } else {
+        mySprite.sayText("Not a wall.")
+    }
+})
+let mySprite: Sprite = null
+scene.setBackgroundColor(11)
+tiles.setCurrentTilemap(tilemap`level1`)
+mySprite = sprites.create(img`
+    ........................
+    ........................
+    ........................
+    ........................
+    ..........ffff..........
+    ........ff1111ff........
+    .......fb111111bf.......
+    .......f11111111f.......
+    ......fd11111111df......
+    ......fd11111111df......
+    ......fddd1111dddf......
+    ......fbdbfddfbdbf......
+    ......fcdcf11fcdcf......
+    .......fb111111bf.......
+    ......fffcdb1bdffff.....
+    ....fc111cbfbfc111cf....
+    ....f1b1b1ffff1b1b1f....
+    ....fbfbffffffbfbfbf....
+    .........ffffff.........
+    ...........fff..........
+    ........................
+    ........................
+    ........................
+    ........................
+    `, SpriteKind.Player)
+mySprite.left = 0
+mySprite.setFlag(SpriteFlag.GhostThroughWalls, true)
+mySprite.vx = 30
+```
+
+## See also #seealso
+
+[get tile location](/reference/tiles/get-tile-location)
+
+```jres
+{
+    "transparency16": {
+        "data": "hwQQABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true
+    },
+    "tile1": {
+        "data": "hwQQABAAAABmZmZmZmZmZmZvZmZmb2ZmZmZm9mZm9mZmZm9mb2ZmZvZmZmZmZm9mZmZmZmZmZmZmZmZmZmZmZmb2ZvZmb2Zm9mZmZmZm9mZmZmZmZmZmZmb2b2b2ZmZmZmZmZmZmZm9mZmb2ZmZmZmb2ZmZm9mZvZmZmZvZmZvZmZmZmZmZmZg==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile0"
+    },
+    "level1": {
+        "id": "level1",
+        "mimeType": "application/mkcd-tilemap",
+        "data": "MTAwYTAwMDgwMDAwMDAwMDAxMDAwMDAxMDAwMDAwMDAwMDAwMDEwMDAwMDEwMDAwMDAwMDAwMDAwMTAwMDAwMTAwMDAwMDAwMDAwMDAxMDAwMDAxMDAwMDAwMDAwMDAwMDEwMDAwMDEwMDAwMDAwMDAwMDAwMTAwMDAwMTAwMDAwMDAwMDAwMDAxMDAwMDAxMDAwMDAwMDAwMDAwMDEwMDAwMDEwMDAwMDAwMDAwMDAwMjAwMDAwMDAwMDIwMDAwMDAwMDAyMDAwMDAwMDAwMjAwMDAwMDAwMDIwMDAwMDAwMDAyMDAwMDAwMDAwMjAwMDAwMDAwMDIwMA==",
+        "tileset": [
+            "myTiles.transparency16",
+            "myTiles.tile1"
+        ],
+        "displayName": "level1"
+    },
+    "*": {
+        "mimeType": "image/x-mkcd-f4",
+        "dataEncoding": "base64",
+        "namespace": "myTiles"
+    }
+}
+```

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

@@ -0,0 +1,145 @@
+# tilemap
+
+A tilemap object that defines a player level for the game scene.
+
+```sig
+tiles._tilemapEditor(null)
+```
+
+A **tilemap** is a data object that contains the dimensions, layers, and tiles for a tile mapping used to set the scene of a game.
+
+## Creating and using tilemaps
+
+Tilemaps aren't coded by the user but are created using a tilemap editor. When you add a tilemap to your project, it contains a default layout having all of it rows and columns filled with transparent tiles.
+
+```block
+tiles.setCurrentTilemap(tilemap`level2`)
+```
+
+You modify the tilemap using the Tilemap Editor. When coding with blocks, the Tilemap Editor will open when you click on the map image in the tilemap block. If you're editing code, the Tilemap Editor opens by clicking the map symbol in the line of code where you use the tilemap.
+
+You design your game scene, or _level_, using the tiles your create or by chosing some from the tile library. You also can set the tilemap size and tile attributes. The example here shows a tilemap created for a maze game: 
+
+```block
+tiles.setCurrentTilemap(tilemap`level1`)
+```
+
+After editing, a tilemap is saved as a project asset. The tilemap is defined as a level and assigned an identifier like `level1`. In code, you use the tilemap with its identifier like this:
+
+```typescript-ignore
+tiles.setCurrentTilemap(tilemap`level1`)
+```
+
+You can use a tilemap directly in scene and tile operations, or as an assigned variable:
+
+```block
+let myTilemap = tilemap`level1`
+tiles.setCurrentTilemap(myTilemap)
+```
+
+## The tilemap object
+
+Tilemaps are complex data objects and are defined as levels which contain tiles at various row and column locations. When a tilemap is added to a project, the project assets will include both the tilemap and its tiles. A tilemap's asset data might look like the following:
+
+```typescript-ignore
+{
+    "transparency16": {
+        "data": "hwQQABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true
+    },
+    "tile1": {
+        "data": "hwQQABAAAABERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERA==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile"
+    },
+    "tile2": {
+        "data": "hwQQABAAAAB3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3dw==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile0"
+    },
+    "tile3": {
+        "data": "hwQQABAAAACqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqg==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile1"
+    },
+    "level1": {
+        "id": "level1",
+        "mimeType": "application/mkcd-tilemap",
+        "data": "MTAwYTAwMDgwMDAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMDAwMDAwMDAyMDAwMDAwMDEwMTAwMDMwMzAwMDIwMjAwMDAwMDAxMDAwMDAzMDAwMDAwMDAwMDAxMDEwMDAwMDAwMDAzMDAwMDAwMDEwMDAwMDIwMDAwMDMwMDAzMDAwMTAxMDAwMjAyMDAwMDAwMDMwMDAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMA==",
+        "tileset": [
+            "myTiles.transparency16",
+            "myTiles.tile1",
+            "myTiles.tile2",
+            "myTiles.tile3"
+        ],
+        "displayName": "level1"
+    },
+    "*": {
+        "mimeType": "image/x-mkcd-f4",
+        "dataEncoding": "base64",
+        "namespace": "myTiles"
+    }
+}
+```
+
+## See also
+
+[set current tilemap](/reference/tiles/set-current-tilemap)
+
+```jres
+{
+    "transparency16": {
+        "data": "hwQQABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true
+    },
+    "tile1": {
+        "data": "hwQQABAAAABERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERA==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile"
+    },
+    "tile2": {
+        "data": "hwQQABAAAAB3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3dw==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile0"
+    },
+    "tile3": {
+        "data": "hwQQABAAAACqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqg==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile1"    
+    },
+    "level1": {
+        "id": "level1",
+        "mimeType": "application/mkcd-tilemap",
+        "data": "MTAwYTAwMDgwMDAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMDAwMDAwMDAyMDAwMDAwMDEwMTAwMDMwMzAwMDIwMjAwMDAwMDAxMDAwMDAzMDAwMDAwMDAwMDAxMDEwMDAwMDAwMDAzMDAwMDAwMDEwMDAwMDIwMDAwMDMwMDAzMDAwMTAxMDAwMjAyMDAwMDAwMDMwMDAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMA==",
+        "tileset": [
+            "myTiles.transparency16",
+            "myTiles.tile1",
+            "myTiles.tile2",
+            "myTiles.tile3"
+        ],
+        "displayName": "level1"
+    },
+    "level2": {
+        "id": "level2",
+        "mimeType": "application/mkcd-tilemap",
+        "data": "MTAwYTAwMDgwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMA==",
+        "tileset": [
+            "myTiles.transparency16"
+        ],
+        "displayName": "level4"
+    },
+    "*": {
+        "mimeType": "image/x-mkcd-f4",
+        "dataEncoding": "base64",
+        "namespace": "myTiles"
+    }
+}
+```

package/libs/game/multiplayer.cpp

@@ -0,0 +1,25 @@
+#include "pxt.h"
+
+namespace multiplayer {
+    //%
+    void postImage(Image_ im, String goal) {
+        // no support >:(
+    }
+
+    //%
+    void setOrigin(String origin) {
+        // no
+    }
+
+    //%
+    Image_ getCurrentImage() {
+        // nah
+        return NULL;
+    }
+
+    //%
+    String getOrigin() {
+        return NULL;
+    }
+
+}

package/libs/game/multiplayer.ts

@@ -0,0 +1,24 @@
+namespace multiplayer {
+    //% shim=multiplayer::getCurrentImage
+    declare function getCurrentImage(): Image;
+
+    //% shim=multiplayer::setOrigin
+    declare function setOrigin(origin: string): void;
+
+    //% shim=multiplayer::getOrigin
+    declare function getOrigin(): string;
+
+    export function init() {
+        game.addScenePushHandler(() => {
+            game.eventContext().registerFrameHandler(scene.MULTIPLAYER_SCREEN_PRIORITY, () => {
+                if (getOrigin() === "client") {
+                    const im: Image = getCurrentImage();
+                    scene.setBackgroundImage(im);
+                    // clear default menu button behavior
+                    controller.menu.onEvent(ControllerButtonEvent.Pressed, () => { });
+                }
+            });
+        });
+        game.pushScene();
+    }
+}

package/libs/game/pxt.json

@@ -48,7 +48,9 @@
         "effects.ts",
         "texteffects.ts",
         "assetTemplates.ts",
-        "animation.ts"
+        "animation.ts",
+        "multiplayer.cpp",
+        "multiplayer.ts"
     ],
     "public": true,
     "dependencies": {

package/libs/game/scene.ts

@@ -63,6 +63,7 @@ namespace scene {
     export const RENDER_BACKGROUND_PRIORITY = 60;
     export const RENDER_SPRITES_PRIORITY = 90;
     export const RENDER_DIAGNOSTICS_PRIORITY = 150;
+    export const MULTIPLAYER_SCREEN_PRIORITY = 190;
     export const UPDATE_SCREEN_PRIORITY = 200;
 
     // default rendering z indices