Skip to content
A VST wrapper around the SameBoy GameBoy emulator, with Arduinoboy emulation
Branch: master
Clone or download
Latest commit 26f4517 Jul 7, 2019

README.md

RetroPlug

A VST wrapper around the SameBoy GameBoy emulator, with Arduinoboy support

Features

Current Limitations (subject to change)

  • VST2 only
  • Windows only
  • 64bit only

Download

Visit the releases page to download the latest version.

Usage

  • Load it as you would any normal VST
  • Double click to open file browser, or drag a rom on to the UI to load
  • A .sav with the same name as your rom will be loaded if it is present
  • Right click to bring up a menu with various options
  • The emulator state is saved in to the project file in your DAW when you hit save, which will persist your changes. YOUR .sav IS NOT AUTO SAVED. If you want to save out the .sav then do so from the SRAM context menu.
  • To edit button mapping, go to Settings -> Open Settings Folder... and edit buttons.json (full list of button names below)
  • For mGB, the usual Arduinoboy rules apply: https://github.com/trash80/mGB - no additional config needed, just throw notes at it!
  • For LSDj, an additional menu will appear in the settings menu, allowing you to set sync modes (Arduinoboy emulation)

Button Mapping

Keyboard button mapping is currently only configurable with JSON configuration files. On first run a config file is written to C:\Users\USERNAME\AppData\Roaming\RetroPlug containing the following default button map:

Button Default key
A Z
B X
Up UpArrow
Down DownArrow
Left LeftArrow
Right RightArrow
Select Ctrl
Start Enter

Supported Keys for buttons.json:

Keys 0 - 9 and A - Z can be used for alpha numeric keys, as well as the following keys:

Backspace, Tab, Clear, Enter, Shift, Ctrl, Alt, Pause, Caps, Esc, Space, PageUp, PageDown, End, Home, LeftArrow, UpArrow, RightArrow, DownArrow, Select, Print, Execute, PrintScreen, Insert, Delete, Help, LeftWin, RightWin, Sleep, NumPad0, NumPad1, NumPad2, NumPad3, NumPad4, NumPad5, NumPad6, NumPad7, NumPad8, NumPad9, Multiply, Add, Separator, Subtract, Decimal, Divide, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14, F15, F16, F17, F18, F19, F20, F21, F22, F23, F24, NumLock, Scroll

All key names are CASE SENSITIVE!

Multiple Instances

You can load multiple instances of the emulator in a single window, and link them with virtual link cables. The goal of this feature is to offer a streamlined way of working with multiple instances of LSDj. You can create an additional emulator instance using the Project -> Add Instance submenu. Choose one of the following options:

  • Load ROM... - Loads a ROM from disk in to the new instance.
  • Same ROM - Loads the ROM of the currently active instance in to the new instance. The created instance will load the .sav file accompanying the ROM.
  • Duplicate - Creates an exact copy of the currently active instance by coying its state.

Additional information:

  • You can create up to 4 instances.
  • Instances are linked when the Game Link option is enabled. This has to be done on every instance that is to be linked.
  • You can move between instances with the Tab key.

Audio Routing

By default, the output of all instances will be summed together in to a single stereo output. The Project -> Audio Routing menu contains additional options for audio routing:

  • Stereo Mixdown - The default option. Mixes the audio of all instances in to two stereo channels.
  • Two Channels Per Instance - Each instance will output on its own 2 channels. Instance 1 will output on channels 1-2, instance 2 will output on channels 3-4, etc. This may require additional configuration in your DAW. This feature is not available in the standalone version.

MIDI Routing

By default, each instance receives all MIDI messages received on all channels. The Project -> MIDI Routing menu contains additional options for MIDI routing:

  • All Channels to All Instances - The default option. Sends all messages received to all instances.
    • A usage example for this mode could be using LSDj in the Arduinoboy MIDI sync mode, where you want multiple instances to sync to a single C-2 note on.
  • Four Channels Per Instance - Evenly maps MIDI channels across up to four instances.
    • The first instance will receive channels 1-4, the second will receive channels 5-8, etc.
    • This is handy for mGB, since it allows you to evenly split all 16 MIDI channels across 4 mGB instances.
    • Also useful for LSDj in MIDI Map mode, since the mode makes use of 2 channels per instance.
  • One Channel Per Instance - Similar to the mode above but for more simplistic uses.
    • The first instance will receive MIDI from channel 1, the second will receive MIDI from channel 2, etc.
    • A more obvious choice if you want control over individual instances when using the Arduinoboy MIDI sync mode (LSDj).

Multi LSDj Setup

For LSDj versions lower than v6.1.0, one instance of LSDj needs to be set to MASTER and the others need to be set to SLAVE. Versions v6.1.0 and above no longer have these modes, but have a singular LSDJ mode, where the instance that initiates playing automatically becomes the master. It appears there may be additional overhead to this new mode that may make things go slightly out of sync - so it is recommended that if you want perfect sync between more than one instance of LSDj that you use one of the MIDI sync modes. This will sync both instances to your DAW, rather than to each other.

LSDj Integration

When LSDj is detected, additional options are added to the context menus.

Sync Modes

  • Off: No sync with your DAW at all. If you hit play in LSDj it will play regardless of what else is happening.

  • MIDI Sync:

    • Receives MIDI clock from your DAW when the transport is running.
    • If you hit play in LSDj, it will not play until you hit play in your DAW. LSDj should be set to "MIDI" mode on the project page.
    • In this mode LSDj knows nothing about the song position in your DAW, all it knows is that it is receiving a MIDI clock, and that it should play.
  • MIDI Sync (Arduinoboy mode):

    • Receives MIDI clock from your DAW, but only plays once a C-2 note is received.
    • Additional Arduinoboy options are emulated, full list can be found here.
  • MIDI Map:

    • Receives MIDI clock from your DAW, and plays the row number relative to MIDI notes that you send it. C-0 is row 0, C#-0 is row 1, etc.
    • Notes sent on channel 2 map to rows 128 and above. Ohter channels are ignored.
    • Rows are stopped when note offs are received, or when you hit stop in your DAW.
    • Requires the Arduinboy build of LSDj.
  • Auto Play:

    • When this option is enabled, RetroPlug will simulate a press of the start button whenever the transport in your DAW is started or stopped.
    • Works in combination with the other sync modes.
    • This option is pretty dumb (it doesnt know if LSDj is playing or not), so it's possible to make it think it is in the wrong state if you manually press Start. If this happens just press Start again.

.sav Manipulation

Thanks to the liblsdj library you are able to list, export, import, load, and delete tracks contained in your LSDj save. The LSDj Songs context menu contains these features.

Additional Options

  • Keyboard Shortcuts: Enables a set of common shortcuts that allows you to use LSDj with a keyboard in a more intuitive manner. This works by sending combinations of button presses to LSDj, so support for these may not always be perfect! Many of the hotkeys for these settings can be modified in the button config file (see Button mapping), although a few can't:
Action Default key(s) Configurable
ScreenUp W Yes
ScreenLeft A Yes
ScreenDown S Yes
ScreenRight D Yes
DownTenRows PageDown Yes
UpTenRows PageUp Yes
CancelSelection Esc Yes
Delete Delete Yes
StartSelection Shift (Hold) No
CopySelection Ctrl + C No
CutSelection Ctrl + X No
PasteSelection Ctrl + V No

Roadmap

  • v1.0.0
    • 32bit builds
    • Mac builds
    • Outputs from individual audio channels
    • Lua scripting
    • LSDj sample patching
  • v2.0.0
    • Additional emulators. Support for C64, GBA and Megadrive/Genesis is being explored.

Dependencies

  • SameBoy - The emulator itself
  • iPlug2 - Audio plugin framework
  • libsdj - Adds the functionality to manipulate LSDj save files
  • tao json - JSON library used for dealing with configs and save states

Building

Windows

RetroPlug is developed in Visual Studio 2019, however SameBoy has to be built using msys2 (mingw) on Windows. Since we can't statically link libraries produced by mingw in VS, the DLL output from the build process is compiled as a resource in to the final VST DLL, which is then loaded from memory at runtime. This allows us to ship the VST as a single DLL.

  • Install msys2 to the default location
  • Make sure rgbds is accessible from your command line (via the PATH variable or some other method)
  • Run thirdparty/SameBoy/retroplug/build.bat
  • Open RetroPlug.sln in Visual Studio 2019 and build.

Mac

Coming soon!

Troubleshooting

Please refrain from asking usage questions in GitHub issues, and use them purely for bugs and feature requests. If you need help, the official support chat for this plugin is on the PSG Cabal discord channel: https://discord.gg/9MdBJST

FAQ

Q: HALP! The keyboard does not work ;(

A: All hosts are different, and some have restrictions on routing keyboard input in to VST instruments. First, click the center of the window to try and force the host to give focus to the correct control. If that doesn't work, make sure your host is allowing the plugin to receive keyboard input (Renoise has an "Enable keyboard" option, etc). If it still doesn't work, try editing default keyboard mapping in buttons.json (written to C:\Users\USERNAME\AppData\Roaming\RetroPlug on first run). There are some quirks with certain DAWs...

  • Reaper does not send the ctrl key to VST's, so you'll need to remap that to something different.

If you find you have issues with a particular DAW, please feel free to submit a bug report.

Q: OMG! LSDj does not start when I hit play in my DAW :o

A: Make sure you have the correct sync mode selected in both LSDj, and in the context menu!

License

MIT

You can’t perform that action at this time.