pxt-common-packages 9.5.1 → 9.5.2

package/libs/game/controllerbutton.ts

@@ -41,6 +41,17 @@ namespace controller {
         return // missing in sim
      }
 
+    export class ButtonHandler {
+        constructor(public event: number, public callback: () => void) { }
+    }
+
+    export class ButtonEventHandlerState {
+        constructor(public id: number) {};
+
+        public user: ButtonHandler[];
+        public system: ButtonHandler[];
+    }
+
     //% fixedInstances
     export class Button {
         _owner: Controller;
@@ -53,6 +64,13 @@ namespace controller {
         private _pressedElasped: number;
         private _repeatCount: number;
 
+        protected get handlerState(): ButtonEventHandlerState {
+            for (const state of game.currentScene().buttonEventHandlers) {
+                if (state.id === this.id) return state;
+            }
+            return undefined;
+        }
+
         toString(): string {
             return `btn ${this.id} ${this._pressed ? "down" : "up"}`;
         }
@@ -63,6 +81,7 @@ namespace controller {
             this.repeatDelay = undefined;
             this.repeatInterval = undefined;
             this._repeatCount = 0;
+
             if (id > 0) {
                 // this is to deal with the "anyButton" hack, which creates a button that is not visible
                 // in the UI, but used in event-handler to simulate the wildcard ANY for matching. As
@@ -103,7 +122,49 @@ namespace controller {
         //% blockId=keyonevent block="on %button **button** %event"
         //% group="Single Player"
         onEvent(event: ControllerButtonEvent, handler: () => void) {
-            control.onEvent(event, this.id, handler);
+            const eventHandler = this.getOrCreateHandlerForEvent(event);
+            eventHandler.callback = handler;
+        }
+
+        /**
+         * Adds an event handler that will fire whenever the specified event
+         * is triggered on this button. Handlers added using this method will
+         * not conflict with events added via onEvent. The same handler can
+         * not be added for the same event more than once.
+         *
+         * @param event     The event to subscribe to for this button
+         * @param handler   The code to run when the event triggers
+         */
+        addEventListener(event: ControllerButtonEvent, handler: () => void) {
+            this.getOrCreateHandlerForEvent(event);
+
+            const handlerState = this.handlerState;
+
+            if (!handlerState.system) handlerState.system = [];
+
+            for (const eventHandler of handlerState.system) {
+                if (eventHandler.event === event && eventHandler.callback === handler) return;
+            }
+
+            handlerState.system.push(new ButtonHandler(event, handler));
+        }
+
+        /**
+         * Removes an event handler registered with addEventListener.
+         *
+         * @param event     The event that the handler was registered for
+         * @param handler   The handler to remove
+         */
+        removeEventListener(event: ControllerButtonEvent, handler: () => void) {
+            const handlerState = this.handlerState;
+            if (!handlerState || !handlerState.system) return;
+
+            for (let i = 0; i < handlerState.system.length; i++) {
+                if (handlerState.system[i].event === event && handlerState.system[i].callback === handler) {
+                    handlerState.system.splice(i, 1)
+                    return;
+                }
+            }
         }
 
         /**
@@ -172,6 +233,42 @@ namespace controller {
                 this._repeatCount = count;
             }
         }
+
+        protected runButtonEvents(event: ControllerButtonEvent) {
+            const handlerState = this.handlerState;
+            if (!handlerState) return;
+
+            const userHandler = this.getOrCreateHandlerForEvent(event);
+            if (userHandler.callback) userHandler.callback();
+
+            if (handlerState.system) {
+                for (const eventHandler of handlerState.system) {
+                    if (eventHandler.event === event && eventHandler.callback) eventHandler.callback();
+                }
+            }
+        }
+
+        protected getOrCreateHandlerForEvent(event: ControllerButtonEvent) {
+            if (!this.handlerState) {
+                game.currentScene().buttonEventHandlers.push(new ButtonEventHandlerState(this.id));
+            }
+
+            const handlerState = this.handlerState;
+            if (!handlerState.user) handlerState.user = [];
+
+            for (const eventHandler of handlerState.user) {
+                if (eventHandler.event === event) {
+                    return eventHandler;
+                }
+            }
+
+            // Register actual handler if this hasn't been used before
+            control.onEvent(event, this.id, () => this.runButtonEvents(event));
+
+            const newHandler = new ButtonHandler(event, undefined);
+            handlerState.user.push(newHandler);
+            return newHandler;
+        }
     }
 
     /**

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

@@ -0,0 +1,123 @@
+# get Neighboring Location
+
+Get the location of a tile next to this one.
+
+```sig
+tiles.getTileLocation(0, 0).getNeighboringLocation(CollisionDirection.Top)
+```
+
+A neighboring tile is one that is immediately to the `left`, `right`, `top`, or `bottom` side of the current tile. You can specify the side of the neighboring tile you want the location for.
+
+## Parameters
+
+* **direction**: the direction side for the neighbor tile from this tile. The directions to choose from are `left`, `right`, `top`, or `bottom`.
+
+## Returns
+
+* a [location](/reference/scene/location) object for the neighbor tile.
+
+## Example #example
+
+Rotate a donut sprite around adjacent tiles in a tilemap.
+
+```blocks
+let nextSpot: tiles.Location = null
+let rotation = 0
+tiles.setCurrentTilemap(tilemap`level1`)
+let mySprite = sprites.create(img`
+    . . . . . . b b b b a a . . . . 
+    . . . . b b d d d 3 3 3 a a . . 
+    . . . b d d d 3 3 3 3 3 3 a a . 
+    . . b d d 3 3 3 3 3 3 3 3 3 a . 
+    . b 3 d 3 3 3 3 3 b 3 3 3 3 a b 
+    . b 3 3 3 3 3 a a 3 3 3 3 3 a b 
+    b 3 3 3 3 3 a a 3 3 3 3 d a 4 b 
+    b 3 3 3 3 b a 3 3 3 3 3 d a 4 b 
+    b 3 3 3 3 3 3 3 3 3 3 d a 4 4 e 
+    a 3 3 3 3 3 3 3 3 3 d a 4 4 4 e 
+    a 3 3 3 3 3 3 3 d d a 4 4 4 e . 
+    a a 3 3 3 d d d a a 4 4 4 e e . 
+    . e a a a a a a 4 4 4 4 e e . . 
+    . . e e b b 4 4 4 4 b e e . . . 
+    . . . e e e e e e e e . . . . . 
+    . . . . . . . . . . . . . . . . 
+    `, SpriteKind.Player)
+mySprite.x = mySprite.x - mySprite.width
+game.onUpdateInterval(1000, function () {
+    if (rotation == 0) {
+        nextSpot = mySprite.tilemapLocation().getNeighboringLocation(CollisionDirection.Right)
+    } else if (rotation == 1) {
+        nextSpot = mySprite.tilemapLocation().getNeighboringLocation(CollisionDirection.Bottom)
+    } else if (rotation == 2) {
+        nextSpot = mySprite.tilemapLocation().getNeighboringLocation(CollisionDirection.Left)
+    } else {
+        nextSpot = mySprite.tilemapLocation().getNeighboringLocation(CollisionDirection.Top)
+    }
+    mySprite.setPosition(nextSpot.x, nextSpot.y)
+    rotation += 1
+    if (rotation > 3) {
+        rotation = 0
+    }
+})
+```
+
+## See also #seealso
+
+[get tile location](/reference/scene/get-tile-location)
+
+```jres
+{
+    "transparency16": {
+        "data": "hwQQABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true
+    },
+    "tile1": {
+        "data": "hwQQABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile"
+    },
+    "tile2": {
+        "data": "hwQQABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true,
+        "displayName": "myTile0"
+    },
+    "tile3": {
+        "data": "hwQQABAAAABERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERA==",
+        "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"
+    },
+    "level1": {
+        "id": "level1",
+        "mimeType": "application/mkcd-tilemap",
+        "data": "MTAwYTAwMDgwMDAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMzAyMDMwMjAzMDIwMzAyMDEwMTAyMDMwMjAzMDIwMzAyMDMwMTAxMDMwMjAzMDIwMzAyMDMwMjAxMDEwMjAzMDIwMzAyMDMwMjAzMDEwMTAzMDIwMzAyMDMwMjAzMDIwMTAxMDIwMzAyMDMwMjAzMDIwMzAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMA==",
+        "tileset": [
+            "myTiles.transparency16",
+            "myTiles.tile3",
+            "myTiles.tile4",
+            "myTiles.tile5"
+        ],
+        "displayName": "level1"
+    },
+    "*": {
+        "mimeType": "image/x-mkcd-f4",
+        "dataEncoding": "base64",
+        "namespace": "myTiles"
+    }
+}
+```

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

@@ -15,7 +15,7 @@ A tile location object represents a column and a row position in the tilemap. Lo
 
 ## Returns
 
-* a tile location object for a given column and row in the tilemap.
+* a tile [location](/reference/scene/location) object for a given column and row in the tilemap.
 
 ## Example #example
 
@@ -48,10 +48,6 @@ forever(function () {
 })
 ```
 
-## Returns
-
-* a tile location for the column and row specifed.
-
 ## See also #seealso
 
 [set tile at](/reference/scene/set-tile-at),

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

@@ -0,0 +1,246 @@
+# Location
+
+The Location object contains the postition information of a game element on the tilemap.
+
+## column (property)
+
+Get a tile column position of an object on the tilemap.
+
+```block
+let location: tiles.Location = null
+
+let col = location.column
+```
+
+```typescript-ignore
+let col = location.column
+```
+
+### Returns
+
+* a [number](/types/number) that is the tile column position of object on the tilemap.
+
+## row (property)
+
+Get a tile row position of an object on the tilemap.
+
+```block
+let location: tiles.Location = null
+
+let row = location.row
+```
+
+```typescript-ignore
+let row = location.row
+```
+
+### Returns
+
+* a [number](/types/number) that is the tile row position of object on the tilemap.
+
+## x (property)
+
+Get the horizontal center position of an object on the tilemap.
+
+```block
+let location: tiles.Location = null
+
+let horz = location.x
+```
+
+```typescript-ignore
+let horz = location.x
+```
+
+### Returns
+
+* a [number](/types/number) that is the current horizontal center position, in pixels, of the object on the tilemap.
+
+## y (property)
+
+Get the vertical center position of an object on the tilemap.
+
+```block
+let location: tiles.Location = null
+
+let vert = location.y
+```
+
+```typescript-ignore
+let vert = location.y
+```
+
+### Returns
+
+* a [number](/types/number) that is the vertical center position, in pixels, of object on the tilemap.
+
+## left (property)
+
+Get the of position of left side an object on the tilemap.
+
+```block
+let location: tiles.Location = null
+
+let left = location.left
+```
+
+```typescript-ignore
+let left = location.left
+```
+
+### Returns
+
+* a [number](/types/number) that is the left side, in pixels, of object on the tilemap.
+
+## right (property)
+
+Get the of position of right side an object on the tilemap.
+
+```block
+let location: tiles.Location = null
+
+let right = location.right
+```
+
+```typescript-ignore
+let right = location.right
+```
+
+### Returns
+
+* a [number](/types/number) that is the right side, in pixels, of object on the tilemap.
+
+## top (property)
+
+Get the of position of top side an object on the tilemap.
+
+```block
+let location: tiles.Location = null
+
+let top = location.top
+```
+
+```typescript-ignore
+let top = location.top
+```
+
+### Returns
+
+* a [number](/types/number) that is the right side, in pixels, of object on the tilemap.
+
+## bottom (property)
+
+Get the of position of bottom side an object on the tilemap.
+
+```block
+let location: tiles.Location = null
+
+let bottom = location.bottom
+```
+
+```typescript-ignore
+let bottom = location.bottom
+```
+
+### Returns
+
+* a [number](/types/number) that is the right side, in pixels, of object on the tilemap.
+
+## Example #example
+
+Make checkered table cloth with tiles on a tilemap. Create a hamburger sprite and randomly locate it on the table cloth. Find out where the hamburger is and display its location.
+
+```blocks
+tiles.setCurrentTilemap(tilemap`level1`)
+let mySprite = sprites.create(img`
+    ...........ccccc66666...........
+    ........ccc4444444444666........
+    ......cc444444444bb4444466......
+    .....cb4444bb4444b5b444444b.....
+    ....eb4444b5b44444b44444444b....
+    ...ebb44444b4444444444b444446...
+    ..eb6bb444444444bb444b5b444446..
+    ..e6bb5b44444444b5b444b44bb44e..
+    .e66b4b4444444444b4444444b5b44e.
+    .e6bb444444444444444444444bb44e.
+    eb66b44444bb444444444444444444be
+    eb66bb444b5b44444444bb44444444be
+    fb666b444bb444444444b5b4444444bf
+    fcb666b44444444444444bb444444bcf
+    .fbb6666b44444444444444444444bf.
+    .efbb66666bb4444444444444444bfe.
+    .86fcbb66666bbb44444444444bcc688
+    8772effcbbbbbbbbbbbbbbbbcfc22778
+    87722222cccccccccccccccc22226678
+    f866622222222222222222222276686f
+    fef866677766667777776667777fffef
+    fbff877768f86777777666776fffffbf
+    fbeffeefffeff7766688effeeeefeb6f
+    f6bfffeffeeeeeeeeeeeeefeeeeebb6e
+    f66ddfffffeeeffeffeeeeeffeedb46e
+    .c66ddd4effffffeeeeeffff4ddb46e.
+    .fc6b4dddddddddddddddddddb444ee.
+    ..ff6bb444444444444444444444ee..
+    ....ffbbbb4444444444444444ee....
+    ......ffebbbbbb44444444eee......
+    .........fffffffcccccee.........
+    ................................
+    `, SpriteKind.Player)
+mySprite.setPosition(randint(16, 144), randint(16, 104))
+let location = mySprite.tilemapLocation()
+let displayString = "My hamburger is at "
+displayString = "" + displayString + "x = "
+displayString = "" + displayString + location.x + ", y = " + location.y
+displayString = "" + displayString + " and over the tile at column = "
+displayString = "" + displayString + location.column + ", row = " + location.row
+game.showLongText(displayString, DialogLayout.Bottom)
+```
+
+## See also #seealso
+
+[get neighboring location](/reference/scene/get-neighboring-location)
+
+```jres
+{
+    "transparency16": {
+        "data": "hwQQABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+        "mimeType": "image/x-mkcd-f4",
+        "tilemapTile": true
+    },
+    "tile3": {
+        "data": "hwQQABAAAABERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERA==",
+        "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"
+    },
+    "level1": {
+        "id": "level1",
+        "mimeType": "application/mkcd-tilemap",
+        "data": "MTAwYTAwMDgwMDAzMDEwMzAxMDMwMTAzMDEwMzAxMDEwMzAyMDMwMjAzMDIwMzAyMDMwMzAyMDMwMjAzMDIwMzAyMDMwMTAxMDMwMjAzMDIwMzAyMDMwMjAzMDMwMjAzMDIwMzAyMDMwMjAzMDEwMTAzMDIwMzAyMDMwMjAzMDIwMzAzMDIwMzAyMDMwMjAzMDIwMzAxMDEwMzAxMDMwMTAzMDEwMzAxMDMwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMA==",
+        "tileset": [
+            "myTiles.transparency16",
+            "myTiles.tile3",
+            "myTiles.tile4",
+            "myTiles.tile5"
+        ],
+        "displayName": "level1"
+    },
+    "*": {
+        "mimeType": "image/x-mkcd-f4",
+        "dataEncoding": "base64",
+        "namespace": "myTiles"
+    }
+}
+```

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

@@ -8,7 +8,7 @@ tiles.tileAtLocationEquals(tiles.getTileLocation(0, 0), null)
 
 ## Parameters
 
-* **location**: a location in the tilemap.
+* **location**: a [location](/reference/scene/location) in the tilemap.
 * **tile**: an [image](/types/image) that matches the tile you're looking for.
 
 ## Returns

package/libs/game/docs/reference/scene/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/scene/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/scene/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/scene/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/scene/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/scene/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"
+    }
+}
+```