tommitytom/retroplug

A frontend for the SameBoy GameBoy emulator, with a focus on music creation. It runs standalone and can be used as an audio plugin (VST) in your favourite DAW!

RetroPlug

A frontend for the SameBoy GameBoy emulator, with a focus on music creation. It runs standalone and can be used as an audio plugin (VST) in your favourite DAW!

Features

• Wraps SameBoy v0.15.7
• Full MIDI support for mGB
• Syncs LSDj to your DAW
• Emulates various Arduinoboy modes
• LSDj tooling - Realtime sample patching, .sav manipulation
• Lua scripting

Download

Visit the releases page to download the latest version.

Installation

• Standalone:
  • Currently the standalone build is provided as a single executable file that can be placed anywhere you'd like.
• VST (Windows):
  • Place the plugin .dll in your VST search path. These paths can generally be configured in your DAW, though the following tend to be the recommended defaults:
    • VST2 (Windows): C:\Program Files\Common Files\VST2

NOTE: Depending on your system configuration, you may need to install the latest Visual C++ redistributable from Microsoft. If the plugin crashes when you try to load it, this is most likely the cause.

Usage

• 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.
• 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)

Configuration

RetroPlug is configurable with Lua configuration files. The configuration files are written on first load if they do not exist, and will be written to the following locations:

• Windows: C:\Users\USERNAME\AppData\Roaming\RetroPlug

You can get to this folder quickly by using the Settings -> Open Settings Folder... option in the context menu.

• config.lua - contains default options for projects and systems
• input/*.lua - contains various input configurations

Button Mapping

The following are defined as the default keyboard and joypad mappings:

Button	Default key	Default pad button
A	W	B
B	D	A
Up	UpArrow	Up, Left Analog Up
Down	DownArrow	Down, Left Analog Down
Left	LeftArrow	Left, Left Analog Left
Right	RightArrow	Right, Left Analog Right
Select	Ctrl	Select (+ R2 for LSDj)
Start	Enter	Start

There are also LSDj specific key bindings to actions:

Action	Default key	Default pad button
DownTenRows	PageDown	R1
UpTenRows	PageUp	L1
CancelSelection	Esc	N/A
Delete	Delete	N/A
StartSelection	Shift (Hold)	X
CopySelection	Ctrl + C	N/A
CutSelection	Ctrl + X	N/A
PasteSelection	Ctrl + V	N/A
ScreenUp	N/A	Right Analog Up
ScreenDown	N/A	Right Analog Down
ScreenLeft	N/A	Right Analog Left
ScreenRight	N/A	Right Analog Right

Additionally, Tab / Pad Y can be used to move between instances when multiple systems are loaded, and Ctrl + S can be used to save your project.

Modifying Button Maps

Input maps have their own specific configuration format. Both keyboard and pad inputs can be assigned directly to Gameboy buttons, or they can be assigned to actions which are defined in Lua scripts. Both keyboard and pad inputs can be defined in a single file, but can be chosen independently of each other in a project.

To modify the button mapping, you can either edit one of the currently existing button maps, or create your own. It is recommended that you make a copy of input/default.lua and modify it to suit your needs. Your button map can then be selected in the context menu via the Settings -> Keyboard and Settings -> Pad menu options.

Supported Keys:

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

Supported Pad Buttons:

The following buttons can be referenced in the input config:

Start, Select, Left, Right, Up, Down, A, B, X, Y, L1, R1, L2, R2, L3, R3, Home, Button17, Button18, Button19, Button20, Button21, Button22, Button23, Button24, Button25, Button26, Button27, Button28, Button29, Button30, Button31

It is also possible to bind the analog sticks to events:

LeftStickLeft, LeftStickRight, LeftStickDown, LeftStickUp, RightStickLeft, RightStickRight, RightStickDown, RightStickUp

All key/button 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.
• 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.
• Using the default keyboard layout, 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 Variation):

  • 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. Other 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. Additionally, dragging a .lsdsng file on to the window will add the song to your .sav file and load it immediately (if the .sav has space to contain the song).

Kit Patching

Kits can be patched, deleted, and exported using the LSDj -> Kits menu.

• Kits can be imported from .kit files, or imported from a previously patched LSDj ROM.
• To import kits to the next available slot, use the LSDj -> Kits -> Import... menu item. If a kit is already in the ROM it will not be imported. This allows you to import all kits from a ROM that the current ROM does not have without creating duplicates.
• To patch a specific kit slot, or to replace an existing kit, choose the kit/slot you want to replace in the context menu, and choose Load... or Replace... respectively.
• Importing kits to a fresh slot requires a reset (this will be done automatically, no song data will be lost). Replacing existing kits does not require a reset, and can be done in realtime while the kit you are patching is currently playing!
• The patched rom is saved in to your DAWs project file when you hit save, or alternatively in to a .rplg file when you save the project to disk.

The ROM that you loaded from disk isn't actually modified. To save the patched ROM out to disk for use on harware or other emulators, using the LSDj -> Export ROM... menu option.

Updating LSDj

Updating to a new verison of LSDj can be quite cumbersome when your ROM is patched with custom samples, though RetroPlug tries to help make this easy by offering a way of swapping out a ROM and keeping custom samples patched. To do this, use the LSDj -> Upgrade To... menu item and select the new LSDj ROM. Please note that this doesn't upgrade the sav data for your songs, so you will still need to be aware that different LSDj versions may make your songs sound completely different!

Roadmap

• v1.0.0
  • Mac build
  • 32bit builds
  • Outputs from individual audio channels
  • Move the emulator instance to a different thread (currently runs in the audio thread)
  • Web build
• 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
• gainput - Gamepad input
• minizip - Zip compression for project files (containing roms, savs, states, etc)
• lua 5.3 - Lua scripting language
• sol - C++ Lua API wrapper
• spdlog - C++ logging library

Building

Windows

Prerequisites

• Visual Studio 2019
• Clang compiler for Visual Studio (clang-cl). This can be installed with the Visual Studio Installer.
• Rednex Game Boy Development System. Must be available via your systems PATH variable.
• Premake 5. Must be available via your systems PATH variable.
• To build the VST2 target, you need to acquire the VST2 SDK. aeffect.h and affectx.h need to be copied in to thirdparty/iPlug2/Dependencies/IPlug/VST2_SDK/

All other dependencies are included in the repository. Run configure.bat, this will write a project to build/vs2019/RetroPlug.sln. Open 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/V3GyA5dtqB

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 default.lua (written to C:\Users\USERNAME\AppData\Roaming\RetroPlug\input 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!

Donations

If you'd like to support development of RetroPlug, donations of any amount are appreciated!

License

MIT

retroplug's Issues

Analog sync

Normal LSDJ sync fails to sync versions that are software overclocked (LSDJ running 4x tempo while on normal clockspeed) and those that have different clock speed. I think problem would be easily solved with analog sync between each instance, or just using analog sync in particular!

retroplug crashes when asio is set as the audio driver

I'm using ableton live 10 lite, retroplug v0.1.0, & sameboy 0.13.6b. trying to use retroplug causes ableton live 10 to crash, either upon opening retroplug, or sometimes upon trying to load lsdj.

Project files cannnot load that has a path included 2-byte characters

I cannot load a project file from D:\GB関連\lsdj\saves\test.retroplug .
"関連" are Japanese Kanji.

In the project file, "GB関連" are transformed to "GB関係". This charactors HEX code is "47 42 E9 96 A2 E4 BF 82". ("47 42 E9 96" are "GB".)
I don't know what the character code of this. For example, UTF-8's "GB関連" HEX code is "47 42 E9 96 A2 E9 80 A3". That wrong code is not a Shift-JIS too.

Finally I can load this project file after I remove 2-byte characters from the file used HEX Editor and fixed the file places.
Can you add multi byte support for project file?

Bug: Sample kits sound bad

Probably won't be fixed until this one is: LIJI32/SameBoy#177

It doesnt work on Podium Free

If i load a rom it freezes while the plugin is completely white. Can still right click.

Suggestion: Add support for Vice emu

Hello, Ive seen in the readme file that you are thinking about adding support for the GBA and Genesis. I dont really understand why, but it would be awesome if you could add support for VICE so we could use defmon http://toolsforscholars.com/defmon/doku.php with RetroPlug

Button input sticks in Ableton

Using Ableton on Windows, there's an issue where the A button gets stuck down - i.e. the emulator receives the button press, but not the button release.

Any chance also for win32 compilation?

Would be cool, using in linux with wine 32-bit, if that would exist. Thanks in advance.

Screen is blank

Hi,

I had previously used RetroPlug with no issues, but now after a few months and after reinstalling Windows 10 on my machine, RetroPlug doesn't work anymore. Whenever I load a ROM, the screen remains blank and there's no sound or input at all. The program seems to work fine and it recognizes LSDJ ROMs, as well as the .sav files, their included songs, etc., but the ROM itself doesn't play.

This happens both in the app version and the dll version. I've tried loading many versions of LSDJ (in case that was the issue) to no avail.

I know that the latest RetroPlug version is a bit old and I might not get any feedback, but this software is quite unique, extremely useful, and I'm hoping that we will get another release at some point.

Thank you.

Req: support sync for Nanoloop

This ROM also supports syncing Via MIDI

Demo ROM can be obtained here for testing:

https://www.nanoloop.com/one/index.html

Accessibility for limited vision users

Thanks to RetroPlug LSDj could be easily designed to be accessible if reading out names of parameters and cursor position would be available to visually impared, and/or through some other solution compatible with open source screen reader, NVDA!

MacOS Support

This is an issue to track MacOS support for RetroPlug.

What's involved in building for MacOS? I see there's an xcode project file in the repo, but it fails to build on my system because I'm missing the AAX SDK. What is that?

lsdj arduinoboy midiout

First of all: thanks for this great piece of software!

I'm trying to send MIDI notes from LSDJ to my keyboard, but it doesn't seem to work.
I have selected the output device from the preferences panel and "all" as output channel and "MIDI-Sync (Arduinoboy)" in the custom lsdj panel.
In lsdj I selected the midi-out synchronization option
Am I doing something wrong or this feature is not implemented?

My configuration:
Windows 10
RetroPlug_standalone-Win64-v0.1.0
lsdj8_3_1-arduinoboy
Akai MPK249 keyboard as a midi receiver

Thanks in advance!

Suddenly unable to load ROMS

I'm sure I'm doing something incorrectly, but spontaneously I'm no longer able to load .gb roms with the standalone or VST version of Retroplug. I'm just stuck on the "DOUBLE CLICK TO LOAD ROM" page. Thankfully I only lost some unimportant things that hadn't been written to .savs, but I'm not sure what's going on. Wasn't sure if a git issue was the right place to post this, but I can't find a social that you're active on. Am I correct in thinking I shouldn't have to build any of the dependencies if I'm just downloading the VST? I don't remember doing that the first time I installed, and it's been working for years.

I'm on windows 10.

I love the plugin btw.

Using ZIP format for plugin chunk data is problematic

Hello. I'm developing OpenMPT, and one of our users had trouble using this VST plugin in OpenMPT: After using it in a track and then trying to reload the track, the whole track failed load. This happens because OpenMPT can load zipped module files, so it first tries to read a file as a ZIP file, and if successful it tries to load a file from that ZIP file as a module. If the file wasn't a ZIP file, it will directly try to load it as a module instead.

What's the problem? Well, ZIP is a peculiar format. Some background information on that, in case you weren't aware: Most people would probably expect that a ZIP file must start with the "PK" magic bytes, but they don't really need to be at the start of the file. To read a ZIP file, you start by finding the central directory, which is placed towards the end of the file. It may not be at the exact end, because a comment text up to 64KB in length may follow. So a typical implementation will seek backwards within the last 64KB of the file to find the central directory (and it seems like many if not all ZIP libraries don't check if the declared length of that comment is actually identical to the number of byte past the end of the central directory). This mechanism is also the reason why you can open a self-extracting ZIP file (i.e. an EXE with embedded ZIP) in pretty much any software that can handle ZIP files - it will simply not care that there's an EXE stub in front of the ZIP.

As a consequence of this design, any music project file of any DAW where the plugin chunk dump by this plugin is placed close to the last 64KB of the project file is at the same time by definition also a valid ZIP file! And as a result of that, any software that, like OpenMPT, can open both regular ZIP files and also its own music project files will end up in a situation where a file is technically both a ZIP file and a music project file. I will try to find a workaround for OpenMPT, but as other DAWs could still encounter similar issues.

As a conclusion, I think it would make sense if RetroPlug didn't give a complete ZIP file as plugin chunk data to the host. I could think of several workarounds:

• XOR-"encrypt" the chunk data. Not very nice but it would avoid being detected as a ZIP file.
• Use a different standard archival container format that cannot be placed in the middle of another file, for example tar.gz
• Just don't use a container format at all and write your own (e.g. zero-terminated filename followed by compressed and uncompressed size fields, followed by zlib-compressed data).
• For backwards compatibility, the plugin should of course still try to load the plugin chunk as a ZIP file.

Audio Routing settings - DAW channel per DMG channel

I guess it depends on the emulator in use here, but would it be possible to have the DMG's channels 1-4 separately on the 4 VST outputs ?

Req: Midi Map buttons and actions

It would be cool to map controls and the save state toggle via midi, then I can make a cool midi controller definition for my controller. Also would be nice to be able to assign a cc to toggle the save in the SRAM context menu.

Linux support

Hi!

First of all thank you for your hard work. I’m currently using Linux (Ubuntu 20.10 more precisely) as my primary OS for making music. I’m also a programmer, so I’m opening this issue mostly for tracking purpose as I’ll be able to work on my own.

VSTs are supported on this platform so a major refactoring shouldn’t be needed. I have access to multiple Linux distributions too so I will be able to test other popular ones like Archlinux, and maybe package it as well so people could install it from their package manager. I could loo into CI/CD to streamline the building process too.

I’ll keep you updated :)

Joypad support

This looks like a good option: https://github.com/jkuhlmann/gainput

RetroPlug is crashing in FL Studio 20

When I try to load a RetroPlug in my FL Studio i receive message:
`The Fruity Wrapper plugin has caused a critical error while loading its state.

It is strongly advised to close the application and restart it, without trying to save your project.
You will find a backup history of your projects in the Backup folder in the browser.

Please contact your plugin's manufacturer about this problem.`

Any ideas what could go wrong?

FL Studio reads RetroPlug as an error.

Hello. I've recently downloaded RetroPlug and put it in my VST2 folder, but it won't work and it's detected by FL Studio as an error. Know that I haven't downloaded or done anything else aside from downloading and placing this .DLL file in my VST2 folder. I hope someone can help me. Sorry for any inconvenience.

Req: Add the option to start/stop on DAW Transport Start/Stop

There should be a menu toggle that if enabled, will send start button clicks when transport starts and again when it is turned off. This will prevent the requirement that LSDJ transport is armed before starting daw transport.

Req: Easy ROM reload for quick development cycles

I'm developing GB software that receives MIDI. I find RP to be incredibly useful for quick testing as it cuts out the cycle of burning a ROM to a flashcart, or developing some solution to fake MIDI data over the serial port. However, it's still slightly annoying that in order to reload ROM (as far as I can tell) you need to system, load ROM, and use the file dialog to select the same ROM file. It would be useful if there was a quicker way. Here are a couple of possible ways this could be achieved.

• Assign some simple way to reload the file through a GUI shortcut, for example double or triple clicking the window. Or use the topmost item in the right click menu (the one that shows the ROM name) to reload the ROM.
• Let the plugin look for changes to the loaded file and reload if it's rewritten.
• Make the process listen for some signal that can be triggered from a build script, for example listening to a TCP port and opening a connection to that ports reloads.

If for example double clicking the window would be considered possibly confusing for users, this might be a feature that needs to be enabled in the config file.

Thanks for the consideration.

i cant get lsdj to run in ableton 9 64 bit

works in renoise on my computer and standalone mode but wont run in ableton live 9 standard 64.bit

Under/Overclocking

LSDj is able to achieve different pitch range on different clock speeds (like lower pulse pitch when underclocked) so having option to change it per instance would be very welcome!