BizHawk Event Shuffler

A fork of Brossentia's BizHawk Shuffler (https://github.com/brossentia/BizHawk-Shuffler) that triggers game swaps when the player performs in-game actions (e.g. collecting a ring in Sonic games)

Games with events defined in the "Events" folder will switch when said event is triggered. All other games will obey the same switch-after-a-random-time-period rules as in Brossentia's original shuffler.

Setup (the same as Brossentia's but with a different Lua script)

A script and setup program to randomize games being played in BizHawk! Currently, players can slip ROMs into the CurrentROMs folder and have the play order generated by a Lua script. The setup program generates a seed, sets the min/max times of each game played before switching, and an option to include a countdown.

This version works with BizHawk from version 2.5.3 onwards. Future official releases should also work with it. However, there is a known issue where the error Can't have lua running in two host threads at a time! is thrown by some games. For this reason, it is recommended to download and use the version below, which suppresses this error.

Recommended version: https://www.alistairaitcheson.com/downloads/BizHawk_2.6.1_with_shuffler_fix_001.zip

Should be simple to get working! To use the shuffler, do the following:

1. Put ROMs into a "CurrentROMs" folder located in the same folder as EventShuffler.lua. You may leave ROMs in a .zip, but do not leave them in a folder.
2. Delete the "DeleteMe" files in the two ROM folders.
3. Run RaceShufflerSetup.exe to set your seed, your min/max time, and whether or not you want an on-screen three-second countdown for the upcoming swap.
4. Open Bizhawk.
5. Open a ROM for each console (NES, SNES, etc.) you're using, and map controls for them.
6. Go to Tools > Lua, then load the EventShuffler.lua script. (SoloShuffler.lua to run Brossentia's original script)
7. Enjoy!

If you wish to change the min/max times, add/remove games during playthrough, add a countdown on the screen, and randomize the seed (recommended), open the RaceShufflerSetup.exe.

Please note: If you move from 2 ROMs down to 1, only switch while playing the final game. Otherwise, the shuffler will stay on the one you just completed. I'll be fixing this later!

The file "CurrentROM.txt" will automatically change when moving to a new ROM. Feel free to use this for your OBS layout.

Future builds will hopefully have the following:

1. Ability to determine a swap order rather than having games shuffled.
2. Auto-remove DeleteMe files.
3. Add source code to this repository for the setup program.

Changing Event Shuffler Settings

Run the program EventShufflerSetup.exe to change the following settings used in EventShuffler.lua:

• Should debug output be shown in Lua console
• Should the game use the timer as well as events to switch games
• What happens when an event is triggered (switch games, write into RAM, or send button to controls reader)

You can also change the following settings for ControlsOutputReader.lua

• Should debug output be shown in Lua console
• How long should games wait between changing the selected button

You can also edit the events that are defined for each game. These changes will take effect the next time a game switch occurs, or when EventShuffler.lua is restarted.

Having One Game Control Another

1. Run the program EventShufflerSetup.exe
2. Make sure Send button press to Controls Reader is checked
3. Open the game you want to be in control in BizHawk
4. Open the Lua console and run EventShuffler.lua.
   • If you want this game to be silent, type client.SetSoundOn(false) in the Lua console
5. Open a second instance of BizHawk. In this new instance, open the game you want to receive the controls
6. Open the Lua console for this instance and run ControlsOutputReader.lua

If you want to change which events cause the selected button to change, do the following:

1. While EventShuffler.lua is running, run the program EventShufflerSetup.exe
2. Click on Show/Add Current Game
3. Click on the event you want to change, under Events for this game
4. Change the value of Control Reader Effect.
   • PRESS - the receiving game will press a button when this event fires
   • CHANGE - the receiving game will change selected button when this event fires

Adding Support for New Games

1. Open the game you want to add in BizHawk. Run the script EventShuffler.lua in the Lua console.
2. Run the program EventShufflerSetup.exe
3. Press Show/Add Current Game
4. Use the event editor to define the new rule

Supported Games

The following games have events associated with them. If there is a specific version of the game that isn't supported (e.g. JP version of Super Mario World) could you type in gameinfo.getromname() in the Lua console, and let me know what text gets printed?

Versions with a * next to them will throw the Can't have two instances of Lua... error unless this patched version of BizHawk is used: https://www.alistairaitcheson.com/downloads/BizHawk_2.6.1_with_shuffler_fix_001.zip

Nintendo 64

• Super Mario 64 *

SNES

• Super Mario World
• Super Mario Kart
• The Legend of Zelda: A Link to the Past *

NES

• Super Mario Bros
• Super Mario Bros 2
• Super Mario Bros 3
• Dr Mario
• Donkey Kong
• The Legend of Zelda
• Zelda II: The Adventure of Link

Game Boy

• Super Mario Land
• Super Mario Land 2
• Wario Land: Super Mario Land 3
• The Legend of Zelda: Link's Awakening *

Game Boy Color

• The Legend of Zelda: Link's Awakening DX *
• The Legend of Zelda: Oracle of Ages *
• The Legend of Zelda: Oracle of Seasons *

Genesis

• Sonic the Hedgehog
• Sonic the Hedgehog 2
• Sonic the Hedgehog 3
• Sonic & Knuckles
• Sonic Spinball
• Sonic 3D Blast

Master System

• Sonic the Hedgehog
• Sonic the Hedgehog 2
• Sonic Chaos
• Sonic Blast

Game Gear

• Sonic the Hedgehog
• Sonic the Hedgehog 2
• Sonic Chaos
• Sonic Triple Trouble
• Sonic Blast

Defining Events

To add your own events for a game, create a file with the file name [game name] [console ID].txt in the "Events" folder, where:

• [game name] is the name of the ROM as defined by BizHawk, up to but not including a [ or ( character. (Find names from the Lua console by typing in gameinfo.getromname())
• [console ID] is the ID of the console as defined by BizHawk (Found from the Lua console by typing in emu.getsystemid())

Event triggers are given as lines of the form [trigger name]>bytes:[comma separated hex values]/domain:[name of memory domain]/base:[10,100 or 256]/delay:[frame count]/minChange:[int]/maxChange[int] Fields after the > can be in any order. If not set then the fields will use default parameters.

• trigger name (e.g. rings) - an internal name for what counter has changed
• bytes (e.g. FE20,FE21,FE22) - which bytes to calculate the value from (lowest first)
• domain (e.g. 68K RAM. Default varies by console) - which RAM state to look in (Found from the Lua console by typing in memory.getmemorydomainlist())
• base (default = 256) If 256, each byte gives a hex value between #00 and #FF. If 100 values are decimal, so the value #99 represents the number 99 rather than the number 153). If 10 values are all between #00 and #09.
• delay (default = 0) The number of frames between the most recent event and the switch triggering. Used, for example, to differentiate between the score going up because you got a coin, and the score going up because of an end-of-level totaliser.
• minChange (default = 0) If the value changes less than this in one frame then do not switch.
• maxChange (default = 1000000000) If the value changes more than this in one frame then do not switch.

TO DO

• Add infinite lives functionality
• More games!!!

Contact me

games@alistairaitcheson.com Twitter: http://twitter.com/agaitcheson