FullGuide-lua.md

Full Guide (lua script only)

This guide is for using the .lua script. If you need to use the full application, see Full Guide (application).

Setup

1. Ensure you have mGBA
2. Download both mGBA-http and mGBASocketServer.lua from the Releases section.
   • Which version of mGBASocketServer.lua?
     • Version 0.5.0 and lower is easier to use. Simply fire off the message
     • Version 0.6.0 and higher requires <|END|> to be at the end of the request, and will reply with <|END|> at the end of the response.
3. Open mGBA and click Tools > Scripting to open the Scripting window.
4. In the scripting window click File > Load script to bring up the file picker dialog.
5. Select the mGBASocketServer.lua file you downloaded earlier
6. Load up a ROM in mGBA
7. Done, the lua script is ready to accept commands

Usage

By default the script will listen to port 8888.

To see what mGBA scripting APIs are implemented, see the implemented APIs document.

Python example

For version 0.5.0 and lower:

import socket

HOST = "127.0.0.1"
PORT = 8888

with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
    s.connect((HOST, PORT))
    s.sendall(b"core.getGameTitle")
    data = s.recv(1024).decode()

print(f"Game Title: {data}")

For version 0.6.0 and higher:

import socket

HOST = "127.0.0.1"
PORT = 8888 
TERMINATION_MARKER = "<|END|>" 

with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
    s.connect((HOST, PORT))
    
    command = "core.getGameTitle" + TERMINATION_MARKER
    s.sendall(command.encode())
    
    buffer = ""
    while True:
        chunk = s.recv(1024).decode()
        buffer += chunk
        
        if TERMINATION_MARKER in buffer:
            response = buffer.split(TERMINATION_MARKER)[0]
            break

print(f"Game Title: {response}")

Examples inspired by Socket Programming in Python by Nathan Jennings

Configuration

Depending on the version, the script has some easy to configure options for logging and the port number at the top.