MF_Core — API Reference

Base library for the MF_* plugin family for RPG Maker MZ: utilities, math, layout units, safe hooks, events, validation, conditions, file/save/config storage, editable documents, localization and text codes, input and drag-and-drop, tweens and timers, asset preloading, and layout-aware display primitives.

Press / to search every function, option and pitfall on this page.

Overview

Everything is exposed through the global object MF. Modules marked experimental may change in a MINOR release (always listed in the changelog).

Pitfalls

Details that are easy to miss when you jump straight to one function. Each item is also marked with a red Pitfall box in its section.

Setup and versions

• MF_Core must be above every MF_* pluginOtherwise MF is undefined when the plugin loads. Add @base MF_Core and @orderAfter MF_Core so the Plugin Manager warns about the order.
  See: Installation, Plugin template
• Always state the MF_Core version you wrote againstregister(name, v, { requires: { MF_Core: "1.0.0" } }) and the same in @help. Without it you cannot tell later which plugins were written for which API; a missing version logs a warning.
  See: Versioning policy, MF.Core
• Experimental APIs may change in a MINOR releaseMF.Layout, MF.UI, MF.Document and MF.Input.draggable can change in 1.x — always with a changelog entry. Read the changelog before updating MF_Core.
  See: Versioning policy
• Errors in hooks are not swallowedAn exception in MF.Hook.alias/before/after shows the error screen, like any MZ plugin. Use { safe: true } only for cosmetic additions — it hides errors of your function.
  See: MF.Hook › safe mode

Text and messages

• Backslashes are doubled in JavaScript stringsIn code: "\\C[2]Hi\\C[0]". In the event editor you type \C[2]Hi\C[0]. A single backslash in JS silently turns \C into C.
  See: MF.Text
• Escape codes also run when text is only measuredRPG Maker processes codes in textSizeEx (choice widths, word wrap) without drawing. Custom escapes with side effects (sounds, shakes, waits) must check ctx.drawing, and message-only effects ctx.isMessage. Otherwise a sound plays when the choice window is sized.
  See: MF.Text › Custom codes
• \FACE does not move the textChanging the face mid-message keeps the text position. Start the message with a face (or reserve space) if you switch faces later.
  See: MF.Text › Built-in codes
• Code names: letters only, some are reservedRPG Maker parses codes as [A-Z]+, so \I18N would be read as \I. V N P G C I PX PY FS are reserved. Parameters cannot contain ].
  See: MF.Text › Custom codes
• MF.Text.show needs a message windowWorks on the map and in battle. In your own scene there is no Window_Message — the Promise waits forever (until the scene changes, then resolves false).
  See: MF.Text › Messages as Promises
• Script conditions are off by defaultWith Allow Scripts disabled, { script: "…" } is always false. A warning is logged once per snippet — check the console if a condition "never works".
  See: MF.Script, Parameters

Time and animation

• Durations are frames, bound to the sceneWork created in a scene's constructor or initialize() belongs to the previous scene (it is still current) — pass { scene: this } (1.2.0) or start it in create(). duration: 60 = one second at 60 fps. Tweens, timers and Timer.until pause while the game window is inactive and are cancelled on scene change (Promises resolve false). Use persistent: true to survive scene changes.
  See: MF.Ticker, MF.Tween, MF.Timer
• Assets.bindScene must be called before the scene startsCall it in create(). Once the scene has started, isReady() is no longer consulted.
  See: MF.Assets
• Preloaded audio is decoded again on playbackRPG Maker creates a new buffer for every BGM/BGS/ME/SE playback. Preloading only warms the file cache — except static SE (static: true).
  See: MF.Assets

Data, saves and files

• Save data must be plain JSON-like dataObjects, arrays, strings, numbers, booleans. Class instances survive only if their constructor is a global; sprites, bitmaps and functions never do.
  See: MF.Save
• Module-level variables are not savedA let quests = {} inside your plugin is lost on load and shared between save slots. Use MF.Save (per save) or MF.Config (global).
  See: MF.Save, MF.Config
• An invalid optional data file becomes the defaultThe game keeps running, but saving that default from an editor would overwrite the user's broken file. Check MF.Data.status() — or use MF.Document, which refuses such saves.
  See: MF.Data, MF.Document
• Utils.diff cannot express removed keysRemoving a key from the target is not visible in the diff. Store explicit values such as visible: false.
  See: MF.Utils
• Invalid size expressions fall back silently-ish"50% +" resolves to the fallback (0 by default) with a console warning. Validate user input with MF.Units.isValid or a units schema.
  See: MF.Units, MF.Schema

Input and display

• RPG Maker already uses many keysDefault bindings include Tab, Enter, Shift, Ctrl, Alt, Esc, Space, PageUp/Down, arrows, Insert, Q, W, X, Z, numpad and F9. MF.Input.bind skips those with a warning unless override: true.
  See: MF.Input › Actions
• Shortcuts are ignored while typing in HTML fieldsisShortcut returns false when an input/textarea has focus (editor inspectors), unless { whileTyping: true }.
  See: MF.Input › Raw keys and shortcuts
• A consumed pointer is invisible to the game for that frameWhile dragging (or after consumePointer()) TouchInput.* returns false — windows under the pointer don't react. Read raw values with MF.Input.pointer().
  See: Drag-and-drop
• MF.UI.Window redraws only after a resizerefresh() is called automatically when the size changes. Call it yourself after creation and when your data changes.
  See: MF.UI

Installation

1. Copy MF_Core.js to js/plugins/.
2. Enable it in the Plugin Manager.
3. Place it above all other MF_* plugins.

Requires RPG Maker MZ 1.8+. File-writing features require NW.js (desktop / test play); everything else also works in browser builds.

Parameters

Plugin template

New to MF_Core? The tutorial builds this plugin step by step.

Template for a dependent plugin. Note the explicit MF_Core version in both @help and code — see Versioning policy (Reference).

/*:
 * @target MZ
 * @plugindesc [v0.1.0] Quest log.
 * @author MesaFer
 * @base MF_Core
 * @orderAfter MF_Core
 *
 * @help MF_QuestLog.js
 * Requires: MF_Core 1.0.0+ (written against 1.0.0)
 */
(() => {
    "use strict";
    const PLUGIN_NAME = "MF_QuestLog";

    if (!window.MF || !MF.Core) throw new Error(`${PLUGIN_NAME} requires MF_Core.`);
    MF.Core.register(PLUGIN_NAME, "0.1.0", { requires: { MF_Core: "1.0.0" } });

    const params = MF.Core.parameters(PLUGIN_NAME, {
        type: "object",
        properties: {
            maxQuests: { type: "integer", min: 1, default: 20 }
        }
    });

    MF.Save.register(PLUGIN_NAME, { default: () => ({ quests: {} }), version: 1 });
    const t = MF.I18n.translator(PLUGIN_NAME);
})();

MF.Core

Registers an MF_* plugin. info.requires — { pluginName: minVersion }, each checked with require() before registration. Other info fields are stored in the registry entry.

MF.Core.register("MF_QuestLog", "0.1.0", { requires: { MF_Core: "1.0.0" } });

Throws an Error (shown by MZ on screen) when name is not registered or its version is lower than minVersion. Logs a warning when minVersion is omitted, and a one-time compatibility warning when the installed MAJOR version is higher than the required one.

Same as PluginManager.parameters, but recursively parsed with MF.Utils.parseParams. With a schema, values are validated and defaults are applied; problems are logged as one warning listing all fields.

MF.Log

MF.Log.debug(tag, ...args)   // only when the "debug" parameter is enabled
MF.Log.info(tag, ...args)
MF.Log.warn(tag, ...args)
MF.Log.error(tag, ...args)

Output is prefixed with [tag], e.g. [MF_UIEditor] layout applied.

MF.Utils

Type checks

Runtime mode

Data

Deep copy of plain data. Class instances are returned by reference.

Deep merge. Arrays are replaced as a whole; undefined values are skipped, null is written. Arguments are not mutated.

MF.Utils.merge({ a: { b: 1, c: 2 } }, { a: { c: 3 } });  // { a: { b: 1, c: 3 } }

Deep equality of plain data (NaN equals NaN).

Returns only the fields of target that differ from base. Always returns an object; nested objects without changes are omitted. Used to store layouts as overrides of the defaults.

MF.Utils.diff({ a: { b: 1 } }, { a: { b: 1 } });        // {}
MF.Utils.diff({}, { a: 5 });                            // { a: 5 }
MF.Utils.diff({ a: 5 }, { a: {} });                     // { a: {} }
MF.Utils.diff({ w: { x: 1, y: 2 } }, { w: { x: 5, y: 2 } }); // { w: { x: 5 } }

Path access

Paths are dot strings ("a.b.0.c") or arrays (["a", "b", 0, "c"]).

Misc

MF.Math

Numbers

Snapping

Snaps to the nearest target if it is within threshold. Intended for editor guides.

MF.Math.snap(13, [0, 15, 408], 4);  // { value: 15, snapped: true, target: 15 }

Rectangles

Rectangles are plain objects { x, y, width, height }.

Easing

Functions in MF.Math.easing take t in [0, 1]: linear, easeInQuad, easeOutQuad, easeInOutQuad, easeInCubic, easeOutCubic, easeInOutCubic, easeInSine, easeOutSine, easeInOutSine, easeOutBack, easeOutBounce.

MF.Math.ease("easeOutQuad", 0.5);           // 0.75 (t is clamped, unknown name → linear)
MF.Math.tween(0, 100, 0.5, "easeOutQuad");  // 75

MF.Units

Parses size and position expressions without eval. Compiled expressions are cached.

MF.Units.resolve("100%-240", Graphics.boxWidth);                  // 576 at 816
MF.Units.resolve("(100%-20)/2", 820);                             // 400
MF.Units.resolve("auto", 0, { auto: () => win.fittingHeight(4) });
MF.Units.resolve("50% +", 100, { fallback: 0 });                  // 0 + warning

Division by zero yields 0.

Functions, comparisons and conditions 1.1.0

Precedence (low → high): ? :, ||, &&, comparisons, + -, * /, unary - !, ^. if and ? : evaluate only the chosen branch. Unknown names, unknown functions and wrong argument counts are compile errors (isValid → false). Expressions valid in 1.0.0 give the same results.

MF.Units.resolve("clamp(50%, 200, 400)", 1000);                   // 400
MF.Units.resolve("angle(0, 0, 10, 10)", 0);                       // 45
MF.Units.resolve("3 > 2 ? 10 : 20", 0);                           // 10

MF.Anchor

Anchor names: top-left (default), top, top-right, left, center, right, bottom-left, bottom, bottom-right.

Offsets x/y are measured from the container's anchor point, and the element is aligned by the same point. For example, center with x = 0, y = 0 centers the element; bottom-right with x = -10 places it 10 px from the right edge.

MF.Anchor.toAbsolute("center", 0, 0, 100, 50, 816, 624);        // { x: 358, y: 287 }
MF.Anchor.toRelative("bottom-right", 716, 574, 100, 50, 816, 624); // { x: 0, y: 0 }

MF.Color

Accepted inputs: #rgb, #rgba, #rrggbb, #rrggbbaa, rgb(r, g, b), rgba(r, g, b, a), or an object { r, g, b, a? }.

MF.Hook

Standardized method overriding with a registry of who hooked what.

wrapper(original, ...args) is called with the object's this. Calling original() without arguments passes the original arguments; pass arguments explicitly to change them.

If the method is inherited (e.g. Window_Message.prototype.processCharacter comes from Window_Base), original() calls the parent's implementation as it is at call time, so a plugin that patches Window_Base later is not bypassed — a classic MZ plugin-order bug.

MF.Hook.alias(Scene_Menu.prototype, "create", function(orig) {
    orig();
    this.addChild(new Sprite());
}, "MF_UIEditor");

Calls fn(...args) first. Returning false skips the original.

Calls fn(result, ...args) after the original. Returning anything other than undefined replaces the result.

Error policy and safe mode

By default errors propagate, like any MZ alias: the game shows the error screen, which is what you want for bugs in core logic. This is deliberate — unlike event listeners, hooks are part of the engine's control flow, and silently swallowing an error there could leave a scene half-initialized.

{ safe: true } (for before / after) isolates errors thrown by fn itself: they are logged once per hook, and the original behavior/result is kept. Errors from the original method or other plugins in the chain are never swallowed.

// A cosmetic extension must never break the menu
MF.Hook.after(Scene_Menu.prototype, "create", function() {
    this.addDecorations();
}, "MF_Decor", { safe: true });

Installed hooks, for compatibility debugging.

MF.Events

const emitter = new MF.Events.EventEmitter();
const off = emitter.on("change", (a, b) => { … }, context);  // returns an unsubscribe function
emitter.once("ready", fn);
emitter.emit("change", 1, 2);   // → true if there were listeners
emitter.off("change", fn);      // remove one listener
emitter.off("change");          // remove all listeners of an event
emitter.off();                  // remove everything
emitter.listenerCount("change");
off();

Listener errors are caught and logged so one broken listener does not stop the others. The global bus is MF.Events.bus — see Bus events.

MF.Deprecation

Tools for the deprecation lifecycle. Every deprecated API is reported once per session (console warning + mf:deprecated bus event); further calls are counted.

With info.fn — obj[oldName] becomes a redirect to info.fn (renamed API). Without it — the existing obj[oldName] is wrapped (API scheduled for removal).

Redirects get/set of obj[oldName] to obj[newName].

Manual report, e.g. for a deprecated option value or data format.

MF.Schema

Validates and normalizes structured data: plugin parameters (@type struct), layout files, config values.

const schema = {
    type: "object",
    properties: {
        count:  { type: "integer", min: 1, max: 10, default: 3 },
        mode:   { type: "string", enum: ["fast", "slow"], required: true },
        size:   { type: "units", default: "100%" },
        anchor: { type: "anchor", default: "center" },
        tint:   { type: "color", nullable: true },
        items:  { type: "array", items: { type: "number" }, default: [] }
    },
    additionalProperties: false
};

MF.Schema.validate(data, schema);   // { ok, errors: [{ path: "items[1]", message: "must be a number" }] }
MF.Schema.normalize(data, schema);  // { ok, value, errors } — defaults applied, "12" → 12, "true" → true
MF.Schema.assert(data, schema, "MF_QuestLog parameters");  // value, or throws listing all problems

Validation only; the value is not changed.

Validation plus defaults and coercion of string values ("12" → 12, "true" → true, JSON strings → objects). The input is not mutated.

Like normalize, but throws an Error listing all problems.

Schema fields

Custom type. Report problems with ctx.error(message), validate nested values with ctx.child(value, schema, key), return a normalized value or undefined.

MF.Schema.register("actorId", (v, s, ctx) => {
    if (!Number.isInteger(v) || !$dataActors[v]) ctx.error(`unknown actor ${v}`);
});

MF.Condition

null, undefined and true are true; an array is treated as all.

MF.Condition.evaluate({ all: [
    { switch: 1 },
    { variable: 5, op: ">=", value: 3 },
    { not: { partyHas: 2 } }
]});

Unknown conditions and handler errors evaluate to false and are logged once per unique condition (conditions are often evaluated every frame).

Adds a condition type detected by the presence of key:

MF.Condition.register("level", c => $gameParty.leader().level >= c.level);
MF.Condition.evaluate({ level: 10 });

Switch and variable ids a condition depends on — lets UIs refresh on change instead of every frame.

MF.Script

code is an expression ("a + b") or a block with return. Keys of context are available as variables; context.self becomes this. Compiled functions are cached.

MF.Script.run("a + b", { a: 1, b: 2 });                 // 3
MF.Script.run("const x = a * 2; return x;", { a: 4 });  // 8

When scripts are disabled

With Allow Scripts = false, run returns fallback (for conditions: false). To avoid the "condition silently doesn't work" trap:

• a warning with the code and the parameter name is logged once per snippet;
• the bus event mf:scriptBlocked is emitted once per snippet;
• issues() lists all blocked/failed snippets with occurrence counts.

Runtime errors behave the same way (mf:scriptError, logged once).

MF.FS

Relative paths are resolved from the project root (the folder containing index.html).

NW.js only

projectRoot() tries, in order: process.mainModule.filename (what MZ core uses; deprecated in newer Node), the file:// page location, then process.cwd().

Everywhere

Rejected errors carry err.code:

Triggers a browser download.

Writes via fs when available, otherwise downloads the file.

MF.Data

Registers extra JSON files that are loaded together with the database (DataManager.loadDatabase). The game does not start until they are loaded.

MF.Data.register("$dataUILayouts", "UILayouts.json", {
    optional: true,
    default: { version: 1, scenes: {} },
    onLoad: data => MF.Migration.migrate("UILayouts", data, 1)
});

Error handling

state: idle | pending | loaded | failed. error: { code, message } or null; codes are those of loadJson plus process (onLoad threw).

Reloads a file (e.g. after saving in the editor). Rejects on any error except "optional file not found"; the rejected error has code.

Throws a pending required-file error in the ["LoadError", url, retry] format expected by SceneManager. Called automatically from DataManager.isDatabaseLoaded.

MF.Save

Plugin state stored inside the player's save file — no manual patching of DataManager.makeSaveContents / extractSaveContents. Data lives under contents.mf[key] = { v, data }.

MF.Save.register("MF_QuestLog", {
    default: () => ({ quests: {}, tracked: null }),
    version: 2,
    migrate: (data, fromVersion) => {
        if (fromVersion < 2) data.tracked = null;
        return data;
    }
});

const state = MF.Save.get("MF_QuestLog");   // mutable reference
state.quests.q1 = { stage: 2 };

Registers a save slot for a plugin (use the plugin name as key). Call at plugin load time.

Lifecycle

• Disabled plugins: data of keys that are not registered is kept and written back, so temporarily disabling a plugin does not wipe its progress.
• Errors in migrate/onLoad keep the raw data (defaults would destroy it on the next save), log an error and emit mf:saveError.
• Newer save (version above the registered one): warning, data kept as is.
• Store plain JSON-like data. Class instances survive only if their constructor is a global (normal MZ JsonEx rules).

MF.Config

Global settings (not per save) stored in config.rmmzsave under config.mf — e.g. UI theme, window opacity, language.

MF.Config.register("MF_UIEditor.theme", "default");
MF.Config.register("MF_UIEditor.opacity", 192, { schema: { type: "integer", min: 0, max: 255 } });

MF.Config.get("MF_UIEditor.opacity");               // 192
MF.Config.set("MF_UIEditor.opacity", 128, { save: true });

Use PluginName.setting keys. Unknown keys are preserved. Reserved key: MF_Core.locale (see I18n).

MF.Migration

Registers a step from fromVersion to fromVersion + 1. fn(data) may mutate and/or return the data.

Applies steps using data.version (missing → 0) and updates it. Stops with a warning if a step is missing.

MF.Migration.register("UILayouts", 1, data => {
    data.themes = data.themes || {};
    return data;
});
MF.Migration.migrate("UILayouts", { version: 1 }, 2);  // { version: 2, themes: {} }

MF.History

Undo/Redo stack. Extends EventEmitter and emits "change" on every modification.

A command is { label?, do(), undo(), merge?(next) }. merge may absorb the next command (e.g. consecutive drag steps) and return true; commands are never merged across a save point.

const history = new MF.History(100);   // depth limit

history.execute({
    label: "move",
    do()   { win.x = 100; },
    undo() { win.x = 0; }
});

history.beginBatch();
/* several history.execute(...) */
history.endBatch("align");             // one undo entry

history.undo(); history.redo();
history.canUndo(); history.canRedo();
history.markSaved(); history.isDirty();
history.clear();
history.on("change", updateToolbar);

MF.Document experimental

The editor workflow in one object: History (undo/redo) + Schema (validation before writing) + FS (atomic save with backup) + Data (runtime global) + Migration. A UI editor edits a document instead of wiring these modules by hand.

const doc = new MF.Document({
    path: "data/UILayouts.json",        // file to edit
    global: "$dataUILayouts",           // MF.Data global, updated on save
    schema: layoutSchema,               // validated on load (defaults) and before save
    version: 1, migrationKey: "UILayouts",
    initial: () => ({ version: 1, scenes: {} }),
    historyLimit: 200,
    autosave: false                     // or debounce time in ms
}).load();

// Dragging: every frame sets x; one undo step thanks to the merge key
drag.onMove = c => doc.set("scenes.Scene_Menu.windows._goldWindow.x", baseX + c.dx, { merge: "drag-gold" });

doc.transaction("Align left", d => {
    d.set("scenes.Scene_Menu.windows._goldWindow.x", 0);
    d.set("scenes.Scene_Menu.windows._commandWindow.x", 0);
});

if (MF.Input.isShortcut("Mod+Z")) doc.undo();
if (MF.Input.isShortcut("Mod+S")) {
    const r = doc.save();
    if (!r.ok) showErrors(r.reason, r.errors || r.error);
}

Loading

load() reads, in order: the file (NW.js) → the runtime global (browser; ignored if it holds only the default) → initial(). Then migration and schema normalization (defaults) are applied and the history is cleared.

Methods

Properties: data, loadError, history, path, global, schema. Events: load (data, loadError), change (path, value), dirty (isDirty), save (data), saveFailed (reason, details).

MF.I18n

Namespaced translations. Keys are "namespace:path.to.key".

MF.I18n.register("MF_QuestLog", {
    en: {
        title: "Quests",
        greet: "Hello, {name}!",
        count: { zero: "No quests", one: "{count} quest", other: "{count} quests" }
    },
    ru: {
        title: "Задания",
        count: { one: "{count} задание", few: "{count} задания", many: "{count} заданий", other: "{count} задания" }
    }
});

const t = MF.I18n.translator("MF_QuestLog");
t("title");                   // "Задания" (locale ru-RU)
t("count", { count: 5 });     // "5 заданий"
t("greet", { name: "Reid" }); // "Hello, Reid!" — falls back to en
MF.I18n.t("MF_QuestLog:title");

Locale

Current locale, by priority: setLocale() → player choice saved in config (MF_Core.locale) → $dataSystem.locale → browser language → fallbackLocale ("en"). Locale names are normalized: ru_RU → ru-RU.

Lookup chain: ru-RU → ru → en.

Plural forms

If the value is an object and params.count is a number, the form is chosen with Intl.PluralRules of the matched locale (zero, one, two, few, many, other). zero is used for 0 when present; other is the fallback.

MF.Text

Extends RPG Maker's text system (all windows using drawTextEx, including Window_Message) with custom escape codes, plus Promise-based messages for visual-novel style plugins.

Built-in codes

Custom codes

Names are letters only (RPG Maker parses codes as [A-Z]+) and cannot be the reserved V N P G C I PX PY FS.

Text replacement before RPG Maker's conversion, so the result may contain \C[n], \V[n] and other macros (expanded up to 10 levels). Parameters cannot contain ].

MF.Text.registerMacro("QUEST", id => MF.Save.get("MF_QuestLog").quests[id]?.title || "???");
// "Current quest: \QUEST[q1]"

Executed while the text is processed. ctx: { code, param, args, textState, window, drawing, isMessage }.

MF.Text.registerEscape("SHAKE", ctx => {
    if (!ctx.drawing || !ctx.isMessage) return;        // no side effects while measuring text!
    $gameScreen.startShake(Number(ctx.args[0]) || 5, 5, 20);
});
// "Watch out!\SHAKE[7] The ground trembles."

Messages as Promises

Need a scene with a message window (map, battle). A running message is awaited first.

await MF.Text.show("Where am I?", { face: ["Actor1", 0], speaker: "Reid" });
const answer = await MF.Text.choice(["Stay", "Leave"], { text: "What now?", cancel: 1 });
if (answer === 1) await MF.Text.show("Let's go.");

Utilities

MF.Input

A layer over RPG Maker's Input and TouchInput. Updated once per frame right after RPG Maker reads input.

Actions

MF.Input.bind("journal", { keys: ["j"], buttons: [8] });   // J key, gamepad "back"
if (Input.isTriggered("journal")) SceneManager.push(Scene_Journal);
if (MF.Input.isReleased("journal")) { … }

Raw keys and shortcuts

Raw keys use KeyboardEvent.code ("KeyZ", "Digit1", "F5", "ControlLeft") — independent of keyboard layout and of Input.keyMapper. Intended for editors and debug tools.

if (MF.Input.isShortcut("Mod+Z")) doc.undo();          // Ctrl+Z, Cmd+Z on macOS
if (MF.Input.isShortcut("Mod+Shift+Z")) doc.redo();
if (MF.Input.isShortcut("Delete")) removeSelected();

Pointer

Drag-and-drop experimental

let base;
const handle = MF.Input.draggable(window, {
    onStart: () => (base = { x: window.x, y: window.y }),
    onMove: c => { window.x = base.x + c.dx; window.y = base.y + c.dy; },
    onEnd: () => saveLayout(),
    onCancel: () => { window.x = base.x; window.y = base.y; },   // right click during drag
    onClick: () => select(window)
});

Handle: destroy(), setEnabled(bool), isDragging(). Destroyed targets are removed automatically.

Devices

MF.Ticker

Per-frame runner used by MF.Tween and MF.Timer. It ticks once per game frame (60 fps) after the scene update, only while the scene is started and the game window is active — animations pause together with the game.

Return false from fn to stop. A throwing callback is logged and removed.

Also: frame (counter), count(), clear(), update() (called automatically).

MF.Tween

Animates numeric properties. Durations are in frames (60 = 1 second). Property names may be paths ("scale.x"). Tweens are awaitable: they resolve true on completion and false when stopped or cancelled by a scene change.

await MF.Tween.to(sprite, { x: 400, opacity: 0 }, { duration: 30, easing: "easeOutQuad" });

MF.Tween.from(window, { y: -200 }, { duration: 20, easing: "easeOutBack" });
MF.Tween.fromTo(sprite, { "scale.x": 0 }, { "scale.x": 1 }, { duration: 15 });
MF.Tween.value(0, 100, { duration: 60 }, v => gauge.setRate(v / 100));

const pulse = MF.Tween.to(icon, { opacity: 128 }, { duration: 20, repeat: -1, yoyo: true });
pulse.stop();

Options

Instance

Static

Non-numeric properties are skipped with a warning. Tweens of destroyed PIXI objects stop automatically.

Sequences

async function intro(sprite) {
    await MF.Tween.to(sprite, { opacity: 255 }, { duration: 20 });
    await MF.Timer.wait(30);
    await Promise.all([
        MF.Tween.to(sprite, { x: 200 }, { duration: 30 }),
        MF.Tween.to(sprite, { "scale.x": 2, "scale.y": 2 }, { duration: 30 })
    ]);
}

MF.Timer

MF.Queue

Runs tasks one after another. A task is a function returning a value, a Promise or a Tween.

const queue = new MF.Queue();
queue.add(() => MF.Tween.to(actorSprite, { x: 300 }, { duration: 40 }), "walk");
queue.add(() => MF.Timer.wait(20));
queue.add(() => $gameScreen.startFlash([255, 255, 255, 170], 30));
queue.on("empty", () => console.log("cut-scene finished"));

MF.Layout experimental

Applies Units + Anchor layout to display objects, so plugins don't call Anchor.toAbsolute by hand in every window.

Layout spec

Container

A layout is resolved against, in order: an explicit container (setLayoutContainer), the parent's layoutInnerSize(), a window's inner area (for objects added with addInnerChild), a parent window's size, or the UI area Graphics.boxWidth × boxHeight. Objects re-layout automatically when added to a parent, and a parent refreshes its laid-out children.

Functions

Instance methods (after mixin)

setLayout(spec, merge = false), getLayout(), hasLayout(), setLayoutContainer(sizeOrFn), layoutContainerSize(), layoutInnerSize(), layoutRect(), refreshLayout(); windows also layoutRows().

// Add layout to a built-in window class
MF.Layout.mixinWindow(Window_Gold.prototype);
scene._goldWindow.setLayout({ anchor: "bottom-right", x: -8, y: -8, width: 240, height: "auto", rows: 1 });

MF.UI experimental

Base classes with layout built in. They use MZ-style constructors, so they are subclassed the usual MZ way.

Window_Base with layout. Override refresh() to draw; it is called after every resize.

function Window_QuestInfo() { this.initialize(...arguments); }
Window_QuestInfo.prototype = Object.create(MF.UI.Window.prototype);
Window_QuestInfo.prototype.constructor = Window_QuestInfo;

Window_QuestInfo.prototype.refresh = function() {
    MF.UI.Window.prototype.refresh.call(this);
    this.drawText(t("title"), 0, 0, this.innerWidth, "center");
};

const win = new Window_QuestInfo({ anchor: "bottom", y: -20, width: "60%", height: "auto", rows: 2 });
this.addWindow(win);

Sprite with layout and fit modes. Re-layouts when the bitmap finishes loading.

const logo = new MF.UI.Sprite(ImageManager.loadPicture("Logo"),
    { anchor: "top", y: 40, width: "50%", height: 120, fit: "contain" });

Invisible sized group (default: full container). Children resolve their layouts inside it.

const panel = new MF.UI.Container({ anchor: "center", width: 400, height: 300 });
panel.addChild(new MF.UI.Sprite(bitmap, { anchor: "top-right" }));

MF.Assets

Batch preloading for cut-scenes and heavy UI: parallel loading with a concurrency limit, progress reporting, and failures that are reported instead of crashing the game.

const task = MF.Assets.load([
    "picture:Cutscene_BG", "picture:Cutscene_Hero", "face:Actor1",
    { type: "se", name: "Thunder", static: true },
    { type: "bgm", name: "Theme3" },
    { type: "json", url: "data/Cutscene1.json" }
], {
    concurrency: 6,
    group: "cutscene1",
    onProgress: (p, item) => loadingBar.setRate(p)
});

const { ok, failed } = await task;
if (!ok) console.warn("missing:", failed.map(f => f.item.name));

Item types

Task

Functions

MF.Registry 1.2.0

Named registries for extension points: button actions, element types, condition types of your own plugin. Other plugins add entries without patching your code.

const actions = MF.Registry.define("MF_QuestLog.actions", {
    validate: value => typeof value === "function"   // false → entry rejected with an error
});
const remove = actions.add("openLog", () => SceneManager.push(Scene_QuestLog), "MF_QuestLogAddon");
actions.get("openLog")();
actions.on("add", (id, value, owner) => { /* rebuild menus */ });

MF.Services 1.2.0

A plugin publishes an API under a name and a version; other plugins use it if it is present. No load-order or hard require is needed for optional integrations.

// MF_QuestLog
MF.Services.provide("quest", { start, isDone }, { version: "1.0.0", owner: "MF_QuestLog" });

// Another plugin — optional integration
const quest = MF.Services.use("quest", "1.0.0");   // null if missing or older
if (quest) quest.start("q1");

// Any load order
MF.Services.when("quest").then(api => api.start("q1"));

MF.Notetag 1.2.0

Notetag parsing with a cache (by note text). Tag names are case-insensitive, tags may repeat.

<Price: 120>          → 120
<Unique>              → true
<Element: fire, ice>  → "fire, ice" / ["fire", "ice"] with type "list"
<Description>         block: the text between the tags
Line 1
Line 2
</Description>

MF.Notetag.get($dataItems[5], "Price", { type: "number", default: 0 });
MF.Notetag.getAll(item, "Element", { type: "list" });          // [["fire", "ice"], ...]
MF.Notetag.get(event, "Loot", { type: "json", default: [] });  // Game_Event → event note
MF.Notetag.sum(battler, "CritBonus");                          // actor + class + equips + states

MF.GameEvents 1.2.0

Standard game events on MF.Events.bus with the game: prefix, so plugins do not hook the same MZ methods. Change events (switches, variables, gold, items, level, states) do no extra work while nobody listens.

const off = MF.GameEvents.on("variableChanged", (id, value, old) => { ... });
MF.GameEvents.onScene(this, "goldChanged", this.refreshGold);   // this = scene; removed on terminate
MF.Events.bus.on("game:battleEnd", result => { ... });           // same event

Functions: on, once, emit (your own game:* events), onScene(scene, name, fn, context = scene).

MF.Commands 1.2.0

Plugin commands with typed arguments. A handler that returns a Promise makes the event wait for it — no manual setWaitMode.

MF.Commands.register("MF_QuestLog", "StartQuest", async function(args) {
    // this — Game_Interpreter (null when called from code)
    await MF.Text.show(`Quest ${args.id} started`);
}, {
    id:    { type: "string", required: true },
    stage: { type: "integer", default: 0 }     // "3" → 3
});

await MF.Commands.call("MF_QuestLog", "StartQuest", { id: "q1" });

MF.Options 1.2.0

Adds entries to Scene_Options without patching Window_Options in every plugin. Values are MF.Config keys (registered automatically); the options window grows with the entries.

MF.Options.add({ key: "MF_QuestLog.tracker", label: "Quest tracker", type: "boolean", default: true });
MF.Options.add({ key: "MF_Hud.scale", label: "MF_Hud:options.scale", type: "number",
                 min: 50, max: 150, step: 10, default: 100, format: v => v + "%" });
MF.Options.add({ key: "MF_Hud.position", label: "HUD", type: "list",
                 values: [{ value: "top", label: "Top" }, { value: "bottom", label: "Bottom" }] });

MF.Config.get("MF_QuestLog.tracker");   // read the value anywhere

Also: remove(key), list(), symbol(key) (command symbol "mf:" + key). Changes emit mf:configChanged; MZ saves the config when the options scene closes.

MF.Modifiers 1.2.0

Stacking modifiers instead of competing hooks. Every plugin adds a function; they run in priority order (lower first, then registration order). A non-number result is ignored for numeric stats; errors are logged and skipped.

const off = MF.Modifiers.add("param", (value, { battler, paramId }) =>
    paramId === 2 && battler.isStateAffected(10) ? value * 1.25 : value,
    { owner: "MF_Rage", priority: 100 });

MF.Modifiers.add("skillMpCost", (cost, { skill }) => skill.stypeId === 1 ? cost / 2 : cost);
const dmg = MF.Modifiers.apply("myDamage", base, { target });   // your own stat

Functions: add(stat, fn, { priority, owner }) → remove function, apply(stat, value, ctx), has(stat), list(stat?). Without modifiers the built-in stats return the MZ value unchanged.

MF.Random 1.2.0

const rng = MF.Random.create("dungeon-42");   // same seed → same sequence
rng.int(1, 6); rng.chance(0.1); rng.pick(list); rng.shuffle(list);
rng.weighted([{ id: 1, weight: 5 }, { id: 2, weight: 1 }]);

MF.Random.stream("loot").int(1, 100);   // state stored in the save: no save-scumming
MF.Random.int(1, 6);                    // Math.random with the same helpers

Versioning policy

MF_Core follows Semantic Versioning. Several plugins are developed against it in parallel, so a silent change to any public function breaks all of them at once. The rules below are mandatory.

Deprecation lifecycle

Like PIXI, MF_Core never removes or incompatibly changes an API in one step:

1. Replace. The new API is added. The old name keeps working and redirects to the new implementation through MF.Deprecation, printing a one-time warning.
2. Announce. The changelog lists the old API under Deprecated with the since and removeIn versions.
3. Remove. Only in the announced MAJOR release, listed under Removed ⚠ BREAKING. At least one MINOR release separates steps 1 and 3.

// Hypothetical MF_Core 1.1.0: Utils.oldName renamed to Utils.newName
MF.Utils.newName = function(...) { ... };
MF.Deprecation.method(MF.Utils, "oldName", {
    id: "MF.Utils.oldName", since: "1.1.0", removeIn: "2.0.0",
    replacement: "MF.Utils.newName", fn: MF.Utils.newName
});
// Console (once): [MF_Core] MF.Utils.oldName is deprecated since MF_Core 1.1.0
//                 and will be removed in 2.0.0. Use MF.Utils.newName instead.

Dependent plugins

• Declare the minimum MF_Core version the plugin was written against: register(name, version, { requires: { MF_Core: "1.0.0" } }). A bare require("…", "MF_Core") without a version logs a warning.
• State the same version in @help: Requires: MF_Core 1.0.0+ (written against 1.0.0).
• If the installed MF_Core has a higher MAJOR version than required, a one-time compatibility warning is logged.
• During development, check MF.Deprecation.list() — it shows every deprecated API the running plugins still use.

Changelog

Every public API change is recorded in CHANGELOG.md in the same commit, tagged Added, Changed, Deprecated, Removed ⚠, Breaking ⚠, Experimental change or Fixed.

Compatibility of 1.2.0 with 1.1.0

No function was removed or renamed; every 1.1.0 signature works as before. Changes of existing behavior:

New MZ hooks (all through MF.Hook, calling the original): Game_Switches/Game_Variables.setValue, Game_Party.gainGold/gainItem, Game_Actor.changeExp, Game_Battler.addState/removeState, Game_BattlerBase.param/xparam/sparam/skillMpCost/skillTpCost, BattleManager.startBattle/startTurn/endTurn/endAction/endBattle/makeRewards, Game_Map.setup, Game_Player.performTransfer, Game_Event.start, Game_Message.add, Game_Interpreter.updateWait/clear, Window_Options, Scene_Options.maxCommands, Scene_Base.terminate, DataManager.setupNewGame. Without listeners, modifiers or options they return the original results. A plugin below MF_Core that replaces one of these methods without calling the original disables only the matching new feature.

Save files: a new key MF_Core.random appears in contents.mf. Saves are readable by 1.1.0 (unknown keys are kept as orphans), and 1.1.0 saves load in 1.2.0.

1.2.1 adds two engine performance hooks (through MF.Hook, calling the original, results unchanged): ColorManager.textColor (cached per loaded windowskin; a plugin that draws into the windowskin bitmap at runtime should assign a new bitmap to ColorManager._windowskin) and Bitmap.prototype.drawText (missing align → "start").

Bus events

Emitted on MF.Events.bus:

Error handling summary

Changelog

The full changelog with Breaking / Deprecated markers is in CHANGELOG.md. Summary:

1.2.1 — 2026-09-26

• Fixed: performance — ColorManager.textColor results cached per windowskin (no getImageData per \C[n]); Bitmap.drawText without align uses "start" instead of the invalid undefined (no CanvasTextAlign warnings). Rendering unchanged.

1.2.0 — 2026-09-25

• Added: MF.Registry, MF.Services, MF.Notetag, MF.GameEvents, MF.Commands, MF.Options, MF.Modifiers, MF.Random; options.scene for Ticker / Tween / Timer.
• Changed: parseParams keeps leading-zero strings; Script evaluates multi-line code as an expression first. See compatibility.
• Fixed: Text.wrap freeze and CRLF, Units warning spam, History.isDirty and nested batches, shortcut modifiers, double loading.

1.1.0 — 2026-09-23

• Added: MF.Units functions (min, max, clamp, lerp, angle, atan2d, sind, …), constants, ^, comparisons, && || !, ? :; Units.FUNCTIONS, Units.CONSTANTS, Units.arity. Changed: clearer MF.Units error messages. Backward compatible.

1.0.0 — 2026-09-23

• Initial release. Foundation: Core, Log, Utils, Math, Units, Anchor, Color, Hook, Events, Deprecation, Schema. Game logic: Condition, Script. Storage: FS, Data, Save, Config, Migration, History, Document experimental. Text: I18n, Text. Input: Input (drag-and-drop experimental). Time: Ticker, Tween, Timer, Queue. Display and resources: Layout experimental, UI experimental, Assets.