pxt-common-packages 9.4.1 → 9.4.5

package/libs/game/docs/reference/scene/get-tile-location.md

@@ -0,0 +1,96 @@
+# get Tile Location
+
+Get the tile location object for a particular column and row position in the tilemap.
+
+```sig
+tiles.getTileLocation(0, 0)
+```
+
+A tile location object represents a column and a row position in the tilemap. Location objects are used to get and set tiles or tile information for specific places in the tilemap.
+
+## Parameters
+
+* **col**: a [number](/types/number) that is the tilemap column of the tile location.
+* **row**: a [number](/types/number) that is the tilemap row of the tile location.
+
+## Returns
+
+* a tile location object for a given column and row in the tilemap.
+
+## Example #example
+
+Make a grid tilemap with two tile colors. Create a round shaped sprite. Ramdomly choose a tile location to place the sprite at in the grid.
+
+```blocks
+tiles.setTilemap(tilemap`level1`)
+let mySprite = sprites.create(img`
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . 7 7 7 7 7 7 . . . . . 
+    . . . 7 7 7 7 7 7 7 7 7 7 . . . 
+    . . . 7 7 7 7 7 7 7 7 7 7 . . . 
+    . . 7 7 7 7 7 7 7 7 7 7 7 7 . . 
+    . . 7 7 7 7 7 7 7 7 7 7 7 7 . . 
+    . . 7 7 7 7 7 7 7 7 7 7 7 7 . . 
+    . . 7 7 7 7 7 7 7 7 7 7 7 7 . . 
+    . . 7 7 7 7 7 7 7 7 7 7 7 7 . . 
+    . . 7 7 7 7 7 7 7 7 7 7 7 7 . . 
+    . . . 7 7 7 7 7 7 7 7 7 7 . . . 
+    . . . 7 7 7 7 7 7 7 7 7 7 . . . 
+    . . . . . 7 7 7 7 7 7 . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    `, SpriteKind.Player)
+
+forever(function () {
+    tiles.placeOnTile(mySprite, tiles.getTileLocation(randint(0, 9), randint(0, 6)))
+    pause(500)
+})
+```
+
+## Returns
+
+* a tile location for the column and row specifed.
+
+## See also #seealso
+
+[set tile at](/reference/scene/set-tile-at),
+[place on tile](/reference/scene/place-on-tile)
+
+```jres
+{
+    "transparency16": {
+        "data": "hwQQABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true
+    },
+    "tile1": {
+        "data": "hwQQABAAAADd3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3Q==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile"
+    },
+    "tile2": {
+        "data": "hwQQABAAAABVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVQ==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile0"
+    },
+    "level1": {
+        "id": "level1",
+        "mimeType": "application/mkcd-tilemap",
+        "data": "MTAwYTAwMDgwMDAxMDIwMTAyMDEwMjAxMDIwMTAyMDIwMTAyMDEwMjAxMDIwMTAyMDEwMTAyMDEwMjAxMDIwMTAyMDEwMjAyMDEwMjAxMDIwMTAyMDEwMjAxMDEwMjAxMDIwMTAyMDEwMjAxMDIwMjAxMDIwMTAyMDEwMjAxMDIwMTAxMDIwMTAyMDEwMjAxMDIwMTAyMDIwMTAyMDEwMjAxMDIwMTAyMDEwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMA==",
+        "tileset": [
+            "myTiles.transparency16",
+            "myTiles.tile1",
+            "myTiles.tile2"
+        ],
+        "displayName": "level1"
+    },
+    "*": {
+        "mimeType": "image/x-mkcd-f4",
+        "dataEncoding": "base64",
+        "namespace": "myTiles"
+    }
+}
+```

package/libs/game/docs/reference/scene/get-tiles-by-type.md

@@ -1,65 +1,86 @@
 # get Tiles By Type
 
-Get a list of tiles in the tilemap that have the same color index.
+Return an array of tile locations from the tilemap that contain the specified tile.
 
 ```sig
-scene.getTilesByType(0)
+tiles.getTilesByType(null)
 ```
 
-All the tiles in the tilemap with the chosen **index** are returned in an array of [tiles](/types/tile). You can use this array to change or replace the tiles as one group.
-
 ## Parameters
 
-* **index**: the color index to the tiles to make a list for.
+* **tile**: a tile [image](/types/image) to search the tilemap for.
 
 ## Returns
 
-* an [array](/types/array) of [tiles](/types/tile) from the tilemap that have the same color **index**.
+* an [array](/types/array) of tile locations from the tilemap that have the tile specified in **tile**.
 
 ## Example #example
 
-Get a list of all the tiles in the center of the tilemap. Replace all of them with the tile type used for the border.
+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, find the column tiles in the tilemap and set them as either wall tiles or regular tiles.
 
 ```blocks
-scene.setTile(2, img`
-a a a a a a a a a a a a a a a a 
-a a a a a a a a a a a a a a a a 
-a a a a a a a a a a a a a a a a 
-a a a a a a a a a a a a a a a a 
-a a a a a a a a a a a a a a a a 
-a a a a a a a a a a a a a a a a 
-a a a a a a a a a a a a a a a a 
-a a a a a a a a a a a a a a a a 
-a a a a a a a a a a a a a a a a 
-a a a a a a a a a a a a a a a a 
-a a a a a a a a a a a a a a a a 
-a a a a a a a a a a a a a a a a 
-a a a a a a a a a a a a a a a a 
-a a a a a a a a a a a a a a a a 
-a a a a a a a a a a a a a a a a 
-a a a a a a a a a a a a a a a a 
-`)
-scene.setTileMap(img`
-2 2 2 2 2 2 2 2 2 2 
-2 8 . . . 8 . . . 2 
-2 . 8 . 8 . 8 . 8 2 
-2 . . 8 . . . 8 . 2 
-2 . 8 . 8 . 8 . 8 2 
-2 8 . . . 8 . . . 2 
-2 2 2 2 2 2 2 2 2 2 
-. . . . . . . . . . 
-`)
-for (let tile of scene.getTilesByType(8)) {
-    scene.setTileAt(tile, 2)
-    pause(500)
-}
+let isWall = false
+tiles.setTilemap(tilemap`level1`)
+let 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 = 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
 
-[get tile](/reference/scene/get-tile),
-[set tile at](/reference/scene/set-tile-at)
+[get tile location](/reference/scene/get-tile-location)
 
-```package
-color-coded-tilemap
+```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/scene/is-hitting-tile.md

@@ -0,0 +1,87 @@
+# is Hitting Tile
+
+Check if a sprite is currently hitting a wall.
+
+```sig
+sprites.create(null).isHittingTile(CollisionDirection.Right)
+```
+
+A wall is either a tile set as a wall or the edge of the scene if a tilemap is set.
+
+## Parameters
+
+* **direction**: the direction the sprite moves toward when detecting a wall collision: `left`, `right`, `top`, or `bottom`.
+
+## Returns
+
+* a [boolean](/types/boolean) value that is `true` if the sprite is hitting a wall on the chosen side or `false` if not.
+
+## Example #example
+
+Make a tilemap with a wall going from top to bottom. Set a sprite in motion and make it say "Ouch!" when it hits the wall on its `right` side.
+
+```blocks
+tiles.setTilemap(tilemap`level1`)
+let 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 = 80
+mySprite.vy = 70
+forever(function () {
+    if (mySprite.isHittingTile(CollisionDirection.Right)) {
+        mySprite.sayText("Ouch!", 200, false)
+    }
+})
+```
+
+## See also #seealso
+
+[tile kind at](/reference/scene/tile-kind-at),
+[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": "myTile"
+    },
+    "level1": {
+        "id": "level1",
+        "mimeType": "application/mkcd-tilemap",
+        "data": "MTAwYTAwMDgwMDAwMDAwMDAwMDAwMDAwMDEwMDAwMDAwMDAwMDAwMDAwMDAwMTAwMDAwMDAwMDAwMDAwMDAwMDAxMDAwMDAwMDAwMDAwMDAwMDAwMDEwMDAwMDAwMDAwMDAwMDAwMDAwMTAwMDAwMDAwMDAwMDAwMDAwMDAxMDAwMDAwMDAwMDAwMDAwMDAwMDEwMDAwMDAwMDAwMDAwMDAwMDAwMTAwMDAwMDAwMDAyMDAwMDAwMDAwMjAwMDAwMDAwMDIwMDAwMDAwMDAyMDAwMDAwMDAwMjAwMDAwMDAwMDIwMDAwMDAwMDAyMDAwMDAwMDAwMjAwMA==",
+        "tileset": [
+            "myTiles.transparency16",
+            "myTiles.tile1"
+        ],
+        "displayName": "level1"
+    },
+    "*": {
+        "mimeType": "image/x-mkcd-f4",
+        "dataEncoding": "base64",
+        "namespace": "myTiles"
+    }
+}
+```

package/libs/game/docs/reference/scene/on-hit-wall.md

@@ -0,0 +1,88 @@
+# on Hit Wall
+
+Run code when a sprite contacts a wall tile.
+
+```sig
+scene.onHitWall(SpriteKind.Player, function (sprite, location) { })
+```
+
+You can detect when a moving sprite contacts a wall tile in the tilemap. If your sprite touches a tile that is set as a wall, you can have some code that runs when that happens. You pick the sprite **kind** to check for.
+
+When a wall hit is detected by the sprite of the kind you asked for, it is given to you in the **sprite** parameter of **handler** along with contacted tile's **location**.
+
+A sprite hitting a wall is dectected when the outside edges of its image makes contact with the tile. If a sprite has it's ``ghost`` flag set, any contact with the wall tile isn't noticed.
+
+## Parameters
+
+* **kind**: the type of sprite to check for a wall hit.
+* **handler**: the code to run when the sprite makes contact. The handler has these parameters passed to it:
+>* **sprite**: the sprite that hit the wall tile.
+>* **location**: the location of the wall the sprite contacted in the tilemap.
+
+## Example #example
+
+Create a tilemap with wall tiles surrounding the sides of the scene. Set a sprite in motion and cause it to bounce on wall tiles. When the sprite contacts the wall tiles, make a short fire effect on the sprite.
+
+```blocks
+scene.onHitWall(SpriteKind.Player, function (sprite, location) {
+    sprite.startEffect(effects.fire, 200)
+})
+tiles.setTilemap(tilemap`level1`)
+let 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 = 80
+mySprite.vy = 70
+```
+
+## See also #seealso
+
+[get tile location](/reference/scene/get-tile-location),
+[set wall at](/reference/scene/set-wall-at)
+
+```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": "MTAwYTAwMDgwMDAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMDAwMDAwMDAwMDAwMDAwMDEwMTAwMDAwMDAwMDAwMDAwMDAwMTAxMDAwMDAwMDAwMDAwMDAwMDAxMDEwMDAwMDAwMDAwMDAwMDAwMDEwMTAwMDAwMDAwMDAwMDAwMDAwMTAxMDAwMDAwMDAwMDAwMDAwMDAxMDEwMTAxMDEwMTAxMDEwMTAxMDEyMjIyMjIyMjIyMDIwMDAwMDAyMDAyMDAwMDAwMjAwMjAwMDAwMDIwMDIwMDAwMDAyMDAyMDAwMDAwMjAwMjAwMDAwMDIwMjIyMjIyMjIyMg==",
+        "tileset": [
+            "myTiles.transparency16",
+            "myTiles.tile1"
+        ],
+        "displayName": "level1"
+    },
+    "*": {
+        "mimeType": "image/x-mkcd-f4",
+        "dataEncoding": "base64",
+        "namespace": "myTiles"
+    }
+}
+```

package/libs/game/docs/reference/scene/on-overlap-tile.md

@@ -0,0 +1,88 @@
+# on Overlap Tile
+
+Run code when a sprite overlaps a tile.
+
+```sig
+scene.onOverlapTile(SpriteKind.Player, null, function (sprite, location) {})
+```
+
+You can detect when a moving sprite overlaps a tile in the tilemap. If your sprite moves across a tile, you can have some code that runs when that happens. You pick the sprite **kind** to check for.
+
+When an overlap is detected by the sprite of the kind you asked for, it is given to you in the **sprite** parameter of **handler** along with overlapped tile's **location**.
+
+A sprite hitting a wall is dectected when the outside edges of its image makes starts to overlap the tile.
+
+## Parameters
+
+* **kind**: the type of sprite to check for a overlap.
+* **handler**: the code to run when the sprite overlaps a tile. The handler has these parameters passed to it:
+>* **sprite**: the sprite that overlapped the tile.
+>* **location**: the location of the tile that the sprite overlapped in the tilemap.
+
+## Example #example
+
+Create a tilemap with a section of tiles in the center of the scene. Set a sprite in motion and cause it to bounce on walls. When the sprite overlaps the tiles, make it trace a trail across the tiles.
+
+```blocks
+scene.onOverlapTile(SpriteKind.Player, assets.tile`myTile`, function (sprite, location) {
+    sprite.startEffect(effects.trail, 100)
+})
+tiles.setTilemap(tilemap`level1`)
+let 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 = 80
+mySprite.vy = 70
+```
+
+## See also #seealso
+
+[get tile location](/reference/scene/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": "MTAwYTAwMDgwMDAwMDAwMDAwMDEwMTAwMDAwMDAwMDAwMDAwMDAwMTAxMDAwMDAwMDAwMDAwMDAwMDAxMDEwMDAwMDAwMDAwMDAwMDAwMDEwMTAwMDAwMDAwMDAwMDAwMDAwMTAxMDAwMDAwMDAwMDAwMDAwMDAxMDEwMDAwMDAwMDAwMDAwMDAwMDEwMTAwMDAwMDAwMDAwMDAwMDAwMTAxMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMA==",
+        "tileset": [
+            "myTiles.transparency16",
+            "myTiles.tile1"
+        ],
+        "displayName": "level1"
+    },
+    "*": {
+        "mimeType": "image/x-mkcd-f4",
+        "dataEncoding": "base64",
+        "namespace": "myTiles"
+    }
+}
+```

package/libs/game/docs/reference/scene/place-on-random-tile.md

@@ -3,63 +3,117 @@
 Move a sprite's position to the center of a random tile in the scene.
 
 ```sig
-scene.placeOnRandomTile(null, 0)
+tiles.placeOnRandomTile(null, null)
 ```
 
-You a can make a sprite to locate itself right on top of a random tile in the tile map. Use the color number of type of tile to select for the sprite to locate on one of them.
-
+You can make a sprite locate itself right on top of a random tile in the tilemap. Choose a tile in the tilemap to indicate which type of tile to have the sprite randomly placed on. If there is only one tile of that type, the sprite will always go to that tile. If multiple tiles of the same type are in the tilemap, then the sprite will randomly locate on any one of them.
 
 ## Parameters
 
 * **sprite**: the sprite to move onto the tile.
-* **color**: the color [number](/types/number) of a tile to randomly select.
+* **tile**: the tile type to randomly select in the tilemap.
 
 ## Example #example
 
-Make a tilemap with several different tiles. Create a round shaped sprite. Ramdomly place the sprite on a tile with color number `8`.
+Make a tilemap with several different tiles. Create a round shaped sprite. Ramdomly place the sprite on a blue tile.
 
 ```blocks
-enum SpriteKind {
-    Player,
-    Enemy
-}
-let mySprite: Sprite = null
-scene.setTileMap(img`
-. . . . . . . . 3 . 
-. 2 . . . . . . . . 
-. . . . . 8 . . . . 
-. . . . . . . b . . 
-. . 8 . 6 . . . . . 
-. . . . . . 4 . . . 
-. a . . . . . . . . 
-. . . . . . . . e . 
-`)
-mySprite = sprites.create(img`
-. . . . . . . . . . . . . . . . 
-. . . . . . . . . . . . . . . . 
-. . . . . 7 7 7 7 7 7 . . . . . 
-. . . 7 7 7 7 7 7 7 7 7 7 . . . 
-. . . 7 7 7 7 7 7 7 7 7 7 . . . 
-. . 7 7 7 7 7 7 7 7 7 7 7 7 . . 
-. . 7 7 7 7 7 7 7 7 7 7 7 7 . . 
-. . 7 7 7 7 7 7 7 7 7 7 7 7 . . 
-. . 7 7 7 7 7 7 7 7 7 7 7 7 . . 
-. . 7 7 7 7 7 7 7 7 7 7 7 7 . . 
-. . 7 7 7 7 7 7 7 7 7 7 7 7 . . 
-. . . 7 7 7 7 7 7 7 7 7 7 . . . 
-. . . 7 7 7 7 7 7 7 7 7 7 . . . 
-. . . . . 7 7 7 7 7 7 . . . . . 
-. . . . . . . . . . . . . . . . 
-. . . . . . . . . . . . . . . . 
-`, SpriteKind.Player)
+tiles.setTilemap(tilemap`level1`)
+let mySprite = sprites.create(img`
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . 7 7 7 7 7 7 . . . . . 
+    . . . 7 7 7 7 7 7 7 7 7 7 . . . 
+    . . . 7 7 7 7 7 7 7 7 7 7 . . . 
+    . . 7 7 7 7 7 7 7 7 7 7 7 7 . . 
+    . . 7 7 7 7 7 7 7 7 7 7 7 7 . . 
+    . . 7 7 7 7 7 7 7 7 7 7 7 7 . . 
+    . . 7 7 7 7 7 7 7 7 7 7 7 7 . . 
+    . . 7 7 7 7 7 7 7 7 7 7 7 7 . . 
+    . . 7 7 7 7 7 7 7 7 7 7 7 7 . . 
+    . . . 7 7 7 7 7 7 7 7 7 7 . . . 
+    . . . 7 7 7 7 7 7 7 7 7 7 . . . 
+    . . . . . 7 7 7 7 7 7 . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    `, SpriteKind.Player)
 pause(1000)
-scene.placeOnRandomTile(mySprite, 8)
+tiles.placeOnRandomTile(mySprite, assets.tile`myTile`)
 ```
 
 ## See also #seealso
 
 [get tile](/reference/scene/get-tile)
 
-```package
-color-coded-tilemap
+```jres
+{
+    "transparency16": {
+        "data": "hwQQABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true
+    },
+    "tile7": {
+        "data": "hwQQABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile5"
+    },
+    "tile1": {
+        "data": "hwQQABAAAACIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiA==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile"
+    },
+    "tile2": {
+        "data": "hwQQABAAAAAiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIiIg==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile0"
+    },
+    "tile3": {
+        "data": "hwQQABAAAABVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVQ==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile1"
+    },
+    "tile4": {
+        "data": "hwQQABAAAAB3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3d3dw==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile2"
+    },
+    "tile5": {
+        "data": "hwQQABAAAACqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqg==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile3"
+    },
+    "tile6": {
+        "data": "hwQQABAAAACZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmQ==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile4"
+    },
+    "level1": {
+        "id": "level1",
+        "mimeType": "application/mkcd-tilemap",
+        "data": "MTAwYTAwMDgwMDAwMDAwMDAwMDAwMDAzMDAwMDAwMDAwMDA2MDAwMDAwMDAwMDAyMDAwMDAxMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDMwMDAwMDAwMDAwMDAwMDA1MDAwMDAwMDAwMTAwMDAwMDAwMDAwMDA0MDAwMDAwMDAwMDAwMDYwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMA==",
+        "tileset": [
+            "myTiles.transparency16",
+            "myTiles.tile1",
+            "myTiles.tile2",
+            "myTiles.tile3",
+            "myTiles.tile4",
+            "myTiles.tile5",
+            "myTiles.tile6",
+            "myTiles.tile7"
+        ],
+        "displayName": "level1"
+    },
+    "*": {
+        "mimeType": "image/x-mkcd-f4",
+        "dataEncoding": "base64",
+        "namespace": "myTiles"
+    }
+}
 ```