Skip to content

Latest commit

 

History

History
105 lines (71 loc) · 6.5 KB

README.md

File metadata and controls

105 lines (71 loc) · 6.5 KB

mGBA-http

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! 📝

Features

  • 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

Example

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

Quick Start Guide

mGBA-http works with 0.10.2+.

  1. Ensure you have mGBA
  2. Download mGBA-http and mGBASocketServer.lua from the Releases section
  3. Run mGBA-http
  4. 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.

Limitations

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

Why?

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

Contributing

If you know Lua, GameBoy/Advance, or mGBA specifics, I'd love for help.

Development

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.

Design Document

The rough design philosphy is outlined in the design document. Please understand and follow this when considering a contribution.

Build

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.

Cross Platform

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.

Contact

If there's a problem feel free to start an issue, otherwise see my about page on how to contact me.

Acknowledgments

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 ✌

Links

License

MIT

If you end up using mGBA-http, drop me a message and tell me what you're up to!