Mupen64Plus v2.0 Core Front-End

Mupen64Plus v2.0 API

Mupen64Plus v2.0 Core<-->Front-End API

Most libmupen64plus functions return an m64p_error return code, which is an enumerated type defined in m64p_types.h. Front-end code should check the return value of each call to a libmupen64plus function.

Startup/Shutdown Functions

Prototype	m64p_error CoreStartup(int APIVersion, const char *ConfigPath, const char *DataPath, void *Context, void (*DebugCallback)(void *Context, int level, const char *message), void *Context2, void (*StateCallback)(void *Context2, m64p_core_param ParamChanged, int NewValue))
Input Parameters	APIVersion Integer containing the version number of the Core API used by the front-end. ConfigPath File path to folder containing Mupen64Plus.cfg. Can be NULL. DataPath Folder to search first when looking for shared data files. Can be NULL. Context Pointer which will be passed back to the DebugCallback function. Can be NULL. DebugCallback Pointer to function in front-end for receiving debug information and warnings from the core. This function must be thread-safe. Can be NULL. The value of level is 1 for an error, 2 for a warning, 3 for info, and 4 for verbose info. Context2 Pointer which will be passed back to the StateCallback function. Can be NULL. StateCallback Pointer to function in front-end for receiving core state change notifications. This function must be thread-safe. Can be NULL.
Requirements	This function must be called before any other libmupen64plus functions.
Usage	This function initializes libmupen64plus for use by allocating memory, creating data structures, and loading the configuration file. If ConfigPath is NULL, libmupen64plus will search for the configuration file in its usual place (On Linux, in ~/.config/mupen64plus/). This function may return M64ERR_INCOMPATIBLE if older front-end is used with newer core.

Prototype	m64p_error CoreShutdown(void)
Input Parameters	N/A
Usage	This function saves the configuration file, then destroys data structures and releases memory allocated by the core library.

Prototype	m64p_error CoreAttachPlugin(m64p_plugin_type PluginType, m64p_dynlib_handle PluginLibHandle)
Input Parameters	PluginType Enumerated type specifying the plugin type to attach to the core. If this type of plugin is currently attached to the core, an error will be returned. PluginLibHandle Dynamic library handle (defined in m64p_types.h) corresponding with the plugin object to attach.
Requirements	Both the core library and the plugin library must already be initialized with the CoreStartup()/PluginStartup() functions, and a ROM must be open. This function cannot be called while the emulator is running. The plugins must be attached in the following order: Video, Audio, Input, RSP.
Usage	This function attaches the given plugin to the emulator core. There can only be one plugin of each type attached to the core at any given time.

Prototype	m64p_error CoreDetachPlugin(m64p_plugin_type PluginType)
Input Parameters	PluginType Enumerated type specifying the plugin type to detach from the core. If no plugin of this type is currently attached to the core, this function will exit with a return value of M64ERR_SUCCESS.
Requirements	Both the core library and the plugin library must already be initialized with the CoreStartup()/PluginStartup() functions. This function cannot be called while the emulator is running.
Usage	This function detaches the given plugin from the emulator core, and re-attaches the 'dummy' plugin functions.

Command Functions

Prototype	m64p_error CoreDoCommand(m64p_command Command, int ParamInt, void *ParamPtr)
Input Parameters	Command Enumerated type specifying which command should be executed. ParamInt An integer value which may be used as an input to the command. ParamPtr A pointer which may be used as an input to the command.
Requirements	The core library must already be initialized with the CoreStartup() function. Each command may have its own requirements as well.
Usage	This function sends a command to the emulator core. A table of all commands is given below.

Command	Function	Input Parameters	Requirements
M64CMD_ROM_OPEN	This will cause the core to read in a binary ROM image provided by the front-end.	ParamPtr Pointer to the uncompressed ROM image in memory. ParamInt The size in bytes of the ROM image.	The emulator cannot be currently running. A ROM image must not be currently opened.
M64CMD_ROM_CLOSE	This will close any currently open ROM. The current cheat code list will also be deleted.	N/A	The emulator cannot be currently running. A ROM image must have been previously opened. There should be no plugins currently attached.
M64CMD_ROM_GET_HEADER	This will retrieve the header data of the currently open ROM.	ParamPtr Pointer to a rom_header struct to receive the data. ParamInt The size in bytes of the rom_header struct.	A ROM image must be open.
M64CMD_ROM_GET_SETTINGS	This will retrieve the settings data of the currently open ROM.	ParamPtr Pointer to a rom_settings struct to receive the data. ParamInt The size in bytes of the rom_settings struct.	A ROM image must be open.
M64CMD_EXECUTE	This command will start the emulator and begin executing the ROM image. This function call will not return until the game has been stopped.	N/A	The emulator cannot be currently running. A ROM image must have been previously opened.
M64CMD_STOP	This will stop the emulator, if it is currently running.	N/A	This command will execute asynchronously.
M64CMD_PAUSE	This command will pause the emulator if it is running.	N/A	This function will return a non-successful error code if the emulator is in the stopped state. This command may execute asynchronously.
M64CMD_RESUME	This command will resume execution of the emulator if it is paused.	N/A	This function will return a non-successful error code if the emulator is in the stopped state. This command may execute asynchronously.
M64CMD_CORE_STATE_QUERY	This command will query the emulator core for the value of a state parameter	ParamInt An m64p_core_param enumerated type specifying the desired state variable ParamPtr Pointer to an integer to receive the value of the requested state variable.	None
M64CMD_CORE_STATE_SET	This command will set the value of a state parameter in the emulator core	ParamInt An m64p_core_param enumerated type specifying the desired state variable ParamPtr Pointer to an integer to containing the value of the requested state variable.	The initial requirements vary depending upon the variable being set. Setting some variables requires the emulator to be running.
M64CMD_STATE_LOAD	This command will attempt to load a saved state file. If ParamPtr is not NULL, this function will load a state file from a full pathname specified by this pointer. Otherwise (ParamPtr is NULL), it will load from the current slot.	ParamInt Ignored ParamPtr Pointer to string containing state file path and name, or NULL	The emulator must be currently running or paused. This command will execute asynchronously.
M64CMD_STATE_SAVE	This command will save a state file. If ParamPtr is not NULL, this function will save a state file to a full pathname specified by this pointer. Otherwise (ParamPtr is NULL), it will save to the current slot.	ParamInt This parameter will only be used if ParamPtr is not NULL. If 1, a Mupen64Plus state file will be saved. If 2, a Project64 compressed state file will be saved. If 3, a Project64 uncompressed state file will be saved. ParamPtr Pointer to string containing state file path and name, or NULL	The emulator must be currently running or paused. This command will execute asynchronously.
M64CMD_STATE_SET_SLOT	This command will set the currently selected save slot index	ParamInt Value to set for the current slot index. Must be between 0 and 9 ParamPtr Ignored	None
M64CMD_SEND_SDL_KEYDOWN	This command will inject an SDL_KEYDOWN event into the emulator's core event loop. Keys not handled by the core will be passed to the input plugin.	ParamInt Key value of the keypress event to inject, with SDLMod in the upper 16 bits and SDLKey in the lower 16 bits.	The emulator must be currently running or paused.
M64CMD_SEND_SDL_KEYUP	This command will inject an SDL_KEYUP event into the emulator's core event loop.	ParamInt Key value of the keypress event to inject, with SDLMod in the upper 16 bits and SDLKey in the lower 16 bits.	The emulator must be currently running or paused.
M64CMD_SET_FRAME_CALLBACK	This command either registers or removes (if ParamPtr is NULL) a frame callback function. This function will be called after each video frame is rendered. The front-end callback function may call the video plugin's ReadScreen2() function to retrieve the frame if desired.	ParamPtr Can be either NULL or a m64p_frame_callback object.	None
M64CMD_TAKE_NEXT_SCREENSHOT	This will cause the core to save a screenshot at the next possible opportunity.	N/A	The emulator must be currently running or paused. This command will execute asynchronously.
M64CMD_READ_SCREEN	This command will copy the current contents of the video display to the buffer pointer by ParamPtr.	ParamInt 1 to copy the buffer that is currently displayed (front buffer), 0 to copy the buffer that is being drawn (back buffer). ParamPtrA pointer to a buffer of at least width*height*3 bytes. The buffer will be filled with the current display. The format is RGB888 with the origin in the lower left corner.	The emulator must be currently running or paused.
M64CMD_RESET	Reset the emulated machine.	ParamInt 0 to do a soft reset, 1 to do a hard reset. ParamPtr Ignored	The emulator must be currently running or paused.
M64CMD_ADVANCE_FRAME	Advance one frame (the emulator will run until the next frame, then pause).	ParamInt Ignored ParamPtr Ignored	The emulator must be currently running or paused.
M64CMD_SET_MEDIA_LOADER	This command allow frontends to register their media (such as GameBoy cartridge or 64DD disk) loading functions. These functions will be called appropriately by the core at startup and when a new media is inserted.	ParamInt must be sizeof(m64p_media_loader). ParamPtr A pointer to the m64p_media_loader to register, cannot be NULL.	None
M64CMD_NETPLAY_INIT	This command will initilize the netplay subsystem. It will also attempt to make an initial connection to the netplay server. Returns M64ERR_SYSTEM_FAIL on failure, M64ERR_SUCCESS on success.	ParamInt This is the port number the netplay server is listening on. ParamPtr This is a string containing the IP or hostname of the netplay server.	Emulator should be stopped.
M64CMD_NETPLAY_CONTROL_PLAYER	This function is used for the client to request control of certain players. This function can be called more than once if a client would like to control multiple players. Local controllers are assigned in order. Returns M64ERR_INPUT_ASSERT if the server rejects the request. If this function is never called, the client is assumed to be a spectator.	ParamInt This is the player number (from 1-4) the client would like to control. ParamPtr This is a pointer to a uint32_t that contains a unique registration ID (for instance a random number) for the client. This number should be the same each time if this function is called multiple times. The registration ID cannot be 0.	Emulator should be stopped. The input plugin should be started.
M64CMD_NETPLAY_GET_VERSION	This function is used to check API and core versions, the server can use this information to make sure everyone is using the same version of the software. The function returns M64ERR_INCOMPATIBLE if the API versions don't match, and M64ERR_SUCCESS if they do.	ParamInt This is the Netplay API version that the frontend supports. ParamPtr This is a pointer to a uint32_t, the core fills this pointer with a core netplay version. This version number is incremented when changes are made to the core that would affect netplay sync.	None
M64CMD_NETPLAY_CLOSE	Closes the netplay subsystem, as well as any connections to the netplay server.	N/A	None

Core State Parameters

These core parameters may be read and/or written using the M64CMD_CORE_STATE_QUERY and M64CMD_CORE_STATE_SET commands. The front-end application will receive a callback (via the StateCallback function pointer given to the CoreStartup function) when these parameters change value. This callback will be sent even if the function which caused the state change was called by the front-end application itself. Not all of these parameters are readable or writable. Each parameter's value is held in a single 32-bit integer. The meaning of this integer is given in the Parameter Encoding column. See the table below for details on these core parameters.

Name	Readable	Writable	int Parameter Encoding	Notes
M64CORE_EMU_STATE	Yes	Yes	enum m64p_emu_state	1=Stopped, 2=Running, 3=Paused
M64CORE_VIDEO_MODE	Yes	Yes	enum m64p_video_mode	1=None (video not running), 2=Windowed, 3=Fullscreen
M64CORE_SAVESTATE_SLOT	Yes	Yes		Valid values are 0 through 9.
M64CORE_SPEED_FACTOR	Yes	Yes	Emulator playback speed in percent	Valid values are 1 to 1000.
M64CORE_SPEED_LIMITER	Yes	Yes	1 to enable speed limiter, or 0 to disable speed limiter.	When speed limiter is disabled, emulator will run as fast as possible (useful for benchmarking).
M64CORE_VIDEO_SIZE	Yes	Yes	(ScreenWidth << 16) + ScreenHeight	This parameter can only be read or written when the emulator is running or paused. This parameter may be written by the front-end application in response to a window resizing event. Upon receiving this command, the core will pass the new width and height to the ResizeVideoOutput function in the video plugin (video API v2.2.0). If the video plugin supports resizing, it will update its viewport and then call the video extension function VidExt_ResizeWindow to update the window manager.
M64CORE_AUDIO_VOLUME	Yes	Yes	Volume level in percent, 0 - 100
M64CORE_AUDIO_MUTE	Yes	Yes	1 if muted, otherwise 0
M64CORE_INPUT_GAMESHARK	Yes	Yes	1 when Gameshark button pressed, 0 when button released.	Callback function will be invoked on both button press and release.
M64CORE_STATE_LOADCOMPLETE	No	No	1 if state loading was successful, 0 if state loading failed.	This parameter cannot be read or written. It is only used for callbacks, because the state load/save operations are asynchronous.
M64CORE_STATE_SAVECOMPLETE	No	No	1 if state saving was successful, 0 if state saving failed.	This parameter cannot be read or written. It is only used for callbacks, because the state load/save operations are asynchronous.

ROM Handling Functions

Prototype	m64p_error CoreGetRomSettings(m64p_rom_settings *RomSettings, int RomSettingsLength, int Crc1, int Crc2)
Input Parameters	RomSettings Pointer to m64p_rom_settings object to be filled in with data. RomSettingsLength Size of the object pointed to by RomSettings in bytes. Crc1 A 32-bit integer value containing the first CRC (taken from the ROM header) to identify the ROM. Crc2 A 32-bit integer value containing the second CRC (taken from the ROM header) to identify the ROM.
Requirements	The core library must already be initialized with the CoreStartup() function. The RomSettings pointer must not be NULL. The RomSettingsLength value must be greater than or equal to the size of the m64p_rom_settings structure. This function does not require any ROM image to be currently open.
Usage	This function searches through the data in the Mupen64Plus.ini file to find an entry which matches the given Crc1 and Crc2 hashes, and if found, fills in the RomSettings structure with the data from the Mupen64Plus.ini file.

Video Extension Functions

Prototype	m64p_error CoreOverrideVidExt(m64p_video_extension_functions *VideoFunctionStruct);
Input Parameters	VideoFunctionStruct Pointer to a structure (defined in m64p_types.h) containing pointers to the Front-end's custom Video Extension functions to override the default SDL functions
Requirements	The Mupen64Plus library must already be initialized before calling this function. This function cannot be called while the emulator is running.
Usage	This function overrides the core's internal SDL-based OpenGL functions which are called from the video plugin to perform various basic tasks like opening the video window, toggling between windowed and fullscreen modes, and swapping frame buffers after a frame has been rendered. This override functionality allows a front-end to define its own video extension functions to be used instead of the SDL functions, such as for the purpose of embedding the emulator display window inside of a Qt GUI window. If any of the function pointers in the structure are NULL, the override function will be disabled and the core's internal SDL functions will be used. The core library with a Video Extension API v3.0 expects the Functions struct member to be equal to 11 or more.

Cheat Functions

Prototype	m64p_error CoreAddCheat(const char *CheatName, m64p_cheat_code *CodeList, int NumCodes)
Input Parameters	CheatName Pointer to NULL-terminated string containing a unique name for this Cheat Function. CodeList Pointer to an array of m64p_cheat_code objects. NumCodes Number of m64p_cheat_code elements in the cheat code array.
Requirements	The Mupen64Plus library must already be initialized before calling this function. A ROM image must be currently opened.
Usage	This function will add a Cheat Function to a list of currently active cheats which are applied to the open ROM, and set its state to Enabled. This function may be called before a ROM begins execution or while a ROM is currently running. Some cheat codes must be applied before the ROM begins executing, and may not work correctly if added after the ROM begins execution. A Cheat Function consists of a list of one or more m64p_cheat_code elements. If a Cheat Function with the given CheatName already exists, it will be removed and the new Cheat Function will be added in its place.

Prototype	m64p_error CoreCheatEnabled(const char *CheatName, int Enabled)
Input Parameters	CheatName Pointer to NULL-terminated string containing the name of an existing Cheat Function. Enabled Boolean value to which to set the enabled state of the specified Cheat Function.
Requirements	The Mupen64Plus library must already be initialized before calling this function. A ROM image must be currently opened.
Usage	This function enables or disables a specified Cheat Function.