path: root/Allow-tiles-to-have-different-attributes-in-different-blocks-(including-X-and-Y-flip).md

**Note:** You should [expand your tilesets](Expand-tilesets-from-192-to-255-tiles) before following this tutorial! (It's required for convenient map editing.) You should *not* [implement `PRIORITY` colors](Allow-map-tiles-to-appear-above-sprites-\(so-NPCs-can-walk-behind-tiles\)-with-PRIORITY-colors). (It's harmless but redundant; this tutorial will undo that work.)

Maps in pokecrystal are designed with blocks, not tiles, where each block (aka "metatile") is a 4x4 square of tiles. Each 8x8-pixel tile always has the same appearance in every block. But the GameBoy hardware is capable of more. The same tile graphic can be reused with different attributes—not just color, but X and Y flip, as well as "priority" to appear above sprites.

For example, here's the `kanto` tileset. The tiles highlighted in fuchsia are just flipped or recolored copies of the ones highlighted in cyan, so by following this tutorial, you can eliminate all those tiles. And with the priority attribute, you can (for instance) let NPCs walk behind the roof tiles highlighted in yellow. (Although if that's all you want to do, just follow [the `PRIORITY` color tutorial](Allow-map-tiles-to-appear-above-sprites-\(so-NPCs-can-walk-behind-tiles\)-with-PRIORITY-colors).)

![Screenshot](screenshots/redundant-tiles-kanto.png)

This tutorial will show you how to switch from per-tile \*_palette_map.asm files to per-block **\*_attributes.bin** files, which assign full attributes (not just colors) to the individual tiles of each block. By the end, you'll be able to make maps like [this](screenshots/redplusplus-goldenrod-city.png).

(The code for this feature was adapted from [Pokémon Red++](https://github.com/TheFakeMateo/RedPlusPlus/).)


## Contents

1. [Review how tilesets and VRAM work](#1-review-how-tilesets-and-vram-work)
2. [Create \*_attributes.bin files from \*_palette_map.asm and \*_metatiles.bin files](#2-create-_attributesbin-files-from-_palette_mapasm-and-_metatilesbin-files)
3. [Remove the old files and include the new ones](#3-remove-the-old-files-and-include-the-new-ones)
4. [Store attribute pointers in tileset metadata](#4-store-attribute-pointers-in-tileset-metadata)
5. [Start changing how tile attributes are loaded](#5-start-changing-how-tile-attributes-are-loaded)
6. [Declare space in WRAM for on-screen tile attributes](#6-declare-space-in-wram-for-on-screen-tile-attributes)
7. [Continue changing how tile attributes are loaded](#7-continue-changing-how-tile-attributes-are-loaded)
8. [Finish changing how tile attributes are loaded](#8-finish-changing-how-tile-attributes-are-loaded)
9. [Rename \*.blk to \*.ablk](#9-rename-blk-to-ablk)
10. [Use more than 256 tiles in a tileset](#10-use-more-than-256-tiles-in-a-tileset)


## 1. Review how tilesets and VRAM work

Here's a quick overview of how tilesets work:

- The [gfx/tilesets/\*.png](../tree/master/gfx/tilesets/) files are the tileset graphics. Each tile is 8x8 pixels, and a tileset can have up to 192 tiles. (Although they can be [expanded to 255](Expand-tilesets-from-192-to-255-tiles).)
- The [gfx/tilesets/\*_palette_map.asm](../tree/master/gfx/tilesets/) files assign a color to each tile. There are eight possible colors, declared at the bottom of [constants/tileset_constants.asm](../blob/master/constants/tileset_constants.asm), although `TEXT` is not useful since it's reserved for textboxes.
- The [data/tilesets/\*_metatiles.bin](../tree/master/data/tilesets/) files define the blocks. Each block has 16 bytes declaring the tiles it's composed of, from top-left to bottom-right.
- The [data/tilesets/\*_collision.asm](../tree/master/data/tilesets/) files assign collisions to the four quadrants of each block where NPCs can walk (or bump, slide, warp, Surf, etc, as the case may be). Valid collision values are declared in [constants/collision_constants.asm](../blob/master/constants/collision_constants.asm).
- The [maps/\*.blk](../tree/master/maps/) files define the maps. Each one has *W*x*H* bytes declaring the blocks it's composed of, from top-left to bottom-right. (The width and height of each map are declared in [constants/map_constants.asm](../blob/master/constants/map_constants.asm).)

(The \*.bin and \*.blk files are binary data, so unlike \*.asm files, a text editor won't work for them. You'll need a hex editor, or a program like [Polished Map](https://github.com/Rangi42/polished-map) that can edit maps and tilesets.)

However, this tileset system doesn't use the full potential of the GBC hardware. Specifically, each tile on the screen has an **attribute** byte (as described in [the `PRIORITY` color tutorial](Allow-map-tiles-to-appear-above-sprites-\(so-NPCs-can-walk-behind-tiles\)-with-PRIORITY-colors)) that controls more than just its color. Here's what the eight bits of an attribute byte mean:

- **Bits 0–2 ($00–$07):** The color. You can see the color values in [constants/tileset_constants.asm](../blob/master/constants/tileset_constants.asm).
- **Bit 3 ($08):** The tile bank. The way pokecrystal's tileset system works, tile IDs $80–$FF need this bit set.
- **Bit 4 ($10):** Unused by the GameBoy Color.
- **Bit 5 ($20):** X flip. Set this bit to flip the tile horizontally.
- **Bit 6 ($40):** Y flip. Set this bit to flip the tile vertically.
- **Bit 7 ($80):** Priority. Set this bit to make the tile appear above any sprites (although white pixels will be transparent).

For example, the attribute byte $A9 = $80 + $20 + $08 + $01. It has the priority bit, X flip bit, and tile bank bit set, and its color is 1 (`RED`).

Let's take a closer look at the tile bank bit. We can understand it better by looking at [BGB](http://bgb.bircd.org/)'s VRAM viewer:

![VRAM](screenshots/255-tiles-vram.png)

VRAM is divided into six areas, each 128 tiles large. The top and middle four can be used by sprites, and the bottom and middle four can be used by background tiles.

At the hardware level, here's how things go:

- Tile IDs $00–$7F with bank 0 use the lower-left area.
- Tile IDs $80–$FF with bank 0 use the middle-left area.
- Tile IDs $00–$7F with bank 1 use the lower-right area.
- Tile IDs $80–$FF with bank 1 use the middle-right area.

But here's how pokecrystal's data works:

- Tile IDs $00–$7F use the lower-left area; the palette map sets their bank to 0.
- Tile IDs $80–$FF use the lower-right area; the palette map sets their bank to 1.
- The middle areas can't be used for map tilesets.


## 2. Create \*_attributes.bin files from \*_palette_map.asm and \*_metatiles.bin files

To start with, let's change the tileset data files to work like the GBC hardware. We'll create **data/tilesets/\*_attributes.bin** files that assign attributes to the blocks, just like how \*_metatiles.bin assign tile IDs. We'll also change the \*_metatiles.bin files to only use IDs from $00 to $7F; any tiles that were using $80 to $FF will instead have their bank bit set to 1 in the corresponding \*_attributes.bin file.

We can generate \*_attributes.bin and modify \*_metatiles.bin by automatically correlating the \*_palette_map.asm and \*_metatiles.bin files. The end result will *not* take advantage of X/Y flip or eliminate redundant tiles; it will just enable you to do that manually.

Save this as **palmap2attr.py** in the same directory as main.asm:

```python
import glob

color_attrs = {
	'GRAY': 0, 'RED': 1, 'GREEN': 2, 'WATER': 3,
	'YELLOW': 4, 'BROWN': 5, 'ROOF': 6, 'TEXT': 7,
	'PRIORITY_GRAY': 0x80, 'PRIORITY_RED': 0x81,
	'PRIORITY_GREEN': 0x82, 'PRIORITY_WATER': 0x83,
	'PRIORITY_YELLOW': 0x84, 'PRIORITY_BROWN': 0x85,
	'PRIORITY_ROOF': 0x86, 'PRIORITY_TEXT': 0x87,
}

palette_map_names = glob.glob('gfx/tilesets/*_palette_map.asm')
for palette_map_name in palette_map_names:

	if 'unused_museum_palette_map' in palette_map_name:
		continue

	palette_map_name = palette_map_name.replace('\\', '/')
	metatiles_name = (palette_map_name.replace('gfx/', 'data/')
		.replace('_palette_map.asm', '_metatiles.bin'))
	attributes_name = metatiles_name.replace('_metatiles', '_attributes')

	print('Convert', palette_map_name.split('/')[-1], '...')

	tile_colors = {}

	with open(palette_map_name, 'r', encoding='utf8') as palette_map:
		reached_vram1 = False
		tile_index = 0
		for line in palette_map:
			if not line.startswith('\ttilepal'):
				continue
			line = line[len('\ttilepal '):]
			colors = (c.strip() for c in line.split(','))
			bank = next(colors)
			if not reached_vram1 and bank == '1':
				reached_vram1 = True
				tile_index = 0x80
			for color in colors:
				tile_attr = color_attrs.get(color, 0)
				tile_attr |= (tile_index >= 0x80) << 3
				tile_colors[tile_index] = tile_attr
				tile_index += 1

	print('... to', attributes_name.split('/')[-1], '...')

	metatile_bytes = b''
	with open(metatiles_name, 'rb') as metatiles:
		with open(attributes_name, 'wb') as attributes:
			for block_tiles in iter(lambda: metatiles.read(16), b''):
				block_attrs = (tile_colors.get(t, (t >= 0x80) << 3)
					for t in block_tiles)
				attributes.write(bytes(block_attrs))
				metatile_bytes += block_tiles

	print('... and modify', metatiles_name.split('/')[-1], '!')

	with open(metatiles_name, 'wb') as metatiles:
		metatiles.write(bytes(t & 0x7f for t in metatile_bytes))
```

Then run `python3 palmap2attr.py`, just like running `make`. It should output:

```
$ python3 palmap2attr.py
Convert aerodactyl_word_room_palette_map.asm ...
... to aerodactyl_word_room_attributes.bin ...
... and modify aerodactyl_word_room_metatiles.bin !
...
Convert underground_palette_map.asm ...
... to underground_attributes.bin ...
... and modify underground_metatiles.bin !
```

(If it gives an error "`python3: command not found`", you need to install Python 3. It's available as the `python3` package in Cygwin.)

If you followed [the `PRIORITY` color tutorial](Allow-map-tiles-to-appear-above-sprites-\(so-NPCs-can-walk-behind-tiles\)-with-PRIORITY-colors) before this one, that's okay; palmap2attr.py supports `PRIORITY` colors too. If you haven't followed it, that's even better, because it's totally redundant with this one. :P


## 3. Remove the old files and include the new ones

Now that all the \*_attributes.bin files are created, delete all the \*_palette_map.asm files. Also delete [gfx/tileset_palette_maps.asm](../blob/master/gfx/tileset_palette_maps.asm).

Edit [gfx/tilesets.asm](../blob/master/gfx/tilesets.asm):

```diff
 ...

 SECTION "Tileset Data 8", ROMX

 TilesetHoOhWordRoomMeta:
 INCBIN "data/tilesets/ho_oh_word_room_metatiles.bin"

 TilesetKabutoWordRoomMeta:
 INCBIN "data/tilesets/kabuto_word_room_metatiles.bin"

 TilesetOmanyteWordRoomMeta:
 INCBIN "data/tilesets/omanyte_word_room_metatiles.bin"

 TilesetAerodactylWordRoomMeta:
 INCBIN "data/tilesets/aerodactyl_word_room_metatiles.bin"
+
+
+SECTION "Tileset Data 9", ROMX
+
+Tileset0Attr:
+TilesetJohtoAttr:
+INCBIN "data/tilesets/johto_attributes.bin"
+
+TilesetJohtoModernAttr:
+INCBIN "data/tilesets/johto_modern_attributes.bin"
+
+TilesetKantoAttr:
+INCBIN "data/tilesets/kanto_attributes.bin"
+
+TilesetBattleTowerOutsideAttr:
+INCBIN "data/tilesets/battle_tower_outside_attributes.bin"
+
+TilesetHouseAttr:
+INCBIN "data/tilesets/house_attributes.bin"
+
+TilesetPlayersHouseAttr:
+INCBIN "data/tilesets/players_house_attributes.bin"
+
+TilesetPokecenterAttr:
+INCBIN "data/tilesets/pokecenter_attributes.bin"
+
+TilesetGateAttr:
+INCBIN "data/tilesets/gate_attributes.bin"
+
+TilesetPortAttr:
+INCBIN "data/tilesets/port_attributes.bin"
+
+TilesetLabAttr:
+INCBIN "data/tilesets/lab_attributes.bin"
+
+
+SECTION "Tileset Data 10", ROMX
+
+TilesetFacilityAttr:
+INCBIN "data/tilesets/facility_attributes.bin"
+
+TilesetMartAttr:
+INCBIN "data/tilesets/mart_attributes.bin"
+
+TilesetMansionAttr:
+INCBIN "data/tilesets/mansion_attributes.bin"
+
+TilesetGameCornerAttr:
+INCBIN "data/tilesets/game_corner_attributes.bin"
+
+TilesetEliteFourRoomAttr:
+INCBIN "data/tilesets/elite_four_room_attributes.bin"
+
+TilesetTraditionalHouseAttr:
+INCBIN "data/tilesets/traditional_house_attributes.bin"
+
+TilesetTrainStationAttr:
+INCBIN "data/tilesets/train_station_attributes.bin"
+
+TilesetChampionsRoomAttr:
+INCBIN "data/tilesets/champions_room_attributes.bin"
+
+TilesetLighthouseAttr:
+INCBIN "data/tilesets/lighthouse_attributes.bin"
+
+TilesetPlayersRoomAttr:
+INCBIN "data/tilesets/players_room_attributes.bin"
+
+TilesetPokeComCenterAttr:
+INCBIN "data/tilesets/pokecom_center_attributes.bin"
+
+TilesetBattleTowerAttr:
+INCBIN "data/tilesets/battle_tower_attributes.bin"
+
+TilesetTowerAttr:
+INCBIN "data/tilesets/tower_attributes.bin"
+
+
+SECTION "Tileset Data 11", ROMX
+
+TilesetCaveAttr:
+TilesetDarkCaveAttr:
+INCBIN "data/tilesets/cave_attributes.bin"
+
+TilesetParkAttr:
+INCBIN "data/tilesets/park_attributes.bin"
+
+TilesetRuinsOfAlphAttr:
+INCBIN "data/tilesets/ruins_of_alph_attributes.bin"
+
+TilesetRadioTowerAttr:
+INCBIN "data/tilesets/radio_tower_attributes.bin"
+
+TilesetUndergroundAttr:
+INCBIN "data/tilesets/underground_attributes.bin"
+
+TilesetIcePathAttr:
+INCBIN "data/tilesets/ice_path_attributes.bin"
+
+TilesetForestAttr:
+INCBIN "data/tilesets/forest_attributes.bin"
+
+TilesetBetaWordRoomAttr:
+INCBIN "data/tilesets/beta_word_room_attributes.bin"
+
+TilesetHoOhWordRoomAttr:
+INCBIN "data/tilesets/ho_oh_word_room_attributes.bin"
+
+TilesetKabutoWordRoomAttr:
+INCBIN "data/tilesets/kabuto_word_room_attributes.bin"
+
+TilesetOmanyteWordRoomAttr:
+INCBIN "data/tilesets/omanyte_word_room_attributes.bin"
+
+TilesetAerodactylWordRoomAttr:
+INCBIN "data/tilesets/aerodactyl_word_room_attributes.bin"
```

All we're doing here is `INCBIN`-ing each of the \*_attributes.bin files with an appropriate label. Of course, if you've added or removed any tilesets, they'll need their own labels and `INCBIN` statements. It doesn't matter which section any of them go in, or whether you create new sections.

Also, notice that cave_attributes.bin is being used for the `cave` *and* `dark_cave` tilesets. That's because they already shared cave_metatiles.bin and cave_collision.asm. The only reason dark_cave_metatiles.bin and dark_cave_collision.asm exist is so programs like Polished Map can easily render tilesets and maps.


## 4. Store attribute pointers in tileset metadata

Edit [data/tilesets.asm](../blob/master/data/tilesets.asm):

```diff
tileset: MACRO
-	dba \1GFX, \1Meta, \1Coll
+	dba \1GFX, \1Meta, \1Coll, \1Attr
	dw \1Anim
-	dw NULL
-	dw \1PalMap
ENDM
```

And edit [wram.asm](../blob/master/wram.asm):

```diff
 wTileset::
 wTilesetBank:: db ; d1d9
 wTilesetAddress:: dw ; d1da
 wTilesetBlocksBank:: db ; d1dc
 wTilesetBlocksAddress:: dw ; d1dd
 wTilesetCollisionBank:: db ; d1df
 wTilesetCollisionAddress:: dw ; d1e0
+wTilesetAttributesBank:: db
+wTilesetAttributesAddress:: dw
 wTilesetAnim:: dw ; bank 3f ; d1e2
-	ds 2 ; unused ; d1e4
-wTilesetPalettes:: dw ; bank 3f ; d1e6
 wTilesetEnd::
```

Now each tileset will be associated with the correct attribute data.


## 5. Start changing how tile attributes are loaded

We just removed the `wTilesetPalettes` pointer and the \*_palette_map.asm data it pointed to, so it's time to see how they were being used and update that code to use the \*_attributes.bin files instead.

It turns out that `wTilesetPalettes` is only used in [engine/tilesets/map_palettes.asm](../blob/master/engine/tilesets/map_palettes.asm), which defines two routines: `SwapTextboxPalettes` and `ScrollBGMapPalettes`. `SwapTextboxPalettes` is only called by `FarCallSwapTextboxPalettes`, and `ScrollBGMapPalettes` is only called by `FarCallScrollBGMapPalettes`, both in [home/palettes.asm](../blob/master/home/palettes.asm). Furthermore, `FarCallSwapTextboxPalettes` and `FarCallScrollBGMapPalettes` are only called in [home/map.asm](../blob/master/home/map.asm).

First, delete [engine/tilesets/map_palettes.asm](../blob/master/engine/tilesets/map_palettes.asm).

Edit [main.asm](../blob/master/main.asm):

```diff
 SECTION "bank13", ROMX

-INCLUDE "engine/tilesets/map_palettes.asm"
-INCLUDE "gfx/tileset_palette_maps.asm"
```

Edit [home/palettes.asm](../blob/master/home/palettes.asm):

```diff
-FarCallSwapTextboxPalettes::
-	homecall SwapTextboxPalettes
-	ret
-
-FarCallScrollBGMapPalettes::
-	homecall ScrollBGMapPalettes
-	ret
```

Finally, we need to edit [home/map.asm](../blob/master/home/map.asm); but it's pretty long, and we need to do something else first.


## 6. Declare space in WRAM for on-screen tile attributes

Edit [wram.asm](../blob/master/wram.asm) again:

```diff
 ; This union spans 480 bytes from c608 to c7e8.
 UNION ; c608
-; surrounding tiles
-; This buffer determines the size for the rest of the union;
-; it uses exactly 480 bytes.
-wSurroundingTiles:: ds SURROUNDING_WIDTH * SURROUNDING_HEIGHT
-
-NEXTU ; c608
 ; box save buffer
 ; SaveBoxAddress uses this buffer in three steps because it
 ; needs more space than the buffer can hold.
 wBoxPartialData:: ds 480
 wBoxPartialDataEnd::
```

```diff
-	ds 3
+wTilesetDataAddress:: dw

 wLinkBattleRNs:: ds 10 ; d1fa

 ...
```

```diff
+SECTION "Surrounding Data", WRAMX
+
+wSurroundingTiles:: ds SURROUNDING_WIDTH * SURROUNDING_HEIGHT
+
+wSurroundingAttributes:: ds SURROUNDING_WIDTH * SURROUNDING_HEIGHT
+
+
 SECTION "GBC Video", WRAMX

 ...
```

And edit [pokecrystal.link](../blob/master/pokecrystal.link):

```diff
+WRAMX 4
+	"Surrounding Data"
 WRAMX 5
 	"GBC Video"
 	...
```

As we'll see next, `wSurroundingTiles` stores the tile IDs of all the blocks surrounding the player on-screen. (It gets updated when the player moves, of course.) The screen is 20x18 tiles, so 6x5 blocks are needed to cover it; each block has 4x4 tiles, so that's 480 bytes of tile data. Now that each of those tiles can have its own attributes, we need to introduce `wSurroundingAttributes` to play a similar role for attribute data. However, there's not enough free space in WRAM0 for both `wSurroundingTiles` and `wSurroundingAttributes`, so we have to put `wSurroundingAttributes` in a different bank, and for convenience we move `wSurroundingTiles` to the same bank. WRAMX 4 happens to be unused, so that's where they go.

(We also introduce `wTilesetDataAddress`, which will store either `wTilesetBlocksAddress` when writing to `wSurroundingTiles`, or `wTilesetAttributesAddress` when writing to `wSurroundingAttributes`.)


## 7. Continue changing how tile attributes are loaded

Now we can edit [home/map.asm](../blob/master/home/map.asm). Let's go over it piece by piece.

```diff
OverworldTextModeSwitch::
-	call LoadMapPart
-	call FarCallSwapTextboxPalettes
-	ret
+	; fallthrough

 LoadMapPart::
 	ldh a, [hROMBank]
 	push af

 	ld a, [wTilesetBlocksBank]
 	rst Bankswitch
 	call LoadMetatiles

 	ld a, "■"
 	hlcoord 0, 0
 	ld bc, SCREEN_WIDTH * SCREEN_HEIGHT
 	call ByteFill
+
+	ld a, [wTilesetAttributesBank]
+	rst Bankswitch
+	call LoadMetatileAttributes

 	ld a, BANK(_LoadMapPart)
 	rst Bankswitch
 	call _LoadMapPart

 	pop af
 	rst Bankswitch
 	ret
```

We deleted `FarCallSwapTextboxPalettes`, so now `OverworldTextModeSwitch` just calls `LoadMapPart`; but since the latter is right after the former, they can just be two labels for the same routine.

Anyway, `LoadMapPart` calls `LoadMetatiles` to load certain data from the \*_metatiles.bin files, and we're going to define a `LoadMetatileAttributes` routine that does the same thing with the \*_attributes.bin files, so this is where it will be called.

```diff
 LoadMetatiles::
+	ld hl, wSurroundingTiles
+	ld de, wTilesetBlocksAddress
+	jr _LoadMetatilesOrAttributes
+
+LoadMetatileAttributes::
+	ld hl, wSurroundingAttributes
+	ld de, wTilesetAttributesAddress
+	; fallthrough
+
+_LoadMetatilesOrAttributes:
+	ld a, [de]
+	ld [wTilesetDataAddress], a
+	inc de
+	ld a, [de]
+	ld [wTilesetDataAddress + 1], a
+
 	; de <- wOverworldMapAnchor
 	ld a, [wOverworldMapAnchor]
 	ld e, a
 	ld a, [wOverworldMapAnchor + 1]
 	ld d, a
-	ld hl, wSurroundingTiles
 	ld b, SURROUNDING_HEIGHT / METATILE_WIDTH ; 5

 .row
 	push de
 	push hl
 	ld c, SURROUNDING_WIDTH / METATILE_WIDTH ; 6

 .col
 	push de
 	push hl
 	; Load the current map block.
 	; If the current map block is a border block, load the border block.
 	ld a, [de]
 	and a
 	jr nz, .ok
 	ld a, [wMapBorderBlock]

 .ok
 	; Load the current wSurroundingTiles address into de.
 	ld e, l
 	ld d, h
 	; Set hl to the address of the current metatile data ([wTilesetBlocksAddress] + (a) tiles).
-	; This is buggy; it wraps around past 128 blocks.
-	; To fix, uncomment the line below.
-	add a ; Comment or delete this line to fix the above bug.
 	ld l, a
 	ld h, 0
-	; add hl, hl
+	add hl, hl
 	add hl, hl
 	add hl, hl
 	add hl, hl
-	ld a, [wTilesetBlocksAddress]
+	ld a, [wTilesetDataAddress]
 	add l
 	ld l, a
-	ld a, [wTilesetBlocksAddress + 1]
+	ld a, [wTilesetDataAddress + 1]
 	adc h
 	ld h, a
+
+	ldh a, [rSVBK]
+	push af
+	ld a, BANK("Surrounding Data")
+	ldh [rSVBK], a

 	; copy the 4x4 metatile
 rept METATILE_WIDTH + -1
 rept METATILE_WIDTH
 	ld a, [hli]
 	ld [de], a
 	inc de
 endr
 	ld a, e
 	add SURROUNDING_WIDTH - METATILE_WIDTH
 	ld e, a
 	jr nc, .next\@
 	inc d
 .next\@
 endr
 rept METATILE_WIDTH
 	ld a, [hli]
 	ld [de], a
 	inc de
 endr
+
+	pop af
+	ldh [rSVBK], a
+
 	; Next metatile
 	pop hl
 	ld de, METATILE_WIDTH
 	add hl, de
 	pop de
 	inc de
 	dec c
 	jp nz, .col
 	; Next metarow
 	pop hl
 	ld de, SURROUNDING_WIDTH * METATILE_WIDTH
 	add hl, de
 	pop de
 	ld a, [wMapWidth]
 	add 6
 	add e
 	ld e, a
 	jr nc, .ok2
 	inc d
 .ok2
 	dec b
 	jp nz, .row
 	ret
```

The `LoadMetatiles` routine copies data from \*_metatiles.bin (pointed to by `[wTilesetBlocksAddress]`) into `wSurroundingTiles`. We've reused most of its code for `LoadMetatileAttributes`, which copies data from \*_attributes.bin (pointed to by `[wTilesetAttributesAddress]`) into `wSurroundingAttributes`. Since `wSurroundingTiles` and `wSurroundingAttributes` are not in WRAM0, we have to switch banks at one point.

We also fixed [the bug that only allowed 128 blocks](../blob/master/docs/bugs_and_glitches.md#loadmetatiles-wraps-around-past-128-blocks), since you'll probably need 256 to take full advantage of this block attribute system.

```diff
 ScrollMapDown::
 	hlcoord 0, 0
 	ld de, wBGMapBuffer
 	call BackupBGMapRow
-	ld c, 2 * SCREEN_WIDTH
-	call FarCallScrollBGMapPalettes
+	hlcoord 0, 0, wAttrMap
+	ld de, wBGMapPalBuffer
+	call BackupBGMapRow
 	...

 ScrollMapUp::
 	hlcoord 0, SCREEN_HEIGHT - 2
 	ld de, wBGMapBuffer
 	call BackupBGMapRow
-	ld c, 2 * SCREEN_WIDTH
-	call FarCallScrollBGMapPalettes
+	hlcoord 0, SCREEN_HEIGHT - 2, wAttrMap
+	ld de, wBGMapPalBuffer
+	call BackupBGMapRow
 	...

 ScrollMapRight::
 	hlcoord 0, 0
 	ld de, wBGMapBuffer
 	call BackupBGMapColumn
-	ld c, 2 * SCREEN_HEIGHT
-	call FarCallScrollBGMapPalettes
+	hlcoord 0, 0, wAttrMap
+	ld de, wBGMapPalBuffer
+	call BackupBGMapColumn
 	...

 ScrollMapLeft::
 	hlcoord SCREEN_WIDTH - 2, 0
 	ld de, wBGMapBuffer
 	call BackupBGMapColumn
-	ld c, 2 * SCREEN_HEIGHT
-	call FarCallScrollBGMapPalettes
+	hlcoord SCREEN_WIDTH - 2, 0, wAttrMap
+	ld de, wBGMapPalBuffer
+	call BackupBGMapColumn
 	...
```

`FarCallScrollBGMapPalettes` used to update `wBGMapPalBuffer` when the screen was scrolled. We deleted it, so now have to update it the same way as `wBGMapBuffer`.


## 8. Finish changing how tile attributes are loaded

One more thing: edit [engine/overworld/load_map_part.asm](../blob/master/engine/overworld/load_map_part.asm):

```diff
 _LoadMapPart::
 	ld hl, wSurroundingTiles
+	decoord 0, 0
+	call .copy
+	ld hl, wSurroundingAttributes
+	decoord 0, 0, wAttrMap
+.copy:
 	ld a, [wMetatileStandingY]
 	and a
 	jr z, .top_row
 	ld bc, SURROUNDING_WIDTH * 2
 	add hl, bc

 .top_row
 	ld a, [wMetatileStandingX]
 	and a
 	jr z, .left_column
 	inc hl
 	inc hl

 .left_column
-	decoord 0, 0
+	ldh a, [rSVBK]
+	push af
+	ld a, BANK("Surrounding Data")
+	ldh [rSVBK], a
 	ld b, SCREEN_HEIGHT
 .loop
 	ld c, SCREEN_WIDTH
 .loop2
 	ld a, [hli]
 	ld [de], a
 	inc de
 	dec c
 	jr nz, .loop2
 	ld a, l
 	add METATILE_WIDTH
 	ld l, a
 	jr nc, .carry
 	inc h

 .carry
 	dec b
 	jr nz, .loop
+	pop af
+	ldh [rSVBK], a
 	ret
```

The `_LoadMapPart` routine initializes `wSurroundingTiles` with the relevant area of map data. Here we've updated it to also initialize `wSurroundingAttributes`, and switch to the new WRAM bank that both of them are in.


## 9. Rename \*.blk to \*.ablk

We're almost done, but when we try to open a .blk file in Polished Map, it complains that the palette_map.asm file is missing. It can't read the new attributes.bin files. Until 2019, that would have forced us to design maps and tilesets in a hex editor, like savages. But now there's [Polished Map++](https://github.com/Rangi42/polished-map/tree/plusplus), a fork of Polished Map designed for these new files. There's just one thing left to change in our project for more convenient editing.

Edit [data/maps/blocks.asm](../blob/master/data/maps/blocks.asm), replacing each occurrence of ".blk" with ".ablk".

Then run this command in the terminal:

```bash
for f in maps/*.blk maps/**/*.blk; do git mv $f ${f%.blk}.ablk; done
```

It will rename every \*.blk file to \*.ablk. (If you're not using Git, then just use `mv` instead of `git mv`.)

This has no effect on the ROM itself; it's just so that we can have a clean separation of .blk files associated with Polished Map, and .ablk associated with Polished Map++.

*Now* we're done! `make` works, and all the maps look the same as before—but now they're capable of looking very different.

The pokecrystal map engine didn't support flipped, recolored, or priority tiles, so of course the tileset graphics were not designed to take advantage of those features. But now you can. And all of those engine features *did* exist in Gen 3, so if you're devamping tiles from R/S/E or FR/LG, they'll benefit from this change.

Case in point: here's Goldenrod City from [Red++ 4](https://github.com/TheFakeMateo/RedPlusPlus/):

[![Screenshot](screenshots/redplusplus-goldenrod-city.png)](screenshots/redplusplus-goldenrod-city.png)

The same tiles can appear in different colors, like lit `YELLOW` and unlit `BROWN` windows using a single tile, or multicolored roofs. Trees are horizontally symmetrical, as are some roofs and walls, so they only needed half as many tiles. Vertical symmetry is also useful, like for the pattern on the Dept. Store's roof. And with the priority attribute, NPCs can walk behind things like treetops or some rooftops. (That doesn't work for every roof, since some have white highlights that would be transparent, but it works for the Pokémon Center roof.) All the tiles that saved, plus [expanding tilesets from 192 to 255 tiles](Expand-tilesets-from-192-to-255-tiles), allowed a wide variety of unique buildings and decorations. This is the entire tileset:

![Screenshot](screenshots/redplusplus-goldenrod-tileset.png)

(Notice that tile $7F is still the space character, but is also used as a solid white tile in maps. The [tileset expansion tutorial](Expand-tilesets-from-192-to-255-tiles) emphasizes that you shouldn't use tile $7F in maps because it will always be `TEXT`-colored, but with this block attribute system, that's no longer the case. So you don't need an extra white tile just for mapping.)

And here's how that map looks in Polished Map++:

[![Screenshot](screenshots/polished-map-plusplus-goldenrod-city.png)](screenshots/polished-map-plusplus-goldenrod-city.png)

Now when you edit blocks, you can assign attributes to their individual tiles:

[![Screenshot](screenshots/polished-map-plusplus-edit-block.png)](screenshots/polished-map-plusplus-edit-block.png)

And the tileset itself is a colorless image:

[![Screenshot](screenshots/polished-map-plusplus-edit-tile.png)](screenshots/polished-map-plusplus-edit-tile.png)

Note that Polished Map++ assumes you have also [expanded the tilesets to 255 tiles](Expand-tilesets-from-192-to-255-tiles). If you don't apply that tutorial, your maps will look incorrect.


## 10. Use more than 256 tiles in a tileset

If you were paying attention during the review of how VRAM works, you'll have noticed that technically a map can use 512 different tiles. The tile ID goes from 0 to 255, and the bank bit is 0 or 1; 256 × 2 = 512. But even Polished Map++ can only load 256 tile graphics at once. So how can we go beyond this?

That's what the "★" checkbox in the block editor is for. It basically lets you use the tiles in the "middle" two areas of VRAM instead of the "bottom" two areas. Polished Map++ can't show the actual graphics in those middle areas—unless you modify how pokecrystal works, they'll just contain font tiles and NPC sprites anyway—but it draws a cyan border around a tile to indicate that it's special.

Keep in mind that pokecrystal and Polished Map++ show tile IDs that aren't quite the same as the internal hardware. They all agree about tile IDs $00 to $7F, which are in VRAM bank 0, but the tiles that Polished Map++ calls $80 to $FF are actually encoded as $00 to $7F in bank 1.

For example, here's a block that uses tiles $0F, $0A, $0C, and $0D with the "★" attribute:

![Screenshot](screenshots/polished-map-plusplus-extra-tiles.png)

Those are actually tiles $8F, $8A, $8C, and $8D in bank 0. And those values in [charmap.asm](../blob/master/charmap.asm) correspond to the letters "P", "K", "M", and "N". Which is exactly what we see in the game:

![Screenshot](screenshots/extra-tiles.png)

There are plenty of ways to take advantage of some of that VRAM real estate for maps, instead of text and sprites. But that's beyond the scope of this tutorial. ;)