Great question! I've never written a tutorial about these, so it's understandable that it might be unclear.
A TileDisplay is one of the seven display types you can set any display layer to in Mini Micro. This type of display divides the screen (or even a larger area than the screen) into little rectangular regions called tiles or cells. Each cell displays one portion of a source image called a tile set. So, for example, in the platformer demo...
every little square you see there (except the player character — that's a sprite) is a cell in a TileDisplay. Those cells are drawn from /sys/pics/SimplePlatformTiles.png, which looks like this:
Every 64x64 section of this tile set picture is an image that can be displayed at any cell of a TileDisplay. Look again at the platform demo above, and you should be able to find every tile you see somewhere in this tile set.
TileDisplays require a little more set-up than other kinds of displays, because you need to configure both the display itself, and the tile set you're drawing from. So let's walk through an example. (Fire up Mini Micro and follow along!)
display(5).mode = displayMode.tile
tiles = display(5)
tiles.clear
This starts the process of configuring display 5 as a tile display, but we're not done...
tiles.tileSet = file.loadImage("/sys/pics/SimplePlatformTiles.png")
tiles.tileSetTileSize = 64
This tells the tile display that it's going to be drawing tiles from the SImplePlatformTiles image, and that the tiles in that image are 64x64. (If the source tiles were not square, you could assign tileSetTileSize like [40,32] to indicate the tile width and height.)
Now we need to configure how those tiles should be displayed on screen.
tiles.cellSize = 32
tiles.extent = [100,30]
Here we're defining that on screen, each tile should appear as a 32x32 pixel square. Notice that the cell size doesn't have to match the size of the source tiles; you can make them bigger or smaller, or even stretch them if you want (again, use something like [64,32] if you want non-square tiles on screen). The assignment to extent answers the question, How big is this tile display? How many rows and columns of cells are there? In this example we defined 100 columns, and 30 rows.
Check the docs for other properties you can assign on a TileDisplay, in order to make the cells overlap a bit, or offset every row or column in order to create a hexagonal layout. But for a simple square layout like the platform demo, this is all you need.
Now we're ready to start displaying tiles! So far you don't see anything on screen because the tile display is clear; every cell is set to null. To display something, you just need to set the tile index of a cell:
tiles.setCell 0, 0, 12
This should cause a tile to appear in the lower-left corner of the screen.
Which tile is that? It's tile index 12, which is the one you find in the tile set if you start counting tiles at the top-left, starting at 0. This tile set happens to have 12 tiles per row, so the first row is numbered 0 through 11, the second row is 12 through 23, etc. The .setCell method takes the cell column, row, and tile index, so the line above sets cell 0,0 to tile 12, which is the stone-with-grass image in our tile set.
And that's really all there is to know about TileDisplay! Here's one more example to try:
for col in range(5, 20)
for row in range(0, 3)
tiles.setCell col, row, 4
end for
end for
This fills a whole section of the tile display with dirt.
A couple final notes. When you want to know what any tile in the display is set to, just use the .cell(col,row) method to find out. And if you need to tint any cell (maybe to show damage, or do lighting effects, or whatever), you can to that with .setCellTint. Finally, like both PixelDisplay and SpriteDisplay, you can scroll a TileDisplay by assigning to .scrollX and .scrollY.
Feel free to respond with more questions if you have them!
