Convert collision.bin to collision.asm for Polished Map 3.4.0

4 files changed, 86 insertions, 0 deletions

diff --git a/Add-a-new-tileset.md b/Add-a-new-tileset.md
index cdddbd4..9237881 100644
--- a/Add-a-new-tileset.md
+++ b/Add-a-new-tileset.md
@@ -178,6 +178,8 @@ The collision system in pokered was very different from pokecrystal, based on ti
 
 You'll have to define the other 112 blocks yourself. ;)
 
+As of version 3.4.0, Polished Map can edit collision data, so you can create an empty data/tilesets/museum_collision.asm file and then enter collision values at the same time as you're designing blocks in the previous step.
+
 
 ## 7. Include the new files in the ROM
 
diff --git a/Convert-old-collision.bin-to-new-collision.asm-files.md b/Convert-old-collision.bin-to-new-collision.asm-files.md
new file mode 100644
index 0000000..170697e
--- /dev/null
+++ b/Convert-old-collision.bin-to-new-collision.asm-files.md
@@ -0,0 +1,80 @@
+Collision data used to be stored in binary **tilesets/\*_collision.bin** files instead of using named constants in [data/tilesets/\*_collision.asm](../tree/master/data/tilesets/) files. These are inconvenient because you need a hex editor instead of a text editor or [Polished Map](https://github.com/Rangi42/polished-map). However, it's possible to quickly convert from the old format to the new one.
+
+
+## Contents
+
+1. [Convert \*_collision.bin to \*_collision.asm](#1-convert-_collisionbin-to-_collisionasm)
+2. [Replace `INCBIN "*_collision.bin"` with `INCLUDE "*_collision.asm"`](#2-replace-incbin-_collisionbin-with-include-_collisionasm)
+3. [Define the `tilecoll` macro](#3-define-the-tilecoll-macro)
+
+
+## 1. Convert \*_collision.bin to \*_collision.asm
+
+Save this as **bin2asm.py** in the same directory as main.asm:
+
+```python
+import glob
+
+collision_bin_names = glob.glob('tilesets/*_collision.bin')
+for collision_bin_name in collision_bin_names:
+
+	collision_asm_name = collision_bin_name.replace('.bin', '.asm')
+	print(collision_bin_name, '=>', collision_asm_name)
+
+	with open(collision_bin_name, 'rb') as bin:
+		data = bin.read()
+
+	with open(collision_asm_name, 'w', encoding='utf8') as asm:
+		blocks = (data[i:i+4] for i in range(0, len(data), 4))
+		for (i, quadrants) in enumerate(blocks):
+			quadrants = ', '.join('$%02x' % q for q in quadrants)
+			line = '\ttilecoll %s ; %02x\n' % (quadrants, i)
+			asm.write(line)
+```
+
+Then run `python3 bin2asm.py`, just like running `make`. It should output:
+
+```
+$ python3 bin2asm.py
+tilesets/00_collision.bin => tilesets/00_collision.asm
+...
+tilesets/36_collision.bin => tilesets/36_collision.asm
+```
+
+(If it gives an error "`python3: command not found`", you need to install Python 3. It's available as the `python3` package in Cygwin.)
+
+Delete the leftover collision.bin files after they're converted.
+
+
+## 2. Replace `INCBIN "*_collision.bin"` with `INCLUDE "*_collision.asm"`
+
+Edit **tilesets/data_\*.asm** (combined in modern pokecrystal as [gfx/tilesets.asm](../blob/master/gfx/tilesets.asm). Replace every instance of `INCBIN "*_collision.bin"` with `INCLUDE "*_collision.asm"`.
+
+
+## 3. Define the `tilecoll` macro
+
+Edit **macros/pals.asm**:
+
+```
+ tilepal: MACRO
+ ; vram bank, pals
+ x = \1 << 3
+ rept (_NARG +- 1) / 2
+ 	dn (x | PAL_BG_\3), (x | PAL_BG_\2)
+ 	shift
+ 	shift
+ endr
+ endm
++
++tilecoll: MACRO
++	db \1, \2, \3, \4
++ENDM
+```
+
+(It doesn't really matter where you define `tilecoll`, but next to `tilepal` makes sense.)
+
+Modern pokecrystal makes `tilecoll` prepend "`COLL_`" to its four parameters, since they're all assumed to be `COLL_*` constants anyway and it makes the individual \*_collision.asm files smaller. But here we're using raw numbers, not named constants, so that isn't necessary.
+
+That's all! Now you can edit the collision.asm files in a plain text editor, or even use Polished Map as of version 3.4.0:
+
+![Screenshot](screenshots/polished-map-edit-collision.png)
diff --git a/Tutorials.md b/Tutorials.md
index 0a587a6..5751d57 100644
--- a/Tutorials.md
+++ b/Tutorials.md
@@ -70,6 +70,10 @@ Tutorials may use diff syntax to show edits:
 - [Dive](Dive)
 - [Puddles that splash when you walk](Puddles-that-splash-when-you-walk)
 
+**Code cleanup and refactoring:**
+
+- [Convert old collision.bin to new collision.asm files](Convert-old-collision.bin-to-new-collision.asm-files)
+
 **To do:** *(feel free to contribute one of these!)*
 
 - Decoration for your room
diff --git a/screenshots/polished-map-edit-collision.png b/screenshots/polished-map-edit-collision.png
new file mode 100644
index 0000000..c1be80f
--- /dev/null
+++ b/screenshots/polished-map-edit-collision.png