game-and-watch-zelda3/README.md

Port of reverse engineered zelda3 for the Game and Watch

All credits for reverse engineering goes to https://github.com/snesrev/zelda3

Requirements

Minimum flash size of 2MB (the game uses around 1.5MB of extflash).

GCC >= 12

Build instructions

• Clone repository with submodules

git clone --recurse-submodules https://github.com/marian-m12l/game-and-watch-zelda3.git

• Install python requirements using pip

pip3 install -r requirements.txt
pip3 install -r zelda3/requirements.txt

• Place your US ROM file named zelda3.sfc in zelda3/tables.

• Optionally, place your localized ROM file zelda3_<lang>.sfc in zelda3/tables (e.g. zelda3_fr.sfc).

• Compile and flash (e.g. on internal flash bank 2, leaving 1MB (out of 16) for stock firmware at the beginning of extflash, french language)

make INTFLASH_BANK=2 EXTFLASH_SIZE_MB=15 EXTFLASH_OFFSET=1048576 ADAPTER=jlink OPENOCD=/path/to/patched/openocd-git/bin/openocd GNW_TARGET=mario DIALOGUES_LANGUAGE=fr flash

List of build flags

To control how the firmware is programmed:

Build flag	Description
INTFLASH_BANK	Which internal flash bank to program. 1 or 2.
EXTFLASH_OFFSET	Offset after which to program external flash. In bytes.
EXTFLASH_SIZE_MB	Allocated space in external flash. In MB.
LARGE_FLASH	Required for external flash chips > 16MB. Enables 32-bit addressing.

To control game options:

Build flag	Description
LIMIT_30FPS	Limit to 30 fps for improved stability. Enabled by default. Disabling this flag will result in unsteady framerate and stuttering.
OVERCLOCK	Overclock level: 0 (no overclocking), 1 (intermediate overclocking), or 2 (max overclocking). Default value: 2.
RENDER_FPS	Render performance metrics. Disabled by default.
ENABLE_SAVESTATE	Enable savestate support. This allocates 178kB of external flash. Disabled by default.
FASTER_UI	Increase UI speed (item menu, etc.). Enabled by default.
BATTERY_INDICATOR	Display battery indicator in item menu. Enabled by default.
EXTENDED_SCREEN	Extended screensize (0 for default screen size 256x224, 1 for full-height 256x240, 2 for full screen 320x240). Default value: 1.

(WIP) Building as a Retro-Go application (a.k.a. running in RAM)

DISCLAIMER: This is work-in-progress

Zelda3 can be run without flashing to intflash. The "intflash" binary can be stored in the Retro-Go filesystem and loaded into RAM for execution.

The Retro-Go filesystem must be large enough to fit the "intflash" binary on top of emulator savestates.

make [...] flash_extflash
make [...] build/gw_zelda3_intflash.bin
tamp compress build/gw_zelda3_intflash.bin -o build/gw_zelda3_intflash.bin.tamp
python3 gnwmanager.py push /apps/zelda3.bin.tamp build/gw_zelda3_intflash.bin.tamp

Backing up and restoring save (SRAM)

ADAPTER=jlink OPENOCD=/path/to/patched/openocd-git/bin/openocd ./scripts/saves_backup.sh build/gw_zelda3.elf 
ADAPTER=jlink OPENOCD=/path/to/patched/openocd-git/bin/openocd ./scripts/saves_erase.sh build/gw_zelda3.elf 
ADAPTER=jlink OPENOCD=/path/to/patched/openocd-git/bin/openocd ./scripts/saves_restore.sh build/gw_zelda3.elf 

Using savestate

To enable savestate (as opposed to SRAM saves), add ENABLE_SAVESTATE=1 to your make command.

Save is automatic on power off (you can power off without saving by holding PAUSE/SET and pressing POWER).

You can save by pressing GAME + A. You can load the savestate by pressing GAME + B.

Backing up and restoring savestate

ADAPTER=jlink OPENOCD=/path/to/patched/openocd-git/bin/openocd ./scripts/savestate_backup.sh build/gw_zelda3.elf 
ADAPTER=jlink OPENOCD=/path/to/patched/openocd-git/bin/openocd ./scripts/savestate_erase.sh build/gw_zelda3.elf 
ADAPTER=jlink OPENOCD=/path/to/patched/openocd-git/bin/openocd ./scripts/savestate_restore.sh build/gw_zelda3.elf 

Applying additional features

Edit the FEATURE_* values in Makefile to enable additional features and bug fixes to the original game.

List of features

Build flag	Description
FEATURE_SWITCH_LR	Item switch on L/R. Also allows reordering of items in inventory by pressing Y+direction. Hold X, L, or R inside of the item selection screen to assign items to those buttons. If X is reassigned, Select opens the map. Push Select while paused to save or quit. When L or R are assigned items, those buttons will no longer cycle items.
FEATURE_TURN_WHILE_DASHING	Allow turning while dashing.
FEATURE_MIRROR_TO_DARK_WORLD	Allow mirror to be used to warp to the Dark World.
FEATURE_COLLECT_ITEMS_WITH_SWORD	Collect items (like hearts) with sword instead of having to touch them.
FEATURE_BREAK_POTS_WITH_SWORD	Level 2-4 sword can be used to break pots.
FEATURE_DISABLE_LOW_HEALTH_BEEP	Disable the low health beep.
FEATURE_SKIP_INTRO_ON_KEYPRESS	Avoid waiting too much at the start. Enabled by default.
FEATURE_SHOW_MAX_ITEMS_IN_YELLOW	Display max rupees/bombs/arrows with orange/yellow color.
FEATURE_MORE_ACTIVE_BOMBS	Allows up to four bombs active at a time instead of two.
FEATURE_CARRY_MORE_RUPEES	Can carry 9999 rupees instead of 999.
FEATURE_MISC_BUG_FIXES	Enable various zelda bug fixes.
FEATURE_CANCEL_BIRD_TRAVEL	Allow bird travel to be cancelled by hitting the X key.
FEATURE_GAME_CHANGING_BUG_FIXES	Enable some more advanced zelda bugfixes that change game behavior.
FEATURE_SWITCH_LR_LIMIT	Enable this to limit the ItemSwitchLR item cycling to the first 4 items.