Mesen

https://github.com/sourmesen/mesen2
Admin
Mesen is a multi-system emulator supporting NES, SNES, Game Boy, Game Boy Advance, PC Engine,...
Tokens:472,276
Snippets:2,449
Trust Score:6.4
License:GPL-3.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### C# usage examples for Config API

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/config-api.md

Shows how to apply a full audio config, enable maximum-speed emulation and stdout logging, and install shortcut keys using the C# ConfigApi. The shortcut keys are passed as an array of InteropShortcutKeyInfo with a KeyCombination.

```csharp
// C# — apply a full audio config
InteropAudioConfig audio = new InteropAudioConfig();
audio.MasterVolume = 80;
audio.SampleRate = 44100;
ConfigApi.SetAudioConfig(audio);

// C# — enable maximum-speed emulation and stdout logging
ConfigApi.SetEmulationFlag(EmulationFlags.MaximumSpeed, true);
ConfigApi.SetEmulationFlag(EmulationFlags.OutputToStdout, true);

// C# — install shortcut keys (array of { shortcut, keyCombination })
InteropShortcutKeyInfo[] shortcuts = { new InteropShortcutKeyInfo(EmulatorShortcut.FastForward, KeyCombination.TabKey) };
ConfigApi.SetShortcutKeys(shortcuts, shortcuts.Length);
```

--------------------------------

### Get label address example

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-memory-api.md

Looks up the address of the "start" label and logs it if found.

```lua
local addr = emu.getLabelAddress("start")
if addr then emu.log(string.format("label start @ %06X", addr.address)) end
```

--------------------------------

### Netplay host and guest usage example (C#)

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/netplay-api.md

Shows the C# host and guest netplay workflow. The host starts a server on port 6000 with a secret, selects controller port 0, and the guest connects to the host IP with the same secret. The guest retrieves the controller list and disconnects.

```csharp
// Host
NetplayApi.StartServer(6000, "secret");
bool running = NetplayApi.IsServerRunning();
NetplayApi.NetPlaySelectController(new NetplayControllerInfo(0, 0)); // host uses port 0

// Guest
NetplayApi.Connect("192.168.1.10", 6000, "secret", false);
bool connected = NetplayApi.IsConnected();
NetplayControllerUsageInfo[] controllers = new NetplayControllerUsageInfo[8];
int32 count = 8;
NetplayApi.NetPlayGetControllerList(controllers, ref count);
NetplayApi.Disconnect();

```

--------------------------------

### Example of emu.log, emu.displayMessage, and emu.getLogWindowLog

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-misc-api.md

Example usage of the logging functions: logs a debug line, displays an OSD message with category "Script", and retrieves the full emulator log.

```lua
emu.log("debug line")
emu.displayMessage("Script", "Loaded.")
local fullLog = emu.getLogWindowLog()
```

--------------------------------

### C++ host: disassembly search and single-step

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/debugger-api.md

C++ host example showing how to get disassembly output, convert a program counter to a row address, step one instruction, and check if execution is stopped.

```cpp
// C++ host — search a disassembly and step one instruction
CodeLineData out[64];
uint32_t n = GetDisassemblyOutput(CpuType::Snes, 0, out, 64);
int32_t rowAddr = GetDisassemblyRowAddress(CpuType::Snes, 0xC000, 1);
Step(CpuType::Snes, 1, StepType::Step);
bool stopped = IsExecutionStopped();
```

--------------------------------

### Log script data folder if available

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-misc-api.md

Example of getting the script data folder and logging it if it is not empty.

```lua
local dir = emu.getScriptDataFolder()
if dir ~= "" then emu.log("data dir: " .. dir) end
```

--------------------------------

### Log ROM name from emu.getRomInfo

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-misc-api.md

Example of retrieving ROM info and logging the ROM name.

```lua
local rom = emu.getRomInfo()
emu.log("running " .. rom.name)
```

--------------------------------

### StartServer

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/netplay-api.md

Starts a netplay server (host) that binds a TCP listener on the specified port. An empty password disables authentication.

```APIDOC
## StartServer

### Description
Starts a netplay server (host) that binds a TCP listener on the specified port. An empty password disables authentication.

### Method
StartServer

### Endpoint
StartServer(port, password)

### Parameters
- **port** (uint16_t) - Required - The TCP port to listen on.
- **password** (char*) - Required - The password for authentication; empty string disables authentication.

### Response
No return value.
```

--------------------------------

### WaveRecord

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/record-api.md

Starts WAV audio recording.

```APIDOC
## WaveRecord

### Description
Starts recording mixed audio to a WAV file.

### Method
C function

### Endpoint
`void WaveRecord(char* filename)`

### Parameters
- **filename** (char*) - Required - Path to the output WAV file.

### Request Example
```cpp
WaveRecord("run.wav");
```

### Response
No return value.
```

--------------------------------

### RomTestRecord

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/test-api.md

Starts recording a .test file on the live emulator, optionally resetting the game first.

```APIDOC
## RomTestRecord

### Description
Starts recording a .test file on the live emulator, optionally resetting the game first.

### Method
C API function

### Endpoint
void RomTestRecord(char* filename, bool reset)

### Parameters
#### Function Parameters
- **filename** (char*) - Required - Path to the .test file to record to.
- **reset** (bool) - Required - If true, resets the game before recording.

### Returns
- **void** - No return value.

### Example
```csharp
TestApi.RomTestRecord(@"C:\tests\mario.test", true /*reset*/);
```
```

--------------------------------

### SetShortcutKeys

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/config-api.md

Installs shortcut key bindings. Takes an array of InteropShortcutKeyInfo objects, each mapping an EmulatorShortcut to a KeyCombination.

```APIDOC
## SetShortcutKeys

### Description
Installs shortcut key bindings.

### Method
C# API call

### Parameters
- **shortcuts** (InteropShortcutKeyInfo[]) - Required - Array of shortcut key info objects, each containing an EmulatorShortcut and a KeyCombination.
- **length** (int) - Required - The number of shortcuts in the array.

### Request Example
```csharp
InteropShortcutKeyInfo[] shortcuts = { new InteropShortcutKeyInfo(EmulatorShortcut.FastForward, KeyCombination.TabKey) };
ConfigApi.SetShortcutKeys(shortcuts, shortcuts.Length);
```
```

--------------------------------

### AviRecord

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/record-api.md

Starts AVI recording of rendered frames.

```APIDOC
## AviRecord

### Description
Starts lossless-ish AVI capture of the rendered frames.

### Method
C function

### Endpoint
`void AviRecord(char* filename, RecordAviOptions options)`

### Parameters
- **filename** (char*) - Required - Path to the output AVI file.
- **options** (RecordAviOptions) - Required - Options for AVI recording, including codec, compression level, and HUD flags.

### Request Example
```cpp
RecordAviOptions opt = { VideoCodec::H264, 0, true, false };
AviRecord("run.avi", opt);
```

### Response
No return value.
```

--------------------------------

### C++ host usage examples through the C API

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/config-api.md

Shows how to set video config, enable maximum-speed emulation, and read/modify/write NES config using the C API from a C++ host. The NES config is read, modified, and written back.

```cpp
// C++ host — same operations through the C API
VideoConfig vc = { };
vc.VideoFilter = VideoFilterType::xBRZ4x;
vc.AspectRatio  = VideoAspectRatio::Auto;
SetVideoConfig(vc);

SetEmulationFlag(EmulationFlags::MaximumSpeed, true);

NesConfig nes = GetNesConfig();   // read current, modify, write back
nes.Port1.Type = ControllerType::NesController;
SetNesConfig(nes);
```

--------------------------------

### RecordedRomTest::Record

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/test-api.md

Starts recording a .test file, optionally resetting the game first.

```APIDOC
## RecordedRomTest::Record

### Description
Starts recording a .test file, optionally resetting the game first.

### Method
C++ class method

### Endpoint
void Record(char* filename, bool reset)

### Parameters
#### Function Parameters
- **filename** (char*) - Required - Path to the .test file to record to.
- **reset** (bool) - Required - If true, resets the game before recording.

### Returns
- **void** - No return value.

### Example
```cpp
recordedTest.Record("mario.test", true);
```
```

--------------------------------

### Get, edit, and set emulator state

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-emulation-api.md

Example of fetching the state table, inspecting `consoleType` and `frameCount`, editing a field (e.g., `frameCount`), and applying the changes with `setState`. Works for any serializable console field.

```lua
local state = emu.getState()
emu.log(state.consoleType .. " frame " .. state.frameCount)
state.frameCount = 0            -- any serializable console field may be edited
emu.setState(state)
```

--------------------------------

### C# host: initialize debugger, read CPU state, memory, breakpoints

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/debugger-api.md

C# host example showing how to initialize the debugger, read CPU state and program counter, read/write memory while paused, perform an undo (gated by HasUndoHistory()), set a breakpoint at a mapped address, and resume execution.

```csharp
// Ensure the debugger exists, then read CPU state
DebugApi.InitializeDebugger();
BaseState cpuState = new SnesCpuState();
DebugApi.GetCpuState(cpuState, CpuType.Snes);
uint32 pc = DebugApi.GetProgramCounter(CpuType.Snes, false);

// Read a memory byte while paused
uint8 value = DebugApi.GetMemoryValue(MemoryType.SnesWorkRam, 0x7E0000);
DebugApi.SetMemoryValue(MemoryType.SnesWorkRam, 0x7E0000, 0x42);
DebugApi.PerformUndo(); // HasUndoHistory() gate

// Breakpoint at a mapped address
Breakpoint[] bps = { new Breakpoint(0, BreakSource.Breakpoint, 0xC000, MemoryType.SnesPrgRom, CpuType.Snes) };
DebugApi.SetBreakpoints(bps, 1);
DebugApi.ResumeExecution();
```

--------------------------------

### MovieRecord

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/record-api.md

Starts recording an input movie.

```APIDOC
## MovieRecord

### Description
Starts recording an input movie (inputs + savestate).

### Method
C function

### Endpoint
`void MovieRecord(RecordMovieOptions options)`

### Parameters
- **options** (RecordMovieOptions) - Required - Options for movie recording, including filename, author, description, and starting state.

### Request Example
```cpp
RecordMovieOptions opt = { /* C# fills byte arrays; C-side struct mirrors them */ };
MovieRecord(opt);
```

### Response
No return value.
```

--------------------------------

### C# usage example for recording and replaying tests

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/test-api.md

Shows how to record a test session with TestApi.RomTestRecord, stop it with TestApi.RomTestStop, and replay it in background with TestApi.RunRecordedTest. The result is checked against RomTestState.Passed and the error code is printed on failure.

```csharp
// Record a session
TestApi.RomTestRecord(@"C:\tests\mario.test", true /*reset*/);
// ... play ...
TestApi.RomTestStop();

// Replay in background (headless) and inspect the outcome
RomTestResult result = TestApi.RunRecordedTest(@"C:\tests\mario.test", true);
if(result.State != RomTestState.Passed) {
    Console.WriteLine("Test failed, error code " + result.ErrorCode);
}
```

--------------------------------

### C API usage example

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/test-api.md

Shows how to call RunRecordedTest and RunTest from C. RunRecordedTest returns a RomTestResult to check, while RunTest reads an 8-byte value from the specified memory address.

```cpp
// C API
RomTestResult r = RunRecordedTest("mario.test", true);
if(r.State != RomTestState::Passed) { /* handle */ }
uint64_t twoBytes = RunTest("gb.gb", 0x2000, MemoryType::GbWorkRam);
```

--------------------------------

### Compile with Clang on Linux

Source: https://github.com/sourmesen/mesen2/blob/master/COMPILING.md

Run `make` to compile Mesen2 with Clang. Requires SDL2 and .NET 8 SDK installed.

```bash
make
```

--------------------------------

### Example Lua script using emu.addEventCallback and drawing functions

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-api.md

Example Lua script that registers an end-of-frame callback to draw a rectangle and a string with the current frame count, then displays a message. Uses emu.getState(), emu.getMouseState(), emu.drawRectangle(), emu.drawString(), emu.addEventCallback(), and emu.displayMessage().

```lua
-- UI/Debugger/Utilities/LuaScripts/Example.lua (excerpt)
function printInfo()
  state = emu.getState()
  mouseState = emu.getMouseState()
  emu.drawRectangle(8, 8, 128, 24, 0x302060FF, true, 1)
  emu.drawString(12, 12, "Frame: " .. state["frameCount"], 0xFFFFFF, 0xFF000000)
end
emu.addEventCallback(printInfo, emu.eventType.endFrame);
emu.displayMessage("Script", "Example Lua script loaded.")
```

--------------------------------

### C# host application integration with EmuApi

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/emu-api.md

C# host application integration example: initializes the emulator, loads a ROM, retrieves the log, saves/loads state, and releases the core. Failures surface as false/null returns plus ConsoleNotificationType events.

```csharp
// C# host application
EmuApi.InitializeEmu(homeFolder, windowPtr, viewerPtr, false, false, false, false);
bool ok = EmuApi.LoadRom("game.sfc"); // patchFile defaults to null
String log = EmuApi.GetLog();
EmuApi.SaveState(1);            // quick-save slot 1
EmuApi.LoadState(1);
EmuApi.Release();
```

--------------------------------

### C++ host application integration with EmuApi

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/emu-api.md

C++ host application integration example: initializes the emulator core, loads a ROM with an optional patch file, and registers a notification callback for the GameLoaded event.

```cpp
// Initialize the emulator core (equivalent of what UI does at startup)
InitDll();
InitializeEmu("/path/to/home", windowHandle, viewerHandle, false /*hw renderer*/, false, false, false);

// Load a ROM with an optional patch file
bool ok = LoadRom("game.sfc", "patch.bps");

// Register a notification callback
INotificationListener* listener = RegisterNotificationCallback([](int type, void* param) {
    if((ConsoleNotificationType)type == ConsoleNotificationType::GameLoaded) {
        // game started
    }
});
```

--------------------------------

### MoviePlay

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/record-api.md

Starts playback of an input movie.

```APIDOC
## MoviePlay

### Description
Plays an input movie (`.movie`).

### Method
C function

### Endpoint
`void MoviePlay(char* filename)`

### Parameters
- **filename** (char*) - Required - Path to the movie file to play.

### Request Example
```cpp
MoviePlay("run.movie");
```

### Response
No return value.
```

--------------------------------

### Get ROM info with emu.getRomInfo

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-misc-api.md

Returns a table with ROM file name, path, and SHA-1 hash. No errors.

```lua
emu.getRomInfo()   -- → { name=String, path=String, fileSha1Hash=String }
```

--------------------------------

### C# usage of HistoryApi for scrubbing history

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/history-api.md

C# host example that initializes the history viewer, iterates backward through history positions, then resumes gameplay and releases the viewer. Uses HistoryViewerOptions with paused=false, volume=100, and 512x448 viewport.

```csharp
if(HistoryApi.HistoryViewerEnabled()) {
    HistoryApi.HistoryViewerInitialize(windowPtr, viewerPtr);
    HistoryApi.HistoryViewerSetOptions(new HistoryViewerOptions(false /*paused*/, 100 /*volume*/, 512, 448));

    HistoryViewerState state = HistoryApi.HistoryViewerGetState();
    for(uint32 pos = state.Length; pos > 0; pos--) {
        HistoryApi.HistoryViewerSetPosition(pos);
        // viewer renders the historical frame on its own renderer
    }

    HistoryApi.HistoryViewerResumeGameplay(state.Position); // jump back into live emulation
    HistoryApi.HistoryViewerRelease();
}
```

--------------------------------

### Debug API Usage Examples

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/debugger-api.md

Code snippets demonstrating the Debug API usage in C# and C++ hosts.

```APIDOC
## DebugApi.InitializeDebugger

### Description
Initializes the debugger. Must be called before using other debugger functions.

### Method
InitializeDebugger

### Parameters
None

### Request Example
```csharp
DebugApi.InitializeDebugger();
```

### Response
No return value.
```

```APIDOC
## DebugApi.GetCpuState

### Description
Retrieves the current CPU state for the specified CPU type.

### Method
GetCpuState

### Parameters
- **cpuState** (BaseState) - Required - Output parameter that receives the CPU state.
- **cpuType** (CpuType) - Required - The CPU type (e.g., Snes).

### Request Example
```csharp
BaseState cpuState = new SnesCpuState();
DebugApi.GetCpuState(cpuState, CpuType.Snes);
```

### Response
No return value. The state is written to the `cpuState` parameter.
```

```APIDOC
## DebugApi.GetProgramCounter

### Description
Gets the program counter value for the specified CPU type.

### Method
GetProgramCounter

### Parameters
- **cpuType** (CpuType) - Required - The CPU type (e.g., Snes).
- **isDebugger** (bool) - Required - Whether to use the debugger context.

### Request Example
```csharp
uint32 pc = DebugApi.GetProgramCounter(CpuType.Snes, false);
```

### Response
Returns the program counter as a uint32.
```

```APIDOC
## DebugApi.GetMemoryValue

### Description
Reads a single byte from the specified memory type at the given address.

### Method
GetMemoryValue

### Parameters
- **memoryType** (MemoryType) - Required - The memory type (e.g., SnesWorkRam).
- **address** (uint32) - Required - The memory address to read.

### Request Example
```csharp
uint8 value = DebugApi.GetMemoryValue(MemoryType.SnesWorkRam, 0x7E0000);
```

### Response
Returns the byte value at the specified address.
```

```APIDOC
## DebugApi.SetMemoryValue

### Description
Writes a single byte to the specified memory type at the given address.

### Method
SetMemoryValue

### Parameters
- **memoryType** (MemoryType) - Required - The memory type (e.g., SnesWorkRam).
- **address** (uint32) - Required - The memory address to write.
- **value** (uint8) - Required - The byte value to write.

### Request Example
```csharp
DebugApi.SetMemoryValue(MemoryType.SnesWorkRam, 0x7E0000, 0x42);
```

### Response
No return value.
```

```APIDOC
## DebugApi.PerformUndo

### Description
Undoes the last memory write operation. Should be gated by `HasUndoHistory()`.

### Method
PerformUndo

### Parameters
None

### Request Example
```csharp
DebugApi.PerformUndo();
```

### Response
No return value.
```

```APIDOC
## DebugApi.SetBreakpoints

### Description
Sets breakpoints for the debugger.

### Method
SetBreakpoints

### Parameters
- **breakpoints** (Breakpoint[]) - Required - Array of breakpoint objects.
- **count** (int) - Required - Number of breakpoints in the array.

### Request Example
```csharp
Breakpoint[] bps = { new Breakpoint(0, BreakSource.Breakpoint, 0xC000, MemoryType.SnesPrgRom, CpuType.Snes) };
DebugApi.SetBreakpoints(bps, 1);
```

### Response
No return value.
```

```APIDOC
## DebugApi.ResumeExecution

### Description
Resumes execution of the emulated system after a pause or breakpoint.

### Method
ResumeExecution

### Parameters
None

### Request Example
```csharp
DebugApi.ResumeExecution();
```

### Response
No return value.
```

```APIDOC
## GetDisassemblyOutput

### Description
Retrieves disassembly output for the specified CPU type.

### Method
GetDisassemblyOutput

### Parameters
- **cpuType** (CpuType) - Required - The CPU type (e.g., Snes).
- **startRow** (uint32) - Required - The starting row index.
- **out** (CodeLineData[]) - Required - Output array to receive disassembly lines.
- **maxLines** (uint32) - Required - Maximum number of lines to retrieve.

### Request Example
```cpp
CodeLineData out[64];
uint32_t n = GetDisassemblyOutput(CpuType::Snes, 0, out, 64);
```

### Response
Returns the number of lines retrieved.
```

```APIDOC
## GetDisassemblyRowAddress

### Description
Gets the row address for a given program counter value in the disassembly.

### Method
GetDisassemblyRowAddress

### Parameters
- **cpuType** (CpuType) - Required - The CPU type (e.g., Snes).
- **address** (uint32) - Required - The memory address.
- **rowCount** (int32) - Required - Number of rows to consider.

### Request Example
```cpp
int32_t rowAddr = GetDisassemblyRowAddress(CpuType::Snes, 0xC000, 1);
```

### Response
Returns the row address as an int32.
```

```APIDOC
## Step

### Description
Steps the CPU by a specified number of instructions.

### Method
Step

### Parameters
- **cpuType** (CpuType) - Required - The CPU type (e.g., Snes).
- **stepCount** (uint32) - Required - Number of steps to execute.
- **stepType** (StepType) - Required - The type of step (e.g., Step).

### Request Example
```cpp
Step(CpuType::Snes, 1, StepType::Step);
```

### Response
No return value.
```

```APIDOC
## IsExecutionStopped

### Description
Checks whether the emulated CPU is currently stopped (e.g., at a breakpoint).

### Method
IsExecutionStopped

### Parameters
None

### Request Example
```cpp
bool stopped = IsExecutionStopped();
```

### Response
Returns a boolean indicating whether execution is stopped.
```

--------------------------------

### Step and rewind usage examples

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-emulation-api.md

Example usage of `step` and `rewind`. `step` is shown called from a `codeBreak` event to advance 3 instructions of the SNES CPU with `stepOver` type. `rewind` is shown called from an exec callback to rewind 5 seconds of history.

```lua
-- called from a codeBreak event: advance 3 instructions of the SNES CPU
emu.step(3, emu.stepType.stepOver, emu.cpuType.snes)

-- called from an exec callback: rewind 5 seconds of history
emu.rewind(5)
```

--------------------------------

### C# usage of RecordApi for AVI, WAV, and movies

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/record-api.md

C# usage examples for the RecordApi wrapper: recording AVI with H.264 codec and system HUD, recording WAV audio, and recording/playing input movies. Shows the full lifecycle including stop calls and status checks.

```csharp
// Record 60 seconds of AVI with the system HUD
RecordAviOptions avi = new RecordAviOptions();
avi.Codec = VideoCodec.H264;
avi.CompressionLevel = 0;
avi.RecordSystemHud = true;
RecordApi.AviRecord(@"C:\captures\run.avi", avi);
// ... later
RecordApi.AviStop();

// Wave audio
RecordApi.WaveRecord(@"C:\captures\run.wav");
RecordApi.WaveStop();

// Input movie
RecordMovieOptions movie = new RecordMovieOptions("run.movie", "author", "TAS attempt", RecordMovieFrom.StartWithSaveData);
RecordApi.MovieRecord(movie);
bool recording = RecordApi.MovieRecording();
RecordApi.MovieStop();

RecordApi.MoviePlay("run.movie");
bool playing = RecordApi.MoviePlaying();
RecordApi.MovieStop();
```

--------------------------------

### States and Registers

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/debugger-api.md

Functions to get and set console, CPU, and PPU states, and program counter.

```APIDOC
## GetConsoleState

### Description
Gets the console state.

### Method
N/A (C function)

### Endpoint
N/A

### Parameters
- **state** (BaseState&) - Required - Output state.
- **consoleType** (ConsoleType) - Required - Console type.

### Request Example
N/A

### Response
#### Success Response
None

#### Response Example
N/A

## GetCpuState

### Description
Gets the CPU state.

### Method
N/A (C function)

### Endpoint
N/A

### Parameters
- **state** (BaseState&) - Required - Output state.
- **cpuType** (CpuType) - Required - Target CPU subsystem.

### Request Example
N/A

### Response
#### Success Response
None

#### Response Example
N/A

## GetPpuState

### Description
Gets the PPU state.

### Method
N/A (C function)

### Endpoint
N/A

### Parameters
- **state** (BaseState&) - Required - Output state.
- **cpuType** (CpuType) - Required - Target CPU subsystem.

### Request Example
N/A

### Response
#### Success Response
None

#### Response Example
N/A

## SetCpuState

### Description
Sets the CPU state.

### Method
N/A (C function)

### Endpoint
N/A

### Parameters
- **state** (BaseState&) - Required - State to set.
- **cpuType** (CpuType) - Required - Target CPU subsystem.

### Request Example
N/A

### Response
#### Success Response
None

#### Response Example
N/A

## SetPpuState

### Description
Sets the PPU state.

### Method
N/A (C function)

### Endpoint
N/A

### Parameters
- **state** (BaseState&) - Required - State to set.
- **cpuType** (CpuType) - Required - Target CPU subsystem.

### Request Example
N/A

### Response
#### Success Response
None

#### Response Example
N/A

## GetProgramCounter

### Description
Gets the program counter.

### Method
N/A (C function)

### Endpoint
N/A

### Parameters
- **cpuType** (CpuType) - Required - Target CPU subsystem.
- **getInstPc** (bool) - Required - Whether to get the instruction PC.

### Request Example
N/A

### Response
#### Success Response
- **uint32_t** - The program counter value.

#### Response Example
N/A

## SetProgramCounter

### Description
Sets the program counter.

### Method
N/A (C function)

### Endpoint
N/A

### Parameters
- **cpuType** (CpuType) - Required - Target CPU subsystem.
- **addr** (uint32_t) - Required - Address to set.

### Request Example
N/A

### Response
#### Success Response
None

#### Response Example
N/A

## GetDebuggerFeatures

### Description
Gets debugger features for a CPU type.

### Method
N/A (C function)

### Endpoint
N/A

### Parameters
- **cpuType** (CpuType) - Required - Target CPU subsystem.

### Request Example
N/A

### Response
#### Success Response
- **DebuggerFeatures** - Features supported by the debugger.

#### Response Example
N/A

## GetInstructionProgress

### Description
Gets instruction progress for a CPU type.

### Method
N/A (C function)

### Endpoint
N/A

### Parameters
- **cpuType** (CpuType) - Required - Target CPU subsystem.

### Request Example
N/A

### Response
#### Success Response
- **CpuInstructionProgress** - Progress information.

#### Response Example
N/A

## GetDebuggerLog

### Description
Gets the debugger log.

### Method
N/A (C function)

### Endpoint
N/A

### Parameters
- **outBuffer** (char*) - Required - Output buffer.
- **maxLength** (uint32_t) - Required - Maximum length to write.

### Request Example
N/A

### Response
#### Success Response
None

#### Response Example
N/A

## UpdateFrozenAddresses

### Description
Updates frozen addresses for a CPU type.

### Method
N/A (C function)

### Endpoint
N/A

### Parameters
- **cpuType** (CpuType) - Required - Target CPU subsystem.
- **start** (uint32_t) - Required - Start address.
- **end** (uint32_t) - Required - End address.
- **freeze** (bool) - Required - Whether to freeze or unfreeze.

### Request Example
N/A

### Response
#### Success Response
None

#### Response Example
N/A

## GetFrozenState

### Description
Gets frozen state for a range of addresses.

### Method
N/A (C function)

### Endpoint
N/A

### Parameters
- **cpuType** (CpuType) - Required - Target CPU subsystem.
- **start** (uint32_t) - Required - Start address.
- **end** (uint32_t) - Required - End address.
- **outState** (bool*) - Required - Output array of frozen states.

### Request Example
N/A

### Response
#### Success Response
None

#### Response Example
N/A
```

--------------------------------

### emu.getScreenSize

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-drawing-api.md

Gets the post-filter output size of the screen.

```APIDOC
## emu.getScreenSize()

### Description
Returns the size of the current renderer output, applying the active video filter.

### Method
Function

### Endpoint
`emu.getScreenSize()`

### Returns
- **width** (Int) - Width of the output.
- **height** (Int) - Height of the output.

### Example
```lua
local size = emu.getScreenSize()
```
```

--------------------------------

### RecordMovieOptions and RecordMovieFrom definitions

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/record-api.md

Options struct and enum for recording input movies. The enum controls whether to start without save data, with save data, or from the current state. The C# interop layout is documented in the comment.

```cpp
// Core/Shared/Movies/MovieManager.h + MovieTypes.h
enum class RecordMovieFrom
{
	StartWithoutSaveData,
	StartWithSaveData,
	CurrentState
};

struct RecordMovieOptions
{
	// C# interop layout (UI/Interop/RecordApi.cs):
	//   byte[2000] Filename; byte[250] Author; byte[10000] Description; RecordMovieFrom RecordFrom;
};
```

--------------------------------

### Example: sum first 16 read counts from NES work RAM

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-memory-api.md

Retrieves read counters for the NES work RAM region, sums the first 16 entries, and logs the total. The counters array is 1-indexed in Lua.

```lua
local counters = emu.getAccessCounters(emu.counterType.readCount, emu.memType.nesWorkRam)
local total = 0
for i = 1, math.min(16, #counters) do total = total + counters[i] end
emu.log("first 16 bytes read count: " .. total)
```

--------------------------------

### Get script data folder with emu.getScriptDataFolder

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-misc-api.md

Returns the per-script writable folder <home>/LuaScriptData/<scriptName>/ (created on demand) when DebugConfig.ScriptAllowIoOsAccess is enabled; otherwise returns an empty string.

```lua
emu.getScriptDataFolder()   -- → String
```

--------------------------------

### Example: log executed bytes from SNES PRG ROM

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-memory-api.md

Fetches CDL data for the SNES PRG ROM region and logs the CDL flag at address 0x8000, indicating whether that byte was executed.

```lua
local cdl = emu.getCdlData(emu.memType.snesPrgRom)
emu.log("executed bytes: " .. cdl[0x8000])
```

--------------------------------

### Read, modify, and set controller input; emulate mouse position

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-input-api.md

Example of reading controller state, modifying it, and writing it back. Also shows setting analog coordinates for mouse/light-gun devices. The input table keys are button names like 'a' and 'b'; numeric entries update coordinates.

```lua
-- read the first controller and force A held for one frame
local input = emu.getInput(0)
if input.a then emu.log("A pressed") end
input.a = true
input.b = true
emu.setInput(input, 0)

-- emulate a mouse/light-gun position on port 0
emu.setInput({ x = 128, y = 120 }, 0)
```

--------------------------------

### C API usage for AVI recording and movie recording

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/record-api.md

C API equivalent of the C# usage example, showing how to initialize RecordAviOptions with an initializer list and call AviRecord/AviStop. The MovieRecord call uses a comment noting that the C-side struct mirrors the C# byte arrays.

```cpp
// Same via C API
RecordAviOptions opt = { VideoCodec::H264, 0, true, false };
AviRecord("run.avi", opt);
AviStop();
MovieRecord(RecordMovieOptions{ /* C# fills byte arrays; C-side struct mirrors them */ });
```

--------------------------------

### C# host InputApi usage examples

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/input-api.md

C# host usage of InputApi for key simulation, mouse control, controller presence, lag counter reset, and querying pressed keys. The same calls from Lua use emu.isKeyPressed(keyName), emu.getMouseState(), and emu.getInput(port, subPort).

```csharp
// C# host: simulate a key press and let shortcuts react
InputApi.SetKeyState(InputApi.GetKeyCode("Enter"), true);
InputApi.SetKeyState(InputApi.GetKeyCode("Enter"), false);

// C# host: mouse
InputApi.SetMousePosition(128.0, 120.0);
InputApi.SetMouseMovement(0, 0);
SystemMouseState state = InputApi.GetSystemMouseState(rendererHandle);
bool captured = InputApi.CaptureMouse(0, 0, 256, 240, rendererHandle);
InputApi.ReleaseMouse();

// C# host: controller presence + HUD lag counter
bool hasNesPad = InputApi.HasControlDevice(ControllerType.NesController);
InputApi.ResetLagCounter();

// C# host: query the paused key set
UInt16[] keys = new UInt16[3];
InputApi.GetPressedKeys(keys);
```

--------------------------------

### Export save state and movie from history

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/history-api.md

C# example that exports a save state at position 1200 and an input movie from position 0 to 2400 using the history viewer API. Returns boolean success flags.

```csharp
// Export a save state and an input movie from history
bool okSave = HistoryApi.HistoryViewerCreateSaveState("rewind.sav", 1200);
bool okMovie = HistoryApi.HistoryViewerSaveMovie("rewind.movie", 0, 2400);
```

--------------------------------

### emu.getDrawSurfaceSize

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-drawing-api.md

Gets the dimensions and overscan of a draw surface.

```APIDOC
## emu.getDrawSurfaceSize(surface)

### Description
Returns the size and overscan information for a draw surface. The `surface` parameter defaults to the currently selected surface.

### Method
Function

### Endpoint
`emu.getDrawSurfaceSize(surface)`

### Parameters
- **surface** (optional) - The surface to query. Defaults to the currently selected surface.

### Returns
- **width** (Int) - Width of the surface.
- **height** (Int) - Height of the surface.
- **visibleWidth** (Int) - Visible width.
- **visibleHeight** (Int) - Visible height.
- **overscan** (table) - Sub-table with `top`, `bottom`, `left`, `right` values. Only present for `consoleScreen`.
```

--------------------------------

### emu.getPixel

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-drawing-api.md

Gets the RGB value of a pixel at specified coordinates.

```APIDOC
## emu.getPixel(x, y)

### Description
Returns the 24-bit RGB value of the pixel at the given coordinates in the rendered frame. Errors with `"invalid x,y coordinates"` when the coordinates are outside the screen size.

### Method
Function

### Endpoint
`emu.getPixel(x, y)`

### Parameters
- **x** (Int) - Required - X coordinate.
- **y** (Int) - Required - Y coordinate.

### Returns
- **Int** - RGB pixel value.

### Example
```lua
local size = emu.getScreenSize()
local ok, color = pcall(emu.getPixel, size.width, size.height)  -- out of bounds → error
```
```

--------------------------------

### Save screenshot to disk with io.open

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-misc-api.md

Writes the screenshot PNG to disk using an io library. Requires DebugConfig.ScriptAllowIoOsAccess to be enabled.

```lua
local png = emu.takeScreenshot()
local f = assert(io.open(emu.getScriptDataFolder() .. "/shot.png", "wb"))
f:write(png)
f:close()
```

--------------------------------

### Emulator State Table Functions

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-emulation-api.md

Functions to get and set the full emulator state as a Lua table.

```APIDOC
## emu.getState()

### Description
Returns a table representing the current emulator state, including console-specific fields and augmented metadata.

### Method
Lua function

### Signature
`emu.getState()`

### Parameters
None

### Returns
- **Table** - Contains the following keys:
  - `clockRate` (Int)
  - `consoleType` (String, e.g., `"Snes"`, `"Nes"`)
  - `region` (String, from `ConsoleRegion` enum name)
  - `frameCount` (Int)
  - `masterClock` (Int)
  - Plus every console-derived key (per-console RAM content, registers, etc., keyed by the console's `ISerializable` fields).

### Example
```lua
local state = emu.getState()
emu.log(state.consoleType .. " frame " .. state.frameCount)
```

---

## emu.setState(state)

### Description
Sets the emulator state from a table. Partial tables are allowed; missing keys keep their current value. Non-scalar values are ignored.

### Method
Lua function

### Signature
`emu.setState(state)`

### Parameters
- **state** (Table) - Required - Table containing state fields. Only `Integer`/`Double`/`Bool` values are used; string keys; other values ignored.

### Errors
Raises a Lua error if the argument is not a table (via `luaL_checktype`).

### Example
```lua
local state = emu.getState()
state.frameCount = 0            -- any serializable console field may be edited
emu.setState(state)
```

```lua
local ok, err = pcall(emu.setState, { bad = "value" })  -- non-table → error raised
```
```

--------------------------------

### emu.getLogWindowLog()

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-misc-api.md

Returns the entire emulator log as a string.

```APIDOC
## emu.getLogWindowLog()

### Description
Returns the entire emulator log as a string.

### Function Signature
`emu.getLogWindowLog()`

### Parameters
None.

### Returns
- **String** - The full emulator log.

### Example
```lua
local fullLog = emu.getLogWindowLog()
```
```

--------------------------------

### HistoryViewerInitialize

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/history-api.md

Initializes the history viewer with a dedicated emulator instance for replaying history.

```APIDOC
## HistoryViewerInitialize

### Description
Creates a dedicated emulator instance for the history viewer, copies settings from the live emulator, and initializes the viewer. On failure, releases resources and returns.

### Method
Function

### Endpoint
HistoryViewerInitialize(void* windowHandle, void* viewerHandle)

### Parameters
#### Parameters
- **windowHandle** (void*) - Required - Handle to the window for rendering.
- **viewerHandle** (void*) - Required - Handle to the viewer control.

### Response
#### Success Response
No return value.

#### Response Example
```cpp
HistoryViewerInitialize(windowPtr, viewerPtr);
```
```

--------------------------------

### Netplay C API declarations (StartServer, Connect, NetPlayGetControllerList)

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/netplay-api.md

Exported C API for netplay operations. StartServer binds a TCP listener; empty password disables authentication. Connect fills ClientConnectionData and connects; spectator mode joins without controlling a port. Controller functions delegate to GameServer or GameClient depending on role.

```cpp
void     StartServer(uint16_t port, char* password);
void     StopServer();
bool     IsServerRunning();

void     Connect(char* host, uint16_t port, char* password, bool spectator);
void     Disconnect();
bool     IsConnected();

void     NetPlayGetControllerList(NetplayControllerUsageInfo* list, int32_t& length);
void     NetPlaySelectController(NetplayControllerInfo controller);
NetplayControllerInfo NetPlayGetControllerPort();
```

--------------------------------

### Emulation control: reset, stop, breakExecution, resume, step, rewind

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-emulation-api.md

Core emulation control functions. `reset`, `breakExecution`, `resume`, `step` require an initialized script (must be called from a registered callback). `stop` accepts an optional exit code (default 0) and stores it via `Emulator::SetStopCode`. `step` requires `count >= 1`, defaults `stepType` to `step` and `cpuType` to the script's default CPU; `rewind` requires `seconds >= 1` and an exec-callback context.

```lua
emu.reset()                  -- reset the console (via SystemActionManager::Reset)
emu.stop(exitCode)           -- stop emulation with an optional exit code
emu.breakExecution()         -- pause: single-step the default CPU once (StepType::Step)
emu.resume()                 -- resume execution (Debugger::Run)
emu.step(count, stepType, cpuType)
emu.rewind(seconds)
```

--------------------------------

### emu.getRomInfo()

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-misc-api.md

Returns a table with ROM file name, path, and SHA-1 hash.

```APIDOC
## emu.getRomInfo()

### Description
Returns a table with ROM file name, path, and SHA-1 hash.

### Function Signature
`emu.getRomInfo()`

### Parameters
None.

### Returns
- **table** - Object with fields:
  - `name` (String) - ROM file name.
  - `path` (String) - ROM file path.
  - `fileSha1Hash` (String) - SHA-1 hash of the file.

### Example
```lua
local rom = emu.getRomInfo()
emu.log("running " .. rom.name)
```
```

--------------------------------

### Get memory size with emu.getMemorySize

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-memory-api.md

Returns the size in bytes of the specified memory region. Errors: "invalid memory type".

```lua
emu.getMemorySize(memoryType)   -- → Int
```

--------------------------------

### Log when Space key is held using emu.isKeyPressed

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-input-api.md

Example usage of emu.isKeyPressed to log when the Space key is held. The condition is true while the key is pressed.

```lua
if emu.isKeyPressed("Space") then
    emu.log("space held")
end
```

--------------------------------

### NetPlayGetControllerPort

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/netplay-api.md

Gets the currently selected controller port for netplay. On the host, returns the host controller port; on a guest, returns the client's controller port.

```APIDOC
## NetPlayGetControllerPort

### Description
Gets the currently selected controller port for netplay. On the host, returns the host controller port; on a guest, returns the client's controller port.

### Method
NetPlayGetControllerPort

### Endpoint
NetPlayGetControllerPort()

### Parameters
None.

### Response
- **NetplayControllerInfo** - The currently selected controller port.
```

--------------------------------

### Convert SNES work RAM address example

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-memory-api.md

Converts a SNES work RAM address to an absolute address and logs the result if conversion succeeds. Uses emu.memType.snesWorkRam and emu.cpuType.snes.

```lua
local abs = emu.convertAddress(0x7E2000, emu.memType.snesWorkRam, emu.cpuType.snes)
if abs then emu.log(string.format("prg=%06X", abs.address)) end
```

--------------------------------

### Draw pixel at mouse position when left button pressed

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-input-api.md

Example of using emu.getMouseState to draw a pixel at the mouse position when the left button is pressed. Uses emu.drawPixel with the returned coordinates.

```lua
local m = emu.getMouseState()
if m.left then emu.drawPixel(m.x, m.y, 0xFFFFFFFF, 1) end
```

--------------------------------

### Get mouse state with emu.getMouseState

Source: https://github.com/sourmesen/mesen2/blob/master/_autodocs/api-reference/lua-input-api.md

Function signature for emu.getMouseState. Returns a table with absolute coordinates (x, y), relative movement (relativeX, relativeY), and button states (left, middle, right). No parameters and no errors.

```lua
emu.getMouseState()   -- → { x=Int, y=Int, relativeX=Double, relativeY=Double, left=Bool, middle=Bool, right=Bool }
```
Tokens:
Raw