Build the Virtual Console patch with make crystal11_vc (#882)

Fixes #813

.gitattributes

@@ -28,6 +28,9 @@
 *.attrmap binary diff=hex
 *.tilemap binary diff=hex
 
+# Declare files that will always have CRLF line endings on checkout.
+*.patch.template text eol=crlf linguist-language=INI
+
 # these are generated but just in case
 *.lz binary   diff=hex
 *.2bpp binary diff=hex

.gitignore

@@ -17,6 +17,7 @@ gfx/pokemon/*/frames.asm
 # compiled roms
 *.gbc
 *.gb
+*.patch
 
 # rgbds extras
 *.map

Makefile

@@ -1,4 +1,9 @@
-roms := pokecrystal.gbc pokecrystal11.gbc pokecrystal_au.gbc pokecrystal_debug.gbc pokecrystal11_debug.gbc
+roms    := pokecrystal.gbc \
+           pokecrystal11.gbc \
+           pokecrystal_au.gbc \
+           pokecrystal_debug.gbc \
+           pokecrystal11_debug.gbc
+patches := pokecrystal11.patch
 
 rom_obj := \
 audio.o \
@@ -23,6 +28,7 @@ pokecrystal11_obj       := $(rom_obj:.o=11.o)
 pokecrystal_au_obj      := $(rom_obj:.o=_au.o)
 pokecrystal_debug_obj   := $(rom_obj:.o=_debug.o)
 pokecrystal11_debug_obj := $(rom_obj:.o=11_debug.o)
+pokecrystal11_vc_obj    := $(rom_obj:.o=11_vc.o)
 
 
 ### Build tools
@@ -54,16 +60,42 @@ crystal11:       pokecrystal11.gbc
 crystal_au:      pokecrystal_au.gbc
 crystal_debug:   pokecrystal_debug.gbc
 crystal11_debug: pokecrystal11_debug.gbc
+crystal11_vc:    pokecrystal11.patch
 
 clean: tidy
-	find gfx \( -name "*.[12]bpp" -o -name "*.lz" -o -name "*.gbcpal" -o -name "*.sgb.tilemap" \) -delete
-	find gfx/pokemon -mindepth 1 ! -path "gfx/pokemon/unown/*" \( -name "bitmask.asm" -o -name "frames.asm" -o -name "front.animated.tilemap" -o -name "front.dimensions" \) -delete
+	find gfx \
+	     \( -name "*.[12]bpp" \
+	        -o -name "*.lz" \
+	        -o -name "*.gbcpal" \
+	        -o -name "*.sgb.tilemap" \) \
+	     -delete
+	find gfx/pokemon -mindepth 1 \
+	     ! -path "gfx/pokemon/unown/*" \
+	     \( -name "bitmask.asm" \
+	        -o -name "frames.asm" \
+	        -o -name "front.animated.tilemap" \
+	        -o -name "front.dimensions" \) \
+	     -delete
 
 tidy:
-	$(RM) $(roms) $(pokecrystal_obj) $(pokecrystal11_obj) $(pokecrystal_au_obj) $(pokecrystal_debug_obj) $(pokecrystal11_debug_obj) $(roms:.gbc=.map) $(roms:.gbc=.sym) rgbdscheck.o
+	$(RM) $(roms) \
+	      $(roms:.gbc=.sym) \
+	      $(roms:.gbc=.map) \
+	      $(patches) \
+	      $(patches:.patch=_vc.gbc) \
+	      $(patches:.patch=_vc.sym) \
+	      $(patches:.patch=_vc.map) \
+	      $(patches:%.patch=vc/%.constants.sym) \
+	      $(pokecrystal_obj) \
+	      $(pokecrystal11_obj) \
+	      $(pokecrystal11_vc_obj) \
+	      $(pokecrystal_au_obj) \
+	      $(pokecrystal_debug_obj) \
+	      $(pokecrystal11_debug_obj) \
+	      rgbdscheck.o
 	$(MAKE) clean -C tools/
 
-compare: $(roms)
+compare: $(roms) $(patches)
 	@$(SHA1) -c roms.sha1
 
 tools:
@@ -81,6 +113,12 @@ $(pokecrystal11_obj):       RGBASMFLAGS += -D _CRYSTAL11
 $(pokecrystal_au_obj):      RGBASMFLAGS += -D _CRYSTAL11 -D _CRYSTAL_AU
 $(pokecrystal_debug_obj):   RGBASMFLAGS += -D _DEBUG
 $(pokecrystal11_debug_obj): RGBASMFLAGS += -D _CRYSTAL11 -D _DEBUG
+$(pokecrystal11_vc_obj):    RGBASMFLAGS += -D _CRYSTAL11 -D _CRYSTAL11_VC
+
+%.patch: %_vc.sym vc/%.constants.sym %_vc.gbc %.gbc vc/%.patch.template
+	tools/make_patch $^ $@
+
+%.sym: ;
 
 rgbdscheck.o: rgbdscheck.asm
 	$(RGBASM) -o $@ $<
@@ -105,6 +143,11 @@ $(foreach obj, $(pokecrystal11_obj), $(eval $(call DEP,$(obj),$(obj:11.o=.asm)))
 $(foreach obj, $(pokecrystal_au_obj), $(eval $(call DEP,$(obj),$(obj:_au.o=.asm))))
 $(foreach obj, $(pokecrystal_debug_obj), $(eval $(call DEP,$(obj),$(obj:_debug.o=.asm))))
 $(foreach obj, $(pokecrystal11_debug_obj), $(eval $(call DEP,$(obj),$(obj:11_debug.o=.asm))))
+$(foreach obj, $(pokecrystal11_vc_obj), $(eval $(call DEP,$(obj),$(obj:11_vc.o=.asm))))
+
+# Dependencies for VC files that need to run scan_includes
+%.constants.sym: %.constants.asm $(shell tools/scan_includes %.constants.asm) | rgbdscheck.o
+	$(RGBASM) $< > $@
 
 endif
 
@@ -114,10 +157,12 @@ pokecrystal11_opt       = -Cjv -t PM_CRYSTAL -i BYTE -n 1 -k 01 -l 0x33 -m 0x10
 pokecrystal_au_opt      = -Cjv -t PM_CRYSTAL -i BYTU -n 0 -k 01 -l 0x33 -m 0x10 -r 3 -p 0
 pokecrystal_debug_opt   = -Cjv -t PM_CRYSTAL -i BYTE -n 0 -k 01 -l 0x33 -m 0x10 -r 3 -p 0
 pokecrystal11_debug_opt = -Cjv -t PM_CRYSTAL -i BYTE -n 1 -k 01 -l 0x33 -m 0x10 -r 3 -p 0
+pokecrystal11_vc_opt    = -Cjv -t PM_CRYSTAL -i BYTE -n 1 -k 01 -l 0x33 -m 0x10 -r 3 -p 0
 
 pokecrystal_base         = us
 pokecrystal11_base       = us
 pokecrystal_au_base      = us
+pokecrystal11_vc_base    = us
 pokecrystal_debug_base   = dbg
 pokecrystal11_debug_base = dbg
 

README.md

@@ -9,6 +9,7 @@ It builds the following ROMs:
 - Pokemon - Crystal Version (A) [C][!].gbc `sha1: a0fc810f1d4e124434f7be2c989ab5b5892ddf36`
 - CRYSTAL_ps3_010328d.bin `sha1: c60d57a24bbe8ecf7cba54ab3f90669f97bd330d`
 - CRYSTAL_ps3_us_revise_010710d.bin `sha1: 391ae86b1d5a26db712ffe6c28bbf2a1f804c3c4`
+- CGBBYTE1.784.patch `sha1: a25517f60ca0e887d39ec698aa56a0040532a4b3`
 
 To set up the repository, see [INSTALL.md](INSTALL.md).
 

docs/index.md

@@ -21,6 +21,7 @@ These pages are for documenting pieces of the [pokecrystal](https://github.com/p
 - [battle_anim_commands.md](battle_anim_commands.md)
 - [move_effect_commands.md](move_effect_commands.md)
 - [music_commands.md](music_commands.md)
+- [vc_patch.md](vc_patch.md)
 
 
 ## Other subsystems

docs/vc_patch.md

@@ -0,0 +1,124 @@
+# Nintendo 2DS/3DS Virtual Console Patch
+
+The Nintendo Virtual Console is an emulator on the 2DS and 3DS consoles. It can emulate the Game Boy Color (among other consoles), while applying enhancements or modifications to some games, such as replacing Link Cable functionality with the DS' Wireless Link capabilities, or disabling Game Boy Printer features.
+
+Game-specific enhancements are determined by a `.patch` file corresponding to the `.gbc` ROM file. These files are bundled together in a `.cia` file; creating such a file is outside the scope of this project.
+
+
+## Build pokecrystal11.patch
+
+To build **pokecrystal11.patch**:
+
+```bash
+make crystal11_vc
+```
+
+This will also create two ROM files, **pokecrystal11.gbc** and **pokecrystal11_vc.gbc**. The pokecrystal11_vc.gbc file has the patches already applied to it; do *not* use this file! The ROM file and patch file must share the same name, so use pokecrystal11.patch together with pokecrystal11.gbc.
+
+
+## Custom files
+
+There are a few files involved with building the `.patch` file, in addition to the ones used for building ROMs.
+
+### vc/pokecrystal11.patch.template
+
+The `.patch.template` file is the basis for the `.patch` file. Many numeric values in the `.patch` file are derived from the values of labels, constants, and ROM content; these values are abstracted into *commands* that get evaluated by `tools/make_patch` to output symbolic names as their actual values, formatted to match the original `.patch` file.
+
+### vc/pokecrystal11.constants.asm
+
+The `.constants.asm` file is used to create a `.constants.sym` file. Typical `.sym` files only list the values of *labels* (ROM banks and addresses); this file is used to list *constants* that are needed by the `.patch.template`. Any constants that the `.patch.template` refers to must be explicitly printed here with the `vc_const` macro.
+
+### tools/make_patch.c
+
+The program used to convert a `.patch.template` into a `.patch` file.
+
+To convert `vc.patch.template` into `vc.patch`:
+
+```bash
+tools/make_patch labels.sym constants.sym patched.gbc original.gbc vc.patch.template vc.patch
+```
+
+For example, this is what `make crystal11_vc` does:
+
+```bash
+tools/make_patch pokecrystal11_vc.sym vc/pokecrystal11.constants.sym pokecrystal11_vc.gbc pokecrystal11.gbc vc/pokecrystal11.patch.template pokecrystal11.patch
+```
+
+## Patch types
+
+**Hooks** do not directly modify the ROM; they just identify locations within the ROM code. When the emulated code execution reaches a hook, the emulator performs an emulation function. For example, the `BiographySave_ret` hook is located after the code to add a new Hall of Fame entry, and causes the emulator to edit the save file to enable the GS Ball event.
+
+Hooks are defined with the `vc_hook` macro, which defines a label starting with "`.VC_`" for the patch template file to use.
+
+**Patches** directly modify the contents of the ROM. This is done before emulation begins. For example, the `print forbid 1` patch modifies an "`and A_BUTTON`" instruction to "`and 0`", so pressing A will not print Unown on the Game Boy Printer.
+
+Patches are defined with the `vc_patch` and `vc_patch_end` macros; `vc_patch` defines a label starting with "`.VC_`", `vc_patch_end` defines a corresponding label with "`_End`" appended. Between these two macros, the code or data is conditionally different depending on whether or not a patch file is being built.
+
+The sole purpose of creating `pokecrystal11_vc.gbc` and `pokecrystal11_vc.sym` is to make these labels and modifications available to `make_patch` for use in the patch template.
+
+
+## Patch template syntax
+
+**Comments** start at a semicolon "`;`" and continue until the end of the line. They are output as-is, without interpreting commands.
+
+**Patch names** are contained in "`[`" brackets "`]`". They are output as-is, without interpreting commands.
+
+Patch names also set the **current patch label**. This is the label starting with "`.VC_`" followed by the patch name, with any invalid characters (not letters "`A-Z`", digits "`0-9`", underscore "`_`", at sign "`@`", or hash "`#`") converted to underscores "`_`". These labels are conditionally defined only when building the patch file with the `vc_hook` and `vc_patch` macros. For example, the patch name "`[fight begin]`" corresponds to the patch label "`.VC_fight_begin`", generated by the "`vc_hook fight_begin`" macro.
+
+**Commands** are contained in "`{`" braces "`}`". They are not output themselves, but may produce their own output when interpreted.
+
+Commands are interpreted with a series of arguments, separated by whitespace (spaces, tabs, or newlines). Leading and trailing whitespace is ignored; for example, "`{  hex  @  4  }`" is interpreted the same as "`{hex @ 4}`".
+
+Some commands may output a **value series**, which is a series of two-digit hexadecimal bytes separated by spaces, preceded by a decimal count: "<code>a*N*: <i>v1</i> <i>v2</i> [...] <i>vN</i></code>".
+
+Some command names have variants to allow reproducing the exact formatting in a `.patch` file. If the command name is all lowercase, the output byte values use lowercase for hexadecimal digits A-F; if it is all uppercase, they use uppercase. For commands which output a value series, if the command name ends in an underscore, a space is output after the colon preceding the values; if not, then it is not.
+
+**Arguments** evaluate to numeric values. They may be any of the following:
+
+- Literal numbers in decimal (base 10, e.g. "`42`"), hexadecimal (base 16, e.g. "`0x2a`"), or octal (base 8, e.g. "`052`"). They may start with a plus sign "`+`". Numbers may not be negative.
+- Comparison operators: "`==`" is 0, "`>`" is 1, "`<`" is 2, "`>=`" is 3, "`<=`" is 4, "`!=`" is 5, and "`||`" is 0x11.
+- Symbol names from the two `.sym` files provided to `make_patch` may evaluate as their bank-relative address, or their absolute offset in the ROM, depending on the command. They may also be followed by a plus sign and a literal number that gets added to the value.
+- "`@`" evaluates as the address or absolute offset of the current patch/hook label.
+
+Any other characters are output as-is.
+
+
+## Patch template commands
+
+
+### <code>{patch[ <i>offset</i>]}</code>
+
+Outputs the bytes of the current patch as a value series, or as a hexadecimal number if there is only one byte. The bytes are found between the current patch label, and the label which is the current patch label plus "`_End`". An optional argument is an *offset* to add to the current patch label before gathering the contents between it and the end label.
+
+For example, if "`{patch}`" outputs "`a3:ab cd ef`", then "`{patch +1}`" outputs "`a2:cd ef`", and "`{patch +2}`" outputs "`0xef`".
+
+Converting the patch template will print a warning if any differences exist between the original and patched ROMs, which are not covered by "`patch`" commands.
+
+
+### <code>{dws <i>args</i>...}</code>
+
+Outputs its arguments as a value series of little-endian 16-bit words.
+
+Symbol names or "`@`" are evaluated as their relative address.
+
+For example, if "`{dws 42 0xabcd wCurSpecies}`" outputs "`a6:2a 00 cd ab 60 cf`", then "`{dws >= wCurSpecies+3}`" outputs "`a4:04 00 63 cf`".
+
+
+### <code>{db <i>arg</i>}</code>
+
+Outputs its argument as a single-byte value series.
+
+Symbol names or "`@`" are evaluated as their relative address.
+
+For example, "`{db 0xEF}`" outputs "`a1:ef`".
+
+
+### <code>{hex <i>arg</i>[ <i>padding</i>]}</code>
+
+Outputs its first argument as a hexadecimal number. An optional second argument is the minimum length in digits; values shorter than it will be padded with leading zeros.
+
+Symbol names or "`@`" are evaluated as their absolute offset.
+
+This command has extra variants to reproduce inconsistent output casing: "`Hex`" prints the last three digits in lowercase and the rest uppercase; "`HEx`" prints the last two digits in lowercase and the rest uppercase; "`hEX`" prints the last three digits in uppercase and the rest lowercase; and "`heX`" prints the last two digits in uppercase and the rest lowercase.
+
+For example, "`{hex 0xabcd 5}`" outputs "`0x0abcd`".

engine/battle/battle_transition.asm

@@ -21,6 +21,7 @@ DoBattleTransition:
 	ld hl, hVBlank
 	ld a, [hl]
 	push af
+	vc_hook FPA_link_fight_begin
 	ld [hl], $1
 
 .loop
@@ -58,6 +59,7 @@ DoBattleTransition:
 	ld a, $1 ; unnecessary bankswitch?
 	ldh [rSVBK], a
 	pop af
+	vc_hook FPA_link_fight_End4
 	ldh [hVBlank], a
 	call DelayFrame
 	ret
@@ -310,6 +312,7 @@ StartTrainerBattle_Flash:
 	dc 0, 0, 0, 1
 
 StartTrainerBattle_SetUpForWavyOutro:
+	vc_hook FPA_link_fight_End0
 	farcall RespawnPlayerAndOpponent
 	ld a, BANK(wLYOverrides)
 	ldh [rSVBK], a
@@ -367,6 +370,7 @@ StartTrainerBattle_SineWave:
 	ret
 
 StartTrainerBattle_SetUpForSpinOutro:
+	vc_hook FPA_link_fight_End1
 	farcall RespawnPlayerAndOpponent
 	ld a, BANK(wLYOverrides)
 	ldh [rSVBK], a
@@ -509,6 +513,7 @@ ENDM
 .wedge5: db 4, 0, 3, 0, 3, 0, 2, 0, 2, 0, 1, 0, 1, 0, 1, -1
 
 StartTrainerBattle_SetUpForRandomScatterOutro:
+	vc_hook FPA_link_fight_End2
 	farcall RespawnPlayerAndOpponent
 	ld a, BANK(wLYOverrides)
 	ldh [rSVBK], a
@@ -763,6 +768,7 @@ StartTrainerBattle_DrawSineWave:
 	calc_sine_wave
 
 StartTrainerBattle_ZoomToBlack:
+	vc_hook	FPA_link_fight_End3
 	farcall RespawnPlayerAndOpponent
 	ld de, .boxes
 

engine/battle/core.asm

@@ -8940,6 +8940,7 @@ InitBattleDisplay:
 	predef PlaceGraphic
 	xor a
 	ldh [hWY], a
+	vc_hook fight_begin
 	ldh [rWY], a
 	call WaitBGMap
 	call HideSprites

engine/battle_anims/anim_commands.asm

@@ -58,12 +58,20 @@ BattleAnimRunScript:
 	farcall CheckBattleScene
 	jr c, .disabled
 
+	vc_hook FPA_001_Begin
+	vc_hook FPA_002_Begin
+	vc_hook FPA_003_Begin
+	vc_hook FPA_004_Begin
+	vc_hook FPA_005_Begin
+	vc_hook FPA_006_Begin
+	vc_hook FPA_007_Begin
 	call BattleAnimClearHud
 	call RunBattleAnimScript
 
 	call BattleAnimAssignPals
 	call BattleAnimRequestPals
 
+	vc_hook FPA_001_End
 	xor a
 	ldh [hSCX], a
 	ldh [hSCY], a
@@ -673,6 +681,7 @@ BattleAnimCmd_5GFX:
 .loop
 	ld a, [wBattleAnimGFXTempTileID]
 	cp (vTiles1 - vTiles0) / LEN_2BPP_TILE - BATTLEANIM_BASE_TILE
+	vc_hook FPA_042801_Begin
 	ret nc
 	call GetBattleAnimByte
 	ld [hli], a

engine/events/print_unown.asm

@@ -74,7 +74,13 @@ _UnownPrinter:
 	jr nz, .pressed_b
 
 	ldh a, [hJoyPressed]
+	vc_patch print_forbid_1
+if DEF(_CRYSTAL11_VC)
+	and 0
+else
 	and A_BUTTON
+endc
+	vc_patch_end
 	jr nz, .pressed_a
 
 	call .LeftRight

engine/gfx/color.asm

@@ -1033,6 +1033,7 @@ endr
 .FinalPush:
 	ld hl, MltReq1Packet
 	call _PushSGBPals
+	vc_hook Network_RESET
 	jp SGBDelayCycles
 
 SGBBorder_PushBGPals: