How to Create a Shuffler Plugin

Creating a Shuffler Plugin

Download the empty base plugin. (Right click and Save As to download the file)

Include the name of the plugin, your name (author), and the minimum version of Bizhawk your plugin is tested for (minversion).

Events

All methods are sent (1) a data table that can be used to maintain persistent information, even across reloads, and (2) a settings table that contains key-value pairs with settings names as keys and their associated values. Both of these tables are unique to the plugin, so collisions will not happen with other plugins, even if they use the same keys. All methods are optional and any methods that are unused can be safely deleted.

• function plugin.on_setup(data, settings)
  • called once when a shuffler session is started
• function plugin.on_frame(data, settings)
  • called once per frame
• function plugin.on_game_load(data, settings)
  • called when a new game is loaded
• function plugin.on_game_save(data, settings)
  • called when a shuffle is about to happen, before the current game is unloaded
• function plugin.on_complete(data, settings)
  • called when a game is marked as complete, before it is unloaded

The code you write in these methods can draw on any of the methods available through Bizhawk's Lua interface, as well as any functions or variables in shuffler.lua. For Bizhawk-specific methods, please refer to the limited documentation on tasvideos.org, but the shuffler-specific functions/variables you are most likely to find useful are as follows:

• swap_game()
  • Forces a swap at the next possible frame
• swap_game_delay(x)
  • Updates the next scheduled swap to take place x frames from now

Creating Settings

When a plugin is enabled, the user is shown a list plugin-specific settings created by the plugin author. This window looks like the one below.

The "Enabled" button is added automatically, but the rest of the settings are generated from the plugin.settings table. Settings are represented by tables with a name (the name of the setting), type (the type of setting, refer to the list below), and a label (a human-readable description of the setting). The following list contains the types and any additional required information:

• type='boolean'
  • Creates a checkbox. The setting will be a boolean value, true or false, indicating whether the box was checked
  • Optional key: default - if provided and true, the checkbox will default to being checked
• type='romlist'
  • Creates a dropdown menu containing names of games in the games/ folder
• type='select'
  • Creates a dropdown menu containing values specified by a table value associated the required key options
  • Optional key: default - if provided, the dropdown will default to the value associated with this key
• type='file'
  • Creates a button that will open a file select dialog to choose a file. The setting will hold the filename of the chosen file
• type='text'
  • Creates a text box. The setting will contain the contents of the box as a string
  • Optional key: default - if provided, the text box will start pre-filled with the value associated with this key
  • Optional key: password - a boolean specifying whether the box should hide contents with a password character. default: false
• type='number'
  • Creates a text box. The setting will contain the contents of the box as a number
  • Optional key: datatype - if provided, the contents of the text box will be restricted based on the forms.textbox Bizhawk Lua function
  • Optional key: default - if provided, the text box will start pre-filled with the value associated with this key

You can refer to existing plugins for examples of how to create your own settings. All methods receive a table containing the settings for your plugin that you can refer to. For instance, if you have a text setting named color, you can refer to the value of this setting via settings.color in any of the methods.

Sharing Your Plugin

If you think your plugin might be of general interest to others and you've tested it thoroughly to ensure that it is free of any obvious bugs, feel free to create a pull request to have your plugin added to this repository.