An HTTP interface for mGBA scripting. As long as you make HTTP requests, you'll be able to interact with mGBA.
⭐ I've written about this on my blog! 📝
- Interact with mGBA with any language that supports HTTP
- Full Swagger API documentation (swagger.json and SwaggerUI) for fast prototyping and integration
- Maps 1 to 1 with most of the mGBA scripting API
- Custom button APIs for easy button interaction
- Cross platform
- Easy to setup
This project is great if you want to:
- Create a "Twitch Plays"
- Write an AI bot in your preferred programming language
- Create an information dashboard for the current game (e.g. show your current Pokémon's stats like Pokélink)
- Edit the memory of the running game
In the example below, we accept inputs from one program and send them to mGBA:
- (top left) is accepting key inputs from keyboard and sending them to mGBA-http
- (top right) mGBA-http is forwarding these to mGBA
- (bottom left) mGBA's built-in scripting API accepting the requests from mGBA-http
- (bottom right) then the key inputs are read by the ROM
If you want to see more real examples with videos, code, and explanations, check out the examples page.
There are also C# examples I use for testing in the testing folder.
example1-pokemonyellowmovement2.mp4
mGBA-http works with 0.10.2+.
- Ensure you have mGBA
- Download mGBA-http and mGBASocketServer.lua from the Releases section
- Run mGBA-http
- In mGBA, go to Tools > Scripting, then File > Load script and load in mGBASocketServer.lua
Once a ROM is loaded, you are now ready to start using mGBA-http.
For a more in-depth guide with pictures, see the Full Guide.
- No frame perfect calls. There is network latency between your application to mGBA-http and again latency between mGBA-http and mGBA. This will not be accurate for frame perfect manipulation and is meant for more general usage such as for "Twitch plays", AI playing bot, or other non frame specific application. For high accuracy manipulation see Bizhawk which is used for TASBots.
- Not all scripting calls are implemented. See ImplementedApis.md for the list of what is implemented.
- The OSX and Linux binaries are experimental.
This project came about because I didn't know lua and wanted to use C# control emulated Pokémon games in a cross platform way. I was there for and loved Twitch Plays Pokémon and looking around, most GitHub projects for "X plays" style emulator controllers use the Windows SendKey API (or similar abstraction) regardless of language.
When investigating how Ironmon-Tracker worked after seeing it on Arex's stream, I noticed mGBA has a scripting API and more specifically a socket API which I could interact with via C# and it went from there[1][2].
mGBA-http builds on the mGBA socket API abstraction and adds an HTTP layer to simplify interaction and development - which is exactly what I want for future projects.
Future projects such as the proof of concept: CPU Plays Pokemon
If you know Lua, GameBoy/Advance, or mGBA specifics, I'd love for help.
If you're a .NET developer, the setup simple and familiar opening the solution file. I use Visual Studio (At least VS 17.9) and the latest .NET. However, if you choose to develop C# without Visual Studio, that's fine too.
If you're not a .NET developer, check out the comprehensive C# learning website from Microsoft. You can program in C# on whatever platform whether it's Windows, Mac, or Linux.
In terms of the .NET work, the project uses ASP.NET Core minimal API.
The rough design philosphy is outlined in the design document. Please understand and follow this when considering a contribution.
The PowerShell release script ReleaseBuild.ps1 creates the final binaries. PowerShell is cross platform and can be downloaded via the PowerShell download documentation.
The script generates binaries closely aligned with the operating systems and architectures that mGBA provides downloads for.
To reduce the barrier of entry, mGBA-http also has self-contained builds. These are the larger binaries with "self-contained" in the filename and bring the entirity of .NET needed to run the executable - meaning the user does not need to download the .NET runtime to use mGBA-http.
If there's a problem feel free to start an issue, otherwise see my about page on how to contact me.
- The mGBA GitHub team for having socket examples
- Zachary Handley for paving the way with the initial button press code
- heroldev/AGB-buttontest for a simple button testing ROM
References.md has useful links during development.
This project is not associated to the development or development team of mGBA. I'm just a fan ✌
If you end up using mGBA-http, drop me a message and tell me what you're up to!
