SkyEmu contains a web server that implements a REST-like API that can be used to control SkyEmu from other programs and scripts.
This interface provides access to the following functionality:
- Loading arbitrary ROM files
- Retrieving the emulated screen's image
- Reading/Writing arbitrary memory addresses in the emulated system
- Stepping the emulator a controlled number of frames
- Controlling user inputs for the emulator and emulated console
To enable the server check the "Enable HTTP Control Server" option in the advanced settings and configure the port.
Additionally, SkyEmu can be launched in a mode optimized for headless display using the following commandline parameters:
./SkyEmu http_server <Server Port> <Path To ROM file>
When running using these parameters, SkyEmu won't render the UI and will run without sleeping to synchronize with real time.
A description of each of the supported API commands is shown below. You can test each command using a standard web browser by visiting a link like below:
http://localhost:<port>/cmd?Param=Value
Returns the word 'pong' used to check if the server is up.
Example:
http://localhost:8080/ping
Result:
pong
Steps the emulator forward one or more frames. A frames parameter can be optionally provided to step the emulator a fixed number of frames. Otherwise, the emulator steps a single frame. Returns "ok" on completion.
Example:
http://localhost:8080/step
Result:
The emulator is stepped ahead 1 frame.
ok
Example:
http://localhost:8080/step?frames=100
Result:
The emulator is stepped ahead 100 frames.
ok
The emulator is un-paused and runs at 1x speed. Returns "ok" on completion.
Example:
http://localhost:8080/run
Result:
The emulator is playing at 1x speed.
ok
Returns a png image of the current screen of the emulated system. The parameter embed_state can be set to 1 to embed the emulation save state similar to the /save commands output on emulators that support it (ie. SkyEmu). The default keeps embed_state set to 0.
The paramater format specifies which image format to use. It can be set to png, jpg, or bmp. If not specified, png is used by default.
Example:
http://localhost:8080/screen
Result:
<png image of screen>
Example:
http://localhost:8080/screen?format=jpg
Result:
<jpg image of screen>
Example:
http://localhost:8080/screen?embed_state=1
Result:
<much larger png image of screen with save state embedded>
Reads one or multiple bytes of data from the emulated system at addresses provided using parameters. The addr parameter can be repeated an arbitrary amount of times to read an arbitrary amount of bytes.
The paramater map can be used to specify different address maps. This is currently only used in the NDS core where address map 7 is used for the ARM7 address map and 0 and 9 are used for the ARM9 address map. The default address map is 0. The map command only effects bytes read after the parameter and does not persist across API calls.
Example (Read a single byte):
http://localhost:8080/read_byte?addr=02000004
Result:
1 byte of data is returned in hexadecimal
f0
Example (Read multiple bytes):
http://localhost:8080/read_byte?addr=02000004&addr=02000005&addr=02000006
Result:
3 bytes of data are returned in hexadecimal (in the order mem[0x02000004], mem[0x02000005], mem[0x02000006])
f0bf01
Example (Read multiple bytes from different address spaces ):
http://localhost:8080/read_byte?addr=02000004&map=7&addr=02000005&addr=02000006
Result:
3 bytes of data are returned in hexadecimal (in the order mem_map0[0x02000004], mem_map7[0x02000005], mem_map7[0x02000006] of map 7)
f0bf01
Writes one or multiple bytes of data from the emulated system at addresses provided using parameters. Multiple addresses can be written to in a single command. Returns "ok" on completion
The paramater map can be used to specify different address maps. This is currently only used in the NDS core where address map 7 is used for the ARM7 address map and 0 and 9 are used for the ARM9 address map. The default address map is 0. The map command only effects bytes read after the parameter and does not persist across API calls.
Example (Write a single byte):
http://localhost:8080/write_byte?02000000=ff
Result:
mem[0x02000000] = 0xff;
okay
Example (Write multiple bytes):
http://localhost:8080/write_byte?02000000=ff&02000001=ee&02000002=cc
Result:
mem[0x02000000] = 0xff;
mem[0x02000001] = 0xee;
mem[0x02000002] = 0xcc;
ok
Example (Write multiple bytes from different maps ):
http://localhost:8080/write_byte?02000000=ff&map=7&02000001=ee&02000002=cc
Result:
mem_map0[0x02000000] = 0xff;
mem_map7[0x02000001] = 0xee;
mem_map7[0x02000002] = 0xcc;
ok
Sends an input to the emulated system which will stay until a different input command assigns a new value. The parameters specify the input to set and the value to set it to. In general all inputs that have keybinds in the GUI can be set using this command. A full list of the valid input names and their current state is viewable with the /status command. An arbitrary number of inputs can be set using this command. Returns "ok" on completion.
Example (Sends a sequence of commands)
All buttons start released.
http://localhost:8080/input?A=1&Up=1
A and Up are now being pressed.
http://localhost:8080/input?B=1&Up=0
A and B are now being pressed (and Up was released)
http://localhost:8080/input?B=0
A is being pressed (and B was released)
http://localhost:8080/input?A=0
No button is being pressed (A was released)
http://localhost:8080/input?A=0
Example (Send a special command to capture a save state slot)
http://localhost:8080/input?Capture State 0=1
Hot key for capturing save state 0 is being pressed.
http://localhost:8080/step
Emulation is stepped, completing the capture into save state 1
http://localhost:8080/input?Capture State 0=0
Hot key is released.
Returns a json file filled with info about the current state of the emulator and the state of the HTTP Control Server Inputs that are being fed into the emulator.
Example
http://localhost:8080/status
Result:
{
"emulator": "SkyEmu (6af0053049aa689a79ae653a949ed70e517ce2e1)",
"run-mode": "RUN",
"rom-loaded" : true,
"rom-path": "/Users/skylersaleh/Documents/roms/gba/varooom-3d.gba",
"save-path": "/Users/skylersaleh/Documents/roms/gba/varooom-3d.sav",
"rewind-info" : {
"entries-used" : 953,
"capacity" : 1048576,
"percent_full" : 0.1
},
"inputs": {
"A": 0.000000,
"B": 0.000000,
"X": 0.000000,
"Y": 0.000000,
"Up": 0.000000,
"Down": 0.000000,
"Left": 0.000000,
"Right": 0.000000,
"L": 0.000000,
"R": 0.000000,
"Start": 0.000000,
"Select": 0.000000,
"Fold Screen (NDS)": 0.000000,
"Tap Screen (NDS)": 0.000000,
"Emulator /": 0.000000,
"Emulator ": 0.000000,
"Emulator ": 0.000000,
"Emulator ": 0.000000,
"Capture State 0": 0.000000,
"Restore State 0": 0.000000,
"Capture State 1": 0.000000,
"Restore State 1": 0.000000,
"Capture State 2": 0.000000,
"Restore State 2": 0.000000,
"Capture State 3": 0.000000,
"Restore State 3": 0.000000,
"Reset Game": 0.000000,
"Turbo A": 0.000000,
"Turbo B": 0.000000,
"Turbo X": 0.000000,
"Turbo Y": 0.000000,
"Turbo L": 0.000000,
"Turbo R": 0.000000,
"Solar Sensor+": 0.000000,
"Solar Sensor-": 0.000000,
"Toggle Full Screen": 0.000000
}
}
Saves a save state to a parameter specified "path" on the server. Returns "ok" on success and "failed" on error.
Example
http://localhost:8080/save?path=/tmp/save.png
Result:
A save state is created on the server in /tmp/save.png
ok
Loads a save state from a parameter specified "path" on the server. Returns "ok" on success and "failed" on error.
Example
http://localhost:8080/load?path=/tmp/save.png
Result:
The state of the emulator is restored to where it was at the time the /tmp/save.png save state was taken.
ok
Loads a rom from a parameter specified "path" on the server. Can be initially paused by setting the "pause" parameter. Returns "ok" on success.
Example
http://localhost:8080/load?path=/tmp/rom.gba&pause=1
Result:
Loads the rom at /tmp/rom.gba and pauses the emulator.
ok
Lists the current cheats and their status
Example
http://localhost:8080/cheats
Result:
0 - My first cheat: 12345678 AABBCCDD (enabled)
1 - My second cheat: 12345678 90ABCDEF (disabled)
Remove one or more cheats
Example
http://localhost:8080/remove_cheat?id=0&id=1
Result:
Removes cheats at index 0 and 1
ok
Edits or adds a cheat. If the id field is not specified, it will try to add a cheat on the first available id. There's a guarantee for at least 32 cheat slots.
All of the fields are optional, but at least one field other than id must exist. enabled defaults to 1.
Example
http://localhost:8080/add_cheat?name=My cheat&code=12345678AABBCCDD&id=0&enabled=1
Result:
The following cheat will be added:
0 - My cheat: 12345678 AABBCCDD (enabled)
If a cheat already existed at id 0, because id 0 was specified, the cheat will be overwritten with the new one