Ikemen GO is written in Go. On top of the engine code, it uses Lua as an embedded scripting language. Lua scripts make it possible to adjust parts of the application after the engine has been built, without recompiling it.

Lua is used for, among other things:

• logic for screens outside the fight, including screenpack/menu flow;
• game mode flow, such as deciding who enters a match and what happens after the match result;
• features around match flow, such as continue screens, pause menus and post-match screens;
• game configuration and helper logic exposed to screenpacks, modules and custom mode scripts.

Default Lua scripts are available in external/script. These files are updated and expanded between engine versions. Editing them directly is usually not recommended for normal engine users, because local changes may conflict with future updates. Direct edits are mainly useful for full-game authors who intentionally maintain their own script branch.

For most extensions, prefer one of the supported external Lua entry points documented on this page:

• Arcade Paths / Story Mode arcs, for custom arcade and story progression;
• Content unlocking, for Lua conditions in select.def and screenpack menus;
• External modules, for loading standalone Lua files without editing default scripts;
• Hooks, for attaching module code to selected points in the default scripts.

This page does not teach the Lua language itself. For Lua syntax and general programming concepts, refer to the Lua 5.1 reference manual or beginner tutorials such as Lua tutorial basics and Tutorialspoint Lua.

By default, Mugen and Ikemen GO provide a classic arcade mode with relatively simple progression. This is enough for traditional arcade paths, such as fighting a number of random opponents and then a boss, but it gives limited control over special cases. Standard arcade setup is mostly restricted to select.def character parameters, opponent order, maxmatches-style settings and fixed team-mode behavior.

Arcade Paths / Story Mode arcs let authors write progression logic in Lua. This makes it possible to create:

• character-specific arcade routes;
• rival battles;
• hidden bosses;
• branching paths;
• forced single, simul, tag or turns battles in the same run;
• custom storyboards before, between or after matches;
• selectable Story Mode arcs where the author decides exactly who the player controls and who they fight.

Functionality-wise, this makes external front ends such as Mugen Story Mode unnecessary for this use case.

Arcade paths and Story Mode arcs use the same Lua helper functions. The practical difference is how the mode starts.

In an arcade path, the player normally chooses a character, team mode and team size on the select screen. Because of that, launchFight{} can often use default values for the player side.

In Story Mode, there is no normal select screen. There is no default player character, team mode, team size, or character switching after continue. For that reason, Story Mode scripts should usually define the player side explicitly with launchFight arguments such as p1char, p1teammode and p1numchars, just like they define the opponent side.

Custom arcade paths can be assigned in either of these ways:

• in a character DEF file, under the [Arcade] section, with a path relative to the character folder;
• in select.def, as a character parameter, with a path relative to the game folder.

Format:

arcadepath = path_to_lua_file

Story Mode arcs are assigned in select.def, under the [StoryMode] section. Refer to the select.def distributed with the engine for a working example and the available parameters.

The following example recreates a simple Mugen-style arcade order: an intro storyboard, six random order-1 fights, one order-2 fight, one order-3 fight, then an ending storyboard.

launchStoryboard('chars/kfm/intro.def')

for i = 1, 6 do
	if not launchFight{} then return end
end

if not launchFight{order = 2} then return end
if not launchFight{order = 3, winscreen = true} then return end

launchStoryboard('chars/kfm/ending.def')
setMatchNo(-1)

launchStoryboard starts a storyboard. launchFight starts a match and returns false when the script should stop, for example after losing without continuing or when the mode flow is interrupted.

winscreen = true enables the post-match Win Screen / Results Screen for that fight. In custom arcade paths, use it on the final fight if the route should show that screen before the ending.

setMatchNo(-1) marks the run as cleared. Use it before ending a completed route so that clear-related behavior, such as credits and hiscore appending, can run.

Lua can decide what happens next based on match results or other available data. For example, this code sends the player to a secret boss only if they reached seven consecutive wins. Otherwise, it uses a normal order-3 opponent.

if getConsecutiveWins(1) == 7 then
	if not launchFight{p2char = {"SuaveDude"}} then return end
else
	if not launchFight{order = 3} then return end
end

For simple post-match checks, helper functions and Lua trigger functions are usually enough. For more complicated conditions, such as counting perfect rounds or custom story flags, store the needed data during the fight. This can be done with character variables, fvars, maps, or Lua code executed during the match through the lua argument of launchFight.

Lua trigger functions such as var, fvar and map are listed in the Lua triggers section.

A basic path can work with only a few launchFight calls, but real arcade paths should account for common edge cases.

First, exclude special opponents from random pools when needed. For example, if a rival or boss has the same order as regular characters, they can appear randomly unless excluded:

launchFight{exclude = {"Blanka", "Sakura", "Final Bison"}}

Second, use matchNo() when the script must resume from the correct point. This matters when continuing a run, or when the selected character can change after continue and the new character has a different arcade path. Since the Lua file is read from the beginning, each section should check whether it still applies to the current match number.

Third, always stop the script when launchFight returns false:

if not launchFight{} then return end

Fourth, call setMatchNo(-1) when the route is fully cleared. Without this, the engine will not treat the route as completed.

Fifth, use winscreen = true on the final launchFight if the route should show the post-match Win Screen / Results Screen. Custom arcade paths are controlled by the Lua script, not by arcade.maxmatches.

The following example recreates a Street Fighter Alpha 3-style route for Karin. It includes random opponents, rival fights, a forced simul fight and a final boss. It also supports resuming correctly from the current match number.

if matchNo() == 1 and not continued() then
	launchStoryboard('chars/Karin/intro.def')
end

for i = matchNo(), 4 do
	if not launchFight{exclude = {"Blanka", "Sakura", "Juni", "Juli", "Final Bison"}} then return end
end

if matchNo() == 5 then
	if not launchFight{p2char = {"Blanka"}} then return end
end

for i = matchNo(), 8 do
	if not launchFight{exclude = {"Sakura", "Juni", "Juli", "Final Bison"}} then return end
end

if matchNo() == 9 then
	local ok = launchFight{
		p2char = {"Sakura"},
		exclude = {"Juni", "Juli", "Final Bison"}, -- since single mode is not forced
	}
	if not ok then return end
end

if matchNo() == 10 then
	local ok = launchFight{
		p2char = {"Juni", "Juli"},
		p2numchars = 2, -- prevents extra characters being appended by default team size
		p2teammode = "simul",
	}
	if not ok then return end
end

local ok = launchFight{
	p2char = {"Final Bison"},
	p2teammode = "single",
	winscreen = true,
}
if not ok then return end

launchStoryboard('chars/Karin/ending.def')
setMatchNo(-1)

Although this may look complex at first, most path scripts can be reused between characters with only small changes, such as replacing rival names or mid-bosses.

• Start with a simple linear route, then add branching once the basics work.
• Keep rival and boss names in local tables if several characters share the same route structure.
• Use matchNo() around storyboards and fixed fights so a continued run does not replay cleared events.
• Use exclude to keep bosses, rivals or unlockable characters out of normal random pools.
• Use winscreen = true on the final fight if the route should show the Win Screen / Results Screen.
• For Story Mode arcs, explicitly assign p1char and related p1 options instead of relying on select-screen defaults.
• Use Troubleshooting scripts when testing conditions or match data.

Lua can be used to unlock characters, stages and game modes through optional select.def and screenpack parameters.

Characters hidden with the hidden select.def parameter can be unlocked with an unlock parameter on the same line.

Everything after unlock = is treated as Lua code. Because of that, unlock must be the last parameter in the line. The code is executed each time the mode is initiated and when returning to the main menu. It should return a boolean value.

If the code returns true, the hidden character becomes selectable. If the character was previously unlocked but the condition later returns false, the character becomes locked again.

When the game starts, data from saves/stats.json is loaded into a Lua table named stats. The following condition unlocks a character after arcade mode has been cleared at least once:

stats.modes ~= nil and stats.modes.arcade ~= nil and stats.modes.arcade.clear >= 1

The table checks are needed because reading a missing subtable would produce a Lua error.

This condition makes a character available in all modes except bossrush:

gameMode() ~= "bossrush"

Online play sends only inputs, so both players should generally have the same select screen. For that reason, it is recommended to make hidden characters and stages available during netplay:

(--[[ normal unlock condition here ]]) or netPlay()

Since character parameters are written on one line in select.def, complicated conditions are easier to maintain in an external module:

-- function declared in an external module
function myUnlockCondition(myArgument)
	-- Any Lua code goes here.
	-- Return true to unlock or false to keep locked.
end

Then call the function from the unlock parameter.

Stage unlocking works the same way as character unlocking. Assign an unlock parameter as a stage parameter in select.def. The condition should return true when the stage should be available.

Game modes can be locked in the screenpack DEF file under [Title Info] by using:

menu.unlock.<itemname> = lua_condition_here

Replace <itemname> with the menu item name associated with the mode.

The value is read as Lua code. If the parameter is missing or returns true, the mode is visible. If it returns false, the mode is hidden.

Unlike character and stage unlocking, game mode unlocking is runtime-permanent. Once the mode is unlocked, the condition is not checked again until the game is restarted.

External Lua scripts, referred to here as modules, are used to add Lua-coded features without directly modifying scripts distributed with the engine.

There are three ways to load external modules. Modules are loaded after default scripts, in the following order:

1. Any .lua file placed in external/mods is loaded automatically, in alphabetical order.
2. Lua file paths can be added through Common.Modules in the config.
3. A screenpack can load its own Lua file from [Files] using module = path_to_lua_file.

A module directory can also contain a +system.def file. If present, it is appended to the main system.def, making it possible to add screenpack definitions from the module itself.

Use +system.def only for official motif parameters recognized by the engine. For new custom parameters, prefer a dedicated .def or .json file and load it with embedded Lua helper functions. This helps modules stay self-contained and reusable.

Since external modules are loaded after default scripts, they can access data initialized by the engine scripts while avoiding direct edits to those scripts. This makes modules easier to share and less likely to be overwritten by engine updates.

Modules are not guaranteed to stay forward compatible between stable releases. Functions, tables and script flow may change over time. The more intrusive a module is, the more likely it is to break after an update. Complex modules should usually target stable releases instead of nightly builds.

Whenever possible, prefer hooks over direct overwrites. Hook-based extensions are usually easier to maintain than replacing large parts of default logic.

Reference modules are available here:

https://github.com/ikemen-engine/modules

This repository contains example modules, including modules that add new game modes and team mode features.

The hook system lets external modules attach code to selected points in the default Lua scripts without editing those scripts directly.

Hooks are the preferred way to extend built-in scripts. They do not guarantee forward compatibility, but they are usually safer and easier to maintain than direct function or table overwrites.

Hook lists are identified by string names. Some lists are provided by default by the engine. Modules can also define and run their own custom hook lists.

Hook execution order should be treated as undefined.

Hooks are stored in a Lua table and iterated with pairs(), so modules should not rely on one hook running before another unless they handle that explicitly.

hook.runFirst() should be used only with hooks designed to act as overrides. Returning nil means "not handled". Any non-nil value stops further processing and is returned to the caller.

More hook entry points may be added in the future. If a module needs access to a place that is not currently hookable, it is usually better to request a new hook than to patch default scripts directly.

Format: hook.add(list, name, func)
Required arguments:
list = string hook list name.
name = string unique entry name within this list.
func = function to register.
Return: none

Adds a function to a hook list.

If another function with the same name already exists in the same list, it is replaced.

hook.add("main.f_default", "mymodule_defaults", function()
	main.myflag = true
end)

Format: hook.run(list, ...)
Required arguments:
list = string hook list name.
... = extra arguments forwarded to every function in the list.
Return: none

Runs all functions registered in a hook list.

If the list does not exist or is empty, nothing happens.

hook.add("main.f_default", "mod_a", function()
	print("A")
end)

hook.add("main.f_default", "mod_b", function()
	print("B")
end)

When the main.f_default hook is executed, both functions are called.

Format: hook.runFirst(list, ...)
Required arguments:
list = string hook list name.
... = extra arguments forwarded to functions in the list.
Return: first non-nil value, or nil if nothing handled the call.

Runs functions from a hook list until one returns a non-nil value.

This is meant for override-style entry points.

hook.add("start.f_selectMode.luaPath", "my_path", function(path)
	if gameMode() == "arcade" then
		return "external/mods/my_module/arcade.lua"
	end
end)

If this function returns a path, later hooks in the same list are not called.

Format: hook.stop(list, name)
Required arguments:
list = string hook list name.
name = registered hook name.
Return: none

Removes a hook from a list.

hook.stop("main.f_default", "mymodule_defaults")

Below is the list of hook entry points currently exposed by default scripts.

Format: hook.add("launchFight", name, func)
Callback arguments:
common = table temporary Common lists for this match.
t = table resolved launchFight() data.
data = table original argument table passed to launchFight().

Called right before start.f_selectLoading() / loadStart().

This hook can modify common in place. It is the correct place to append per-match Common.* entries from Lua.

hook.add("launchFight", "my_common_lua", function(common)
	common.lua = common.lua or {}
	table.insert(common.lua, "external/mods/my_module/common.lua")
end)

Format: hook.add("loop", name, func)
Callback arguments: none

Called at the start of global.lua loop().

Format: hook.add("loop#[gamemode]", name, func)
Callback arguments: none

Called at the start of global.lua loop(), but limited to the current game mode.

Replace [gamemode] with the actual mode name.

hook.add("loop#arcade", "my_arcade_logic", function()
	-- code executed only in arcade mode
end)

Format: hook.add("main.f_commandLine", name, func)
Callback arguments:
t = table parsed quick-vs player entries.
flags = table raw command line flags.
t_teamMode = table team mode values for both sides.
t_numChars = table team sizes for both sides.
t_matchWins = table match win settings.
t_params = table extra loadStart() params that will be appended later.

Called during command line quick-vs setup, before loading starts.

Format: hook.add("main.f_commandLine.player", name, func)
Callback arguments:
entry = table current parsed player entry.
flags = table raw command line flags.
num = int player number from -pN.
player = int team side, 1 or 2.

Called once for every parsed -pN quick-vs entry.

Useful for custom command line parameters.

Format: hook.add("main.f_default", name, func)
Callback arguments: none

Called after base mode defaults are initialized.

Format: hook.add("main.t_itemname", name, func)
Callback arguments:
t = table current menu table.
item = int selected item index.

Called from mode handlers after default mode setup.

Useful for enabling or disabling extra mode-specific behavior from an external module.

Format: hook.add("main.menu.loop", name, func)
Callback arguments: none

Called at the start of the shared main menu loop.

Format: hook.add("menu.menu.loop", name, func)
Callback arguments: none

Called at the start of submenu loops in menu.lua.

Format: hook.add("options.menu.loop", name, func)
Callback arguments: none

Called at the start of submenu loops in options.lua.

Format: hook.add("options.default", name, func)
Callback arguments: none

Called after restoring default option values.

Useful for resetting module-owned config values.

Format: hook.add("options.save", name, func)
Callback arguments:
reload = bool whether saving this options change will reload the engine.

Called from options.f_saveCfg() after the main config file is saved and before any reload is triggered.

Useful for modules that keep their own config files and should save them only when the user chooses to save settings from the Options menu.

Format: hook.add("main.f_addChar.files", name, func)
Callback arguments:
char = table character data table being appended to main.t_selChars.

Called after default file path resolution for a newly added playable character.

Useful for resolving custom file fields.

Format: hook.add("main.selectDef.options", name, func)
Callback arguments:
t_selOptions = table parsed select.def options table.
lineCase = string lowercased version of the parsed line.

Called for each [Options] line in select.def.

Useful for parsing custom module parameters.

Format: hook.add("main.selectDef.defaults", name, func)
Callback arguments:
t_selOptions = table parsed select.def options table.

Called after default select.def option values are assigned.

Useful for injecting fallback values when custom options are missing.

Format: hook.add("start.f_selectScreen", name, func)
Callback arguments: none

Called during the select screen loop.

Format: hook.add("start.f_selectVersus", name, func)
Callback arguments: none

Called during the versus screen loop.

Format: hook.add("start.f_selectReset", name, func)
Callback arguments: none

Called near the end of start.f_selectReset().

Format: hook.add("start.f_selectReset.side", name, func)
Callback arguments:
side = int team side, 1 or 2.
hardReset = bool whether this is a full reset.
preserveProgress = bool whether mode progress is preserved.
state = table start.p[side] table for this side.

Called once for each side during start.f_selectReset().

Use this to reset module-owned side state.

Format: hook.add("start.f_selectChallenger.resume", name, func)
Callback arguments:
resume = table resume snapshot that will be restored.
winnerSide = int winning side from challenger match.
challengerState = table challenger select state snapshot.

Lets modules preserve additional winner-side state when a challenger interrupts arcade flow and control returns to the resumed run.

Format: hook.add("start.f_selectMode.luaPath", name, func)
Callback arguments:
path = string current Lua path.
Return: string or nil

Called through hook.runFirst().

Return a non-nil string to override the mode Lua path.

Format: hook.add("start.selectScreen.teamMenu", name, func)
Callback arguments:
side = int team side, 1 or 2.
list = table team menu items for this side.
params = table resolved team menu item names.
itemname_order = table resolved item render order.

Called while building the team menu.

Use this to append custom team mode entries.

Format: hook.add("start.f_teamMenu.input", name, func)
Callback arguments:
side = int team side, 1 or 2.
t = table team menu items.
t_cmd = table command owners for this menu.
Return: any non-nil value if input was handled.

Called through hook.runFirst().

Use it for custom left/right value handling on new team menu items.

Format: hook.add("start.f_teamMenu.drawItemValue", name, func)
Callback arguments:
side = int team side, 1 or 2.
t = table team menu items.
i = int current item index.
x = number item draw X offset.
y = number item draw Y offset.
valueCfg = table team menu value config.
Return: any non-nil value if drawing was handled.

Called through hook.runFirst().

Use it to draw icons or custom values for module-defined team menu entries.

Format: hook.add("start.f_teamMenu.confirm", name, func)
Callback arguments:
side = int team side, 1 or 2.
t = table team menu items.
t_cmd = table command owners for this menu.
Return: table or nil.

Called through hook.runFirst().

Return a table to override default confirmation logic.

Recognized fields are copied into start.p[side]. In practice this is usually used for values such as teamMode, numChars, or module-specific flags.

hook.add("start.f_teamMenu.confirm", "my_mode", function(side, t, t_cmd)
	local cur = t[start.p[side].teamMenu]
	if cur == nil or cur.itemname ~= "mymode" then
		return nil
	end
	return {
		teamMode = cur.mode,
		numChars = 2,
		mymode = true,
	}
end)

Format: hook.add("start.f_selectMenu.selected", name, func)
Callback arguments:
side = int team side, 1 or 2.
member = int team member slot.
entry = table newly selected member entry.
state = table start.p[side].
player = int controlling player number.

Called after a character is confirmed on the select screen.

Format: hook.add("start.launchFight.selected", name, func)
Callback arguments:
side = int team side, 1 or 2.
member = int team member slot.
entry = table newly inserted member entry.
state = table start.p[side].
t = table resolved launchFight() data.

Called after a character is inserted directly through launchFight().

Format: hook.add("start.f_selectLoading.member", name, func)
Callback arguments:
v = table per-member loading table.

Called for every selected fighter before loadStart() params are built.

This is the main hook for pre-match member setup. It can be used to assign maps, life overrides, attack data, module flags and other startup values.

hook.add("start.f_selectLoading.member", "my_maps", function(v)
	v.maps = v.maps or {}
	v.maps.myflag = 1
	v.maps.bonuslife = 250
end)

This produces loadStart() params like p1.1.map.myflag=1.

Format: hook.add("start.f_lifeRecovery", name, func)
Callback arguments:
lifeMax = number fighter max life.
fighter = table fighter stats/state table from match results.
Return: number or nil.

Called through hook.runFirst().

Return a value to override the default between-match life recovery formula. Return nil to keep default behavior.

Format: hook.add("game.result_init", name, func)
Callback arguments: none

Called on the first frame of the win / results screen.

Format: hook.add("game.result", name, func)
Callback arguments: none

Called from the second frame onward on the win / results screen.

Format: hook.add("game.victory_init", name, func)
Callback arguments: none

Called on the first frame of the victory screen.

Format: hook.add("game.victory", name, func)
Callback arguments: none

Called from the second frame onward on the victory screen.

Format: hook.add("game.continue_init", name, func)
Callback arguments: none

Called on the first frame of the continue screen.

Format: hook.add("game.continue", name, func)
Callback arguments: none

Called from the second frame onward on the continue screen.

Format: hook.add("game.hiscore_init", name, func)
Callback arguments: none

Called on the first frame of the hiscore screen.

Format: hook.add("game.hiscore", name, func)
Callback arguments: none

Called from the second frame onward on the hiscore screen.

Format: hook.add("game.challenger_init", name, func)
Callback arguments: none

Called on the first frame of the challenger screen.

Format: hook.add("game.challenger", name, func)
Callback arguments: none

Called from the second frame onward on the challenger screen.

This section documents Lua helper functions available to scripts, modules and custom mode files.

These pre-made helpers are intended for Arcade Paths and Story Mode arcs.

Format: launchFight{args}
Required arguments: none
Return: bool. Returns false if further Lua script execution should stop, based on the function parameters and match result. Otherwise returns true.

Optional arguments:

continue = bool Decides whether the character can continue and rematch after a lost or drawn fight. If false, the continue screen is skipped and Lua script execution continues. This can be useful for branching storylines on defeat.

• default arcade path: true
• default story mode: true

quickcontinue = bool Decides whether the player can select a new character after the continue screen. If false, the rematch uses the same character.

• default arcade path: inherited from options
• default story mode: true, regardless of options, because the select screen is disabled in Story Mode

order = int Limits random opponent selection to characters with this order.

• default arcade path: 1
• default story mode: 1

p1char = table List of characters to assign to p1 team side. Character names or paths should be strings.

• default arcade path: characters chosen on the select screen
• default story mode: previously assigned characters

p1pal = int Forces a particular palette for p1.

p1numchars = int Forces p1 team size.

• default arcade path: team size chosen on the select screen, but not less than p1char count
• default story mode: at least 1, but not less than p1char count

p1numratio = table List of ratio settings, from 1 to 4, to assign to p1 team side characters when turns team mode is selected.

Example for three players:

p1numratio = {1, 1, 2}

• default arcade path: same as the ratio chosen on the select screen, not assigned otherwise
• default story mode: not assigned

p1teammode = string Assigns p1 team mode: single, simul, tag or turns.

• default arcade path: team mode chosen on the select screen
• default story mode: single

p1rounds = int Number of rounds p1 has to lose to be considered defeated.

• default arcade path: inherited from options
• default story mode: inherited from options

p1orderselect = bool Decides whether p1 can switch team order.

• default arcade path: true
• default story mode: false

p2char = table List of characters to assign to p2 team side. Character names or paths should be strings.

• default arcade path: random characters with the selected order, up to the team size chosen on the select screen
• default story mode: one random character with the selected order

p2pal = int Forces a particular palette for p2.

p2numchars = int Forces p2 team size.

• default arcade path: team size chosen on the select screen, but not less than p2char count
• default story mode: at least 1, but not less than p2char count

p2numratio = table List of ratio settings, from 1 to 4, to assign to p2 team side characters when turns team mode is selected.

• default arcade path: follows arcade.ratiomatches select.def settings in arcade, if selected; not assigned otherwise
• default story mode: not assigned

p2teammode = string Assigns p2 team mode: single, simul, tag or turns.

• default arcade path: team mode chosen on the select screen
• default story mode: single

p2rounds = int Number of rounds p2 has to lose to be considered defeated.

• default arcade path: rounds assigned as select.def parameter, or inherited from options
• default story mode: inherited from options

p2orderselect = bool Decides whether p2 can switch team order.

• default arcade path: true
• default story mode: false

exclude = table List of characters to exclude from random selection for this match. Characters are still available in the next launchFight call. Characters already fought in the current arcade run with this character are automatically excluded.

• default arcade path: empty list
• default story mode: empty list

music = table Music used at the start of the round. The path string can optionally be followed by volume, loopstart and loopend values.

music = {"sound/theme.mp3", 100, 0, 0}

• default arcade path: music assigned as select.def parameter, or default stage music
• default story mode: default stage music

round.music = table Music used at the start of a specific round. The <roundno> part of the key decides the round.

["round2.music"] = {"sound/round2.mp3", 100, 0, 0}

• default arcade path: music assigned as select.def parameter, or default stage music
• default story mode: default stage music

final.music = table Music used at the start of the final round.

• default arcade path: music assigned as select.def parameter, or default stage music
• default story mode: default stage music

life.music = table Music used when the player's controlled character has low life during a deciding round. Further adjustments are available through the stage DEF file.

• default arcade path: music assigned as select.def parameter, or default stage music
• default story mode: default stage music

victory.music = table Music that starts after the character scores the final round K.O. and continues through the victory screen.

• default arcade path: music assigned as select.def parameter, or default stage music
• default story mode: default stage music

stage = string Path to the stage used in this match.

• default arcade path: stage assigned as select.def parameter, or randomized
• default story mode: randomized

ai = float Forces AI level from 1 to 8, regardless of difficulty and AI ramping settings.

• default arcade path: AI assigned as select.def parameter, or value following AI ramping settings
• default story mode: inherited from options

time = int Overrides round time, in seconds, for this match.

• default arcade path: inherited from options, adjusted by tag team size
• default story mode: inherited from options, adjusted by tag team size

vsscreen = bool Decides whether the versus screen is shown before the fight.

• default arcade path: true
• default story mode: false

victoryscreen = bool Decides whether the victory screen is shown after the fight.

• default arcade path: true
• default story mode: false

lua = string Lua code executed each frame during the match. For example, this can call a custom function that stores match data gathered through Lua trigger functions.

Example:

launchFight{
	p2char = {"Juni", "Juli"},
	p2numchars = 2,
	p2teammode = "simul",
	p2rounds = 1,
	time = 60,
	stage = "stages/dolls.def",
	["victory.music"] = {"sound/kfm.mp3", 100, 0, 0}
}

Format: launchStoryboard(path)
Required arguments: path of the storyboard to execute.
Return: bool. Returns false if the storyboard does not exist, otherwise true.

Example:

launchStoryboard('chars/kfm/intro.def')

Below are the documented embedded Lua functions exposed by the engine.

* marks an optional parameter.

addChar(defpath, params)

Add a character definition to the select screen.

Parameters

Returns

addHotkey(key, ctrl, alt, shift, allowDuringPause, debugOnly, script)

Register a global keyboard shortcut that runs Lua code.

Parameters

Returns

addStage(defpath, params)

Add a stage definition to the select screen.

Parameters

Returns

animAddPos(anim, dx, dy)

Add an offset to an animation's current position.

Parameters

animApplyVel(target, source)

Copy velocity parameters from one animation to another.

Parameters

animCopy(anim)

Create a copy of an animation.

Parameters

Returns

animDebug(anim, prefix)

Print debug information about an animation to the console.

Parameters

animDraw(anim, layer)

Queue drawing of an animation on a render layer.

Parameters

animGetLength(anim)

Get timing information for an animation.

Parameters

Returns

animGetPreloadedCharData(charRef, group, number, keepLoop)

Get a preloaded character animation by sprite group/number.

Parameters

Returns

animGetPreloadedStageData(stageRef, group, number, keepLoop)

Get a preloaded stage animation by sprite group/number.

Parameters

Returns

animGetSpriteInfo(anim, group, number)

Get information about a sprite used by an animation.

Parameters

Returns

animLoadPalettes(anim, param)

Load palettes for an animation's underlying sprite file, if palette usage is enabled.

Parameters

animNew(sff, actOrAnim)

Create a new animation from a sprite file and action definition.

Parameters

Returns

animPaletteGet(anim, paletteId)

Get a palette from an animation.

Parameters

Returns

animPaletteSet(anim, paletteId, palette)

Set colors in an animation palette.

Parameters

animPrepare(anim, charRef)

Prepare an animation so that each character can apply its own palette.

Parameters

Returns

animReset(anim, parts)

Reset an animation to its initial state, fully or partially.

Parameters

animSetAccel(anim, ax, ay)

Set gravity/acceleration applied to an animation.

Parameters

animSetAlpha(anim, src, dst)

Set alpha blending for an animation.

Parameters

animSetAngle(anim, angle)

Set rotation angle for an animation.

Parameters

animSetAnimation(anim, actOrAnim)

Replace an animation's underlying Animation data.

Parameters

animSetColorKey(anim, index)

Set the color key (transparent index) used by an animation.

Parameters

animSetColorPalette(anim, paletteId)

Change the active palette mapping for an animation.

Parameters

Returns

animSetFacing(anim, facing)

Set the facing (horizontal flip) of an animation.

Parameters

animSetFocalLength(anim, fLength)

Set focal length used for perspective projection on an animation.

Parameters

animSetFriction(anim, fx, fy)

Set friction applied to an animation's velocity.

Parameters

animSetLayerno(anim, layer)

Set the render layer used by an animation.

Parameters

animSetLocalcoord(anim, width, height)

Set the local coordinate system for an animation.

Parameters

animSetMaxDist(anim, maxX, maxY)

Set maximum drawing distance (clipping bounds) for an animation.

Parameters

animSetPalFX(anim, palfx)

Configure palette effects for an animation.

Parameters

animSetPos(anim, x, y)

Set animation position, optionally overriding only one axis.

Parameters

animSetProjection(anim, projection)

Set projection mode for an animation.

Parameters

animSetScale(anim, sx, sy)

Set the scale of an animation.

Parameters

animSetTile(anim, tileX, tileY, spacingX, spacingY)

Configure tiling for an animation.

Parameters

animSetVelocity(anim, vx, vy)

Set the base velocity of an animation.

Parameters

animSetWindow(anim, x1, y1, x2, y2)

Set the clipping window for an animation.

Parameters

animSetXAngle(anim, xangle)

Set rotation angle around the X axis for an animation.

Parameters

animSetXShear(anim, shear)

Set the X shear factor applied when drawing an animation.

Parameters

animSetYAngle(anim, yangle)

Set rotation angle around the Y axis for an animation.

Parameters

animUpdate(anim, force)

Advance an animation by one tick. By default, only the first call per frame advances the animation.

Parameters

batchDraw(batch)

Queue drawing of many animations in one call.

Parameters

bgDebug(bg, prefix)

Print debug information about a background definition.

Parameters

bgDraw(bg, layer, x, y, scale)

Queue drawing of a background definition.

Parameters

bgNew(sff, defPath, section, model, defaultLayer)

Load a background definition from a sprite file and configuration.

Parameters

Returns

bgReset(bg)

Reset a background definition to its initial state.

Parameters

changeAnim(animNo, elem, ffx)

[redirectable] Change the character's current animation.

Parameters

Returns

changeState(stateNo)

[redirectable] Change the character's current state or disable it.

Parameters

Returns

clear()

Clear all characters' clipboard text buffers.

clearAllSound()

Stop all currently playing sounds.

clearColor(r, g, b, alpha)

Fill the screen with a solid color (with optional alpha).

Parameters

clearConsole()

Clear text printed to the in-engine console.

clearSelected()

Clear all current select-screen choices (characters, stages, music, game params).

commandAdd(name, command, time, bufferTime, bufferHitpause, bufferPauseend, stepTime)

Register a UI command definition.

Parameters

commandBufReset(playerNo)

Reset command input buffers.

Parameters

commandDebug(playerNo, prefix)

Print debug information about a command list.

Parameters

commandGetState(playerNo, name)

Query the current state of a named command.

Parameters

Returns

computeRanking(mode)

Compute and store ranking data for a mode, returning whether it was cleared.

Parameters

Returns

connected()

Check if the main menu network connection is established.

Returns

continued()

Check whether the current run used a continue.

Returns

endMatch()

Signal that the current match should end (using menu fade-out settings).

enterNetPlay(host)

Enter netplay as client or host.

Parameters

enterReplay(path)

Enter replay playback mode from a replay file.

Parameters

Returns

esc(value)

Get or set the global escape flag.

Parameters

Returns

exitNetPlay()

Exit netplay mode and close any active netplay connection.

exitReplay()

Exit replay mode and restore normal video settings.

fadeActive()

Check whether any global motif fade is active.

Returns

fadeInInit(fade)

Initialize a Fade object using motif fade-in settings.

Parameters

fadeOutInit(fade)

Initialize a Fade object using motif fade-out settings.

Parameters

fadeSkip()

Immediately stop any running global motif fade.

fileExists(path)

Test whether a file exists, after engine path resolution.

Parameters

Returns

findEntityByName(text)

Find the next entity whose name contains the given text.

Parameters

findEntityByPlayerId(playerId)

Find the next entity with the given player ID.

Parameters

findHelperById(helperId)

Find the next helper with the given helper ID.

Parameters

fontGetDef(font)

Get basic font definition information.

Parameters

Returns

fontNew(filename, height)

Load a font from file.

Parameters

Returns

frameStep()

Enable single-frame stepping mode.

game()

Execute a full match using the current configuration.

Returns

gameRunning()

Check whether a match is currently running.

Returns

getAnimElemCount()

[redirectable] Get the character's number of elements in the animation.

Returns

getAnimTimeSum()

[redirectable] Get the character's current accumulated time of the animation.

Returns

getCharAttachedInfo(def)

Resolve and read basic information from a character definition file.

Parameters

Returns

getCharFileName(charRef)

Get the definition file path for a character slot.

Parameters

Returns

getCharInfo(charRef)

Get detailed information about a character slot.

Parameters

Returns

getCharName(charRef)

Get the display name of a character slot.

Parameters

Returns

getCharPreloadStatus(charRef)

Query the background preload state of a character slot.

Parameters

Returns

getCharRandomPalette(charRef)

Get a random valid palette number for a character slot.

Parameters

Returns

getCharSelectParams(charRef)

Get parsed select parameters for a character entry.

Parameters

Returns

getClipboardString()

Get the current system clipboard string.

Returns

getCommandLineFlags()

Get all command-line flags passed to the engine.

Returns

getCommandLineValue(flagName)

Get the value of a specific command-line flag.

Parameters

Returns

getConsecutiveWins(teamSide)

Get the number of consecutive wins for a team.

Parameters

Returns

getCredits()

Get the current credit count.

Returns

getDirectoryFiles(rootPath)

Recursively list all paths under a directory.

Parameters

Returns

getFrameCount()

Get the global frame counter value.

Returns

getGameFPS()

Get the current measured gameplay FPS.

Returns

getGameParams()

Get the current game parameter table.

Returns

getGameSpeed()

Get the current game logic speed as a percentage.

Returns

getGameStats()

Read accumulated game statistics.

Returns

getGameStatsJson()

Get a JSON snapshot of accumulated game statistics.

Returns

getInput(players, ...)

Check raw UI input for one or more players.

Parameters

Returns

getInputTime(players, ...)

Get the hold time of a raw input token for one or more players.

Parameters

Returns

getJoystickGUID(index)

Get a joystick's GUID string.

Parameters

Returns

getJoystickKey(controllerIdx)

Poll joystick input and return the corresponding key string.

Parameters

Returns

getJoystickName(index)

Get a joystick's display name.

Parameters

Returns

getJoystickPresent(index)

Check whether a joystick is present.

Parameters

Returns

getKey(key)

Query or compare the last pressed key.

Parameters

Returns

getKeyText()

Get the last input text associated with the current key event.

Returns

getLastInputController()

Get the last controller that produced UI input.

Returns

getMatchTime()

Get the accumulated match time from completed rounds.

Returns

getMovelist()

[redirectable] Get the character's movelist text.

Returns

getRandom()

Return a 32-bit random number, updating the global seed.

Returns

getRemapInput(playerNo)

Get the input remap target for a player.

Parameters

Returns

getRoundTime()

Get the configured round time limit.

Returns

getRuntimeOS()

Get the current runtime operating system identifier.

Returns

getSelectNo()

[redirectable] Get the character's select slot index.

Returns

getSessionWarning()

Pop the current session warning message.

Returns

getStageInfo(stageRef)

Get information about a stage slot.

Parameters

Returns

getStageNo()

Get the currently selected stage slot index.

Returns

getStagePreloadStatus(stageRef)

Query the background preload state of a stage slot.

Parameters

Returns

getStageSelectParams(stageRef)

Get parsed select parameters for a stage entry.

Parameters

Returns

getStateOwnerId()

[redirectable] Get the character's player ID.

Returns

getStateOwnerName()

[redirectable] Get the character's name of the current state owner.

Returns

getStateOwnerPlayerNo()

[redirectable] Get the character's player number of the current state owner.

Returns

getStoryboardScene()

Get the current storyboard scene index.

Returns

getTimestamp(format)

Get a formatted timestamp string.

Parameters

Returns

getWinnerTeam()

Get the winning team side of the current or last match.

Returns

isUIKeyAction(action)

Check whether a UI action name is currently active.

Parameters

Returns

jsonDecode(path)

Decode a JSON file into Lua values.

Parameters

Returns

jsonEncode(value, path)

Encode a Lua value to JSON and save it to a file.

Parameters

loadAnimTable(path, sff)

Load an AIR/animation definition file and return an animation table.

Parameters

Returns

loadDebugFont(filename, scale)

Load and set the font used by the debug overlay.

Parameters

loadDebugInfo(funcs)

Register Lua functions to be called for debug info display.

Parameters

loadDebugStatus(funcName)

Register the Lua function used to draw debug status.

Parameters

loadGameOption(filename)

Load game options from a config file and return the current config as a table.

Parameters

Returns

loading()

Check whether resources are currently being loaded.

Returns

loadIni(filename, normalizeSections, keepMeta)

Load an INI file and convert it to a nested Lua table.

Parameters

Returns

loadFightScreen(defPath)

Load the fight screen definition.

Parameters

loadMotif(defPath)

Load a motif and return its configuration as a table.

Parameters

Returns

loadStart(params)

Validate selection and start asynchronous loading of characters and stage.

Parameters

loadCancel()

Cancel an in-progress background load, clean up partially loaded assets, and reset the netplay loading handshake.

loadState()

Request loading of a previously saved state on the next frame.

loadStoryboard(defPath)

Load a storyboard and set it as the current storyboard.

Parameters

Returns

loadText(path)

Load a text file and return its contents.

Parameters

Returns

mapSet(name, value, mapType)

[redirectable] Set the character's map value.

Parameters

storyboardCanceled()

Check whether the most recent storyboard was canceled by the player.

Returns

modelNew(filename)

Load a 3D model (glTF) as a Model object.

Parameters

Returns

modifyGameOption(query, value)

Modify a game option using a query string path.

Parameters

modifyMotif(query, value)

Modify a motif using a query string path.

Parameters

modifyStoryboard(query, value)

Modify a currently loaded storyboard using a query string path.

Parameters

netPlay()

Check whether the current session is running in netplay mode.

Returns

netLoadingReady()

Poll the non-blocking netplay loading handshake. Returns true when both peers have finished loading, or immediately if not in netplay.

Returns

panicError(message)

Raise an immediate Lua error with a custom message.

Parameters

paused()

Check whether gameplay is currently paused.

Returns

playBgm(params)

[redirectable] Control background music playback.

Parameters

playerBufReset(playerNo)

Reset player input buffers and disable hardcoded keys.

Parameters

playSnd

[redirectable] Play the character's sound.

Parameters