Creating Category Presets

This guide will walk you through creating a new preset category in the practice hack without any assembly knowledge. All you need is an emulator and your time.

Links

Preset Organization Spreadsheet: https://docs.google.com/spreadsheets/d/1EoOHbldvlxyENVEGpJfy3OgU77sxkYhbF56rr39n-ck/edit#gid=508407274

Download Snes9x-rr v1.51 from https://github.com/TASVideos/snes9x-rr/releases/tag/snes9x-151-v7.1 (get the .zip and extract it)

How it Works

Category presets are made by recording a run in an emulator movie and using a lua script during playback. The script extracts the relevant data at specific timestamps and formats it into two ASM files. These files contain the code for the menus as well as the data needed to load the preset. The preset data is a list of memory addresses and values to be written. When a preset is loaded, the data from the first preset is consumed, followed by the next preset's data. This continues until the selected preset is reached, and all subsequent data has been loaded.

Creating an Emulator Movie

Run Snes9x.exe and load your SM rom. Navigate through the File menu to the Movie submenu and select Record New Movie. Give it a name and make sure 'Record from reset' is selected and 'Clear SRAM' is unchecked. Once you click OK, the game resets and starts recording your gameplay.

While the movie is running, you can make emulator savestates and reload them at will. Start up the game (hopefully intro cleared but not required) and play the run. When you get to a point where you want a preset created, put Samus in the optimal position to start the next room and wait there for 1-2s. You can pause the emulator while sitting there and record the frame number in the spreadsheet. Once you've got the frame number recorded, you can continue on to the next one.

Teledump Script

The script is in the tools folder on GitHub, named teledump.lua. Open it in any text editor. At the top of the script you'll see codenames for each of the existing preset categories. Create a new one for your category and add it to the list. The one on the left in "quotes" is the currently selected category, which should be the newest. Scroll past the memory addresses until you see the list of local SEGMENTS. Make a copy of one of the existing categories and replace text as necessary to match what you have in the sheet. Scroll down again until you see the list of local STEPS. These are the individual presets you made in the spreadsheet. The frame number is listed first in [brackets], followed by segment number that determines which segment submenu it will belong to. The name goes at the end in "quotes".

Once you've finished editing and saved your script, you can run it with the emulator movie to generate the preset files. Start by playing the movie back, then opening the Lua dialog and clicking browse to select the teledump.lua script. Click run and ensure there are no errors in the dialog box. You can fast-forward the emulator and let the script do its magic. Two files will be generated with the names presets_menu.asm and presets_data.asm. Rename the files by replacing presets with the codename of your category. Move the two files into the src/presets folder.

Adding Presets to the ROM

There are two files that need to be edited in order to include your new presets. Start with presets.asm and search for category_preset_data_table: to find the list of "first presets" of each category. You can copy the first line of text in your preset_data.asm file, remove the colon, and add in the dl to match the other categories. Be mindful of the order in which you place your presets. This order will need to be maintained later. Scroll to the bottom of presets.asm and add a new incsrc to the list with your preset_data.asm and preset_menu.asm files.

The next file to edit is mainmenu.asm, and there are five places that need attention. The order you chose in presets.asm must be maintained in nearly all parts of mainmenu.asm. Start with a search for preset_category_submenus: near the top. Add in your category and be mindful of capitalization. The very next section gets the same new line with >>16 added. Next, search for SelectPresetCategoryMenu: to find the next list. Another list follows it with a fixed-width format. Make sure the quotes line up when you're done. Finally, you'll need to copy two lines in place to setup the menu item. Be mindful of the numbering at the end of each category. It's zero-indexed and counts in hexidecimal.

Extra Notes

• You must start a preset in the room BEFORE the thing you want to practice. Presets delete enemies (by default) in the room when they load.
• The practice menu fits 21 presets per segment comfortably, or 23 if you don't mind crossing the border. Any more than that will be off-screen.
• Menu items can contain spaces, uppercase, lowercase, numbers, and the following symbols: : ! . - , ? # ( ) ' % $ +
• Menu headers are limited to spaces, uppercase, numbers and the following symbols: : ! . - , ? # ( ) ' % +
• Max of 26 characters per line.