Mupen64

Lua Scripting

stablenightly

API Definition Setup

To get started with Lua scripting in Mupen64, you should set up your project to use the API definitions.

You can find the API definitions as api.lua in the repack.

  1. Create a ./lib directory at the root of your project
  2. Copy api.lua into ./lib
  3. Add lib to workspace.library in your .luarc config at the root of your project

Most IDEs should now automatically recognize the API definitions and provide code completion and type checking.

It's not necessary to require or dofile the API definitions in your scripts; Mupen has its own internal copy that's automatically loaded.

Make sure to update the api.lua file in your ./lib directory whenever you update Mupen64.

Migration Guides

Mupen.result changed (breaking)

Mupen.result has been updated with new enum values. Update your code accordingly.

painter API and d2d deprecation

The d2d API has been deprecated in favor of the new painter API.

The painter API is inspired by JS canvas and provides more modern drawing and text capabilities.

See the API reference for more details.

emu.atkey with keycode2

emu.atkey reports the deprecated Windows virtual keycode in args.keycode and the SDL keycode in args.keycode2 when an SDL equivalent exists.

Existing scripts that use args.keycode with Mupen.VKeycodes continue to work. Scripts that migrated to SDL keycodes should use args.keycode2 instead:

 emu.atkey(function(args)
-    if args.keycode == Mupen.keycode.SDLK_SPACE then
+    if args.keycode2 == Mupen.keycode.SDLK_SPACE then
         toggle_pause()
     end
 end)

args.keycode and args.keycode2 can be nil for character-only events. args.keycode2 can also be nil when the Windows virtual keycode has no SDL equivalent.

hotkey.prompt with two return values

hotkey.prompt returns a deprecated LegacyHotkey with the old key field first, and a modern Hotkey with the trigger field second

Existing scripts that capture only one result continue to receive the legacy value, but new scripts should use the second result.

local legacy_hotkey, hotkey = hotkey.prompt("Choose a hotkey")
- if legacy_hotkey.key == Mupen.VKeycodes.VK_P then
+ if hotkey.trigger.type == "keycode" and hotkey.trigger.value == Mupen.keycode.SDLK_P then

input.get_key_name_text deprecated

input.get_key_name_text is deprecated and remains a Windows-specific API.

local key_name = input.get_key_name_text(Mupen.VKeycodes.VK_DOWN)

Keycodes and mouse-button flags

New scripts should use Mupen.keycode values instead of Mupen.VKeycodes:

- local key = Mupen.VKeycodes.VK_RETURN
+ local key = Mupen.keycode.SDLK_RETURN

For SDL mouse-button bitmasks, use Mupen.mousebutton:

-local left = 0x01
+local left = Mupen.mousebutton.SDL_BUTTON_LMASK

Available masks are SDL_BUTTON_LMASK, SDL_BUTTON_MMASK, SDL_BUTTON_RMASK, SDL_BUTTON_X1MASK, and SDL_BUTTON_X2MASK.

The old enum is still available, but deprecated.

action.associate_hotkey

action.associate_hotkey still accepts a legacy key field, but it is deprecated and should be migrated to the modern trigger field. The two fields are mutually exclusive:

 action.associate_hotkey("Movie > Pause", {
-    key = Mupen.VKeycodes.VK_P,
+    trigger = { type = "keycode", value = Mupen.keycode.SDLK_P },
     ctrl = true,
 }, true)