Mupen64Plus v2.0 Core API v1.0

Please note: as of January 2011, this API is a work in progress.
The core Mupen64Plus v2.0 modules are complete, but work on GUI front-end applications is ongoing.

To view the design proposal which preceded this API definition, go to Design Proposal 3.

New Architecture

Earlier versions of Mupen64Plus (and other plugin-based N64 emulators) used a single monolithic application (containing the emulator core) and four plugins. The plugins were dynamically-loaded libraries, and the application used one plugin of each type: Video, Audio, Input, and RSP. Each plugin and the application contained its own GUI code for user interface, and each plugin and the application were individually responsible for finding their own data files and finding, loading, parsing, and storing their own configuration data files.

This was an acceptable architecture for emulators which were only designed to run on a single platform (such as Windows), but causes a lot of developer and user headaches when applied to a cross-platform emulator such as Mupen64Plus. For this reason, we are re-designing the layout of the emulator to solve some of the problems caused by the old architecture.

Under the new architecture, the old monolithic emulator application is split into two parts: a core emulator library and a main application, called the front-end. The front-end is primarily responsible for the user interface. All GUI code will be removed from the core and plugin libraries. The primary function of the core library is to emulate the R4300 CPU and memory system, attaching the plugins to form a full N64 system emulator. The core library also contains some utility functions which may be used by the front-end and plugins, such as a configuration parameter handler.

High-level Usage

The expected sequence of operations which will be taken by the front-end application are as follows:

1. Load core library (libmupen64plus.so) and set function pointers
2. Call CoreGetVersion, check core version and capabilities
3. Call CoreStartup to initialize the core library
4. Load front-end configuration from core config API or through own mechanism
5. Find plugins, open dynamic libraries, call PluginStartup for each
6. Enter message loop for user interaction
7. If user selects ROM and presses Play:
   • Load and de-compress the ROM
   • Use CoreDoCommand to open the ROM
   • Call CoreAttachPlugin to attach selected plugins to core
   • Use CoreDoCommand to start emulation
   • When emulation is finished, call CoreDetachPlugin on all plugins, then close the ROM

Versioning

API Versioning Scheme

Since the Mupen64Plus emulator comprises 6 different software modules which can be mixed and matched (the front-end app, the core library, and 4 plugins), and the interfaces between these modules change over time, there are many hard-to-diagnose bugs which could show up due to incompatibilities between these different modules. For this reason, we use a comprehensive versioning scheme which allows any 2 components to determine whether or not they are compatible, and to support forward and backward compatibility as necessary. This scheme is described in detail in this document.

Core API

Basic Core Functions

These two functions (PluginGetVersion and CoreErrorMessage) are utility functions and may be called at any time (even before core startup). These functions are used by both the front-end and the plugins.

Front-End Functions

There are several types of functions here, which are exported from the Core library to be used by the front-end. There are 'housekeeping' functions, for startup and shutdown, and attaching and detaching plugins. There is also a Command API which is used for many simple functions such as loading, executing, or stopping a ROM. Finally the Cheat API is here, for adding and removing cheat functions.

Video Extension API

These functions are exported from the Core library for use by the video plugin. These functions are used for high-level video setup tasks such as enumerating available screen resolutions, setting the video mode, window caption, OpenGL attributes, and fullscreen mode. The video extension API allows for the abstraction of these functions away from the hard-coded SDL function calls currently in the video plugins, so that a front-end may override these functions and provide its own video API.

Debugger Functions

These are the debugger functions, which are also called only from the front-end. Most of these functions will return with an error if the core library was not compiled with the debugger enabled. A front-end may examine the Capabilities value returned by the CoreGetVersion function to determine if the core library was built with the debugger enabled.

Configuration API

These configuration functions are exported from the core library and are used by the core and the plugins to store all of their persistent configuration parameters. The front-end application may also use these functions to store its configuration options, or it may use a different mechanism. This section also contains two Operating System Abstraction functions. These functions are used by the core, plugins, and the front-end to find full filepaths to shared data files and user-specific data files.

Plugin API

Plugin API

This section lists all of the functions which are exported by the plugins. The front-end application should only use the PluginStartup, PluginShutdown, and PluginGetVersion functions. All other functions will only be called from the core.

Netplay

Starting with version 2.6, Mupen64Plus has support for playing games with multiple players over a network. To support this, a few new command types were added to the CoreDoCommand function, as documented in front-end functions. The core handles the network I/O on its own, and the interface for handling netplay from the perspective of the front-end is very high level. The design of the netplay feature is such that a separate piece of server software (not part of Mupen64Plus) is also required. An example of such a server program is available here from loganmc10 on github. A description of the network protocol which is used for communication between the client emulators and the netplay server is available here.