MC2
MC² · Developers

Build a plugin.

Plugins add commands, sidebar tabs, Play screen cards, menu items and a settings page to MC², in plain JavaScript. One plugin runs on Mac and Windows.

API 2 JavaScript and HTML Mac and Windows

What a plugin can do

A plugin is a folder with a manifest.json. With only a manifest it can add note and link tabs to the sidebar. Give it a main.js and it becomes a code plugin that drives MC² through the mc2 object:

  • Commands in the ⌘K palette (Ctrl+K on Windows).
  • Sidebar tabs, Play screen cards and tabs inside a pack's page, each drawn from your own HTML.
  • Items in the right-click and ••• menus of packs, servers, worlds and mods.
  • Badges on sidebar items, and the app background.
  • A native settings page, drawn by MC² from your manifest.
  • Data and control: packs, mods, hosted servers, server status, keybinds, worlds, friends, the web, and storage of its own.
  • Events: launches, exits, crashes, log lines, mods, servers and friends.

Players approve every permission a plugin asks for before it runs, and every plugin listed in Browse has been reviewed by a person.

Your first plugin

The template uses every contribution point once: a command, an event, a sidebar tab, a Play screen card, a pack menu item and settings. It also ships types for editor autocomplete. Get it from pikzelperfekt/mc2-plugin-template.

  1. Copy the template into the plugins folder. In MC², Plugins › Folder opens it. Name the folder after your plugin's id.
  2. Set your id. In manifest.json, change id, name, author and repo. An id is 2 to 64 lowercase letters, digits and dashes, and it is also the folder name once installed.
  3. Turn on developer mode. Settings › Extensions › Plugins › Developer mode. Saving any file in the plugin's folder now reloads it within a second.
  4. Enable it. On the Plugins page, MC² shows its permissions and asks you to approve them, as it would ask a player.
  5. Try it. Press ⌘K and run Say hello, launch a pack, open the My Plugin tab, and find the Launches card on the Play screen.

Output from console.log, mc2.log and uncaught errors appears in the plugin console on the Plugins page.

main.jsthe smallest useful plugin
module.exports = {
  onload() {
    mc2.addCommand({
      id: "play-vanilla",
      name: "Play Vanilla",
      icon: "play.fill",
      callback() {
        // listInstances is synchronous in main.js, and needs "instances"
        const pack = mc2.listInstances().find((p) => p.name === "Vanilla");
        if (pack) mc2.launch(pack.id);   // needs "launch"
        else mc2.notify("No pack called Vanilla.");
      },
    });
  },
};

Files and folders

Where plugins live

Mac~/Library/Application Support/MC2/plugins/<id>/
Windows%APPDATA%\MC2\plugins\<id>\

Plugins › Folder opens it on either system. The same folder also holds approvals.json, MC²'s record of what each player approved. Leave it alone.

A plugin's folder

my-plugin/
  manifest.json     or plugin.json; plugin.json is read first if both exist
  main.js           optional; present means a code plugin
  panel.html        optional; any page your code names
  widget.html
  background.png
  • Keep it flat. Installs come from a GitHub release, whose files have no folders. A release asset with a path in its name is skipped.
  • Every path stays inside the folder. A file: that leads out of it, through ../, an absolute path, a backslash, a drive letter or a symlink, is refused.

manifest.json

manifest.json
{
  "id": "playtime-goals",
  "name": "Playtime Goals",
  "version": "1.0.0",
  "author": "you",
  "authorUrl": "https://github.com/you",
  "description": "A daily playtime goal, streaks, and a Play screen card.",
  "repo": "you/mc2-plugin-playtime-goals",
  "main": "main.js",
  "minAppVersion": "0.21.0",
  "permissions": ["storage", "ui"],
  "settings": [
    { "key": "goalMinutes", "type": "number", "label": "Minutes a day", "default": 60, "min": 5, "max": 720 }
  ],
  "tabs": [
    { "id": "wiki", "title": "MC Wiki", "icon": "book", "kind": "link", "url": "https://minecraft.wiki" }
  ]
}
FieldMeaning
idRequired. 2 to 64 lowercase letters, digits and dashes, starting with a letter or digit. It names the plugin's folder and keys its storage, settings and approvals, so never change it once published.
nameRequired. What players see.
versionmajor.minor.patch, such as 1.2.0. Review requires it.
author, authorUrlShown on the plugin's row.
descriptionOne line. Review warns without one.
repoowner/name on GitHub, used for Update. An install from GitHub fills it in if you leave it out.
mainThe JavaScript entry. Its presence makes a code plugin. Leave it out for a manifest-only plugin.
minAppVersionThe oldest MC² it runs on. An older MC² refuses to install it and says to update.
permissionsWhat the plugin may touch. See Permissions.
settingsSettings MC² draws for you. See Settings.
tabsSidebar tabs that need no code: kind is "link" with a url, or "note" with its text in content. Each takes an id, a title and an optional icon.
themesStill accepted, and review checks the files are in the release, but MC² no longer applies plugin palettes: the app has one look. Use mc2.setBackground instead.

Icons are SF Symbol names, such as gauge or arrow.down.circle. See Mac and Windows for how Windows draws them.

How a plugin runs

  • Its own hidden web view. Each code plugin's main.js runs in a page of its own, a WKWebView on the Mac and a WebView2 on Windows, apart from the app. A plugin stuck in a loop stalls only itself.
  • No network but mc2.fetch. The page's content policy refuses every load, so fetch, XMLHttpRequest, sockets, images and frames from the internet all fail, and peer connections are switched off. External <script src> files cannot load either: put your code in main.js.
  • A watchdog. MC² pings each plugin every 5 seconds. One that has not answered for 10 seconds shows as Not responding on the Plugins page, with a Disable button. It is never killed silently.
  • Nothing survives in the page. Keep state with mc2.storage, not localStorage: on the Mac the page's own web storage is discarded.

Lifecycle

Top-level code runs when the plugin loads. Then MC² calls onload, CommonJS style:

module.exports = {
  onload()   { /* register commands, listeners, cards */ },
  onunload() { /* clear your timers */ },
};
  • onunload runs when the plugin is switched off or reloaded (the Reload button, a permission change, a developer-mode save). It does not run when MC² quits, nor for a plugin marked Not responding, so save as you go.
  • Commands, tabs, cards, menu items, badges and the background a plugin added are removed for it on unload.
  • The app-load event fires once MC² has started.

Feature detection

mc2.apiVersion is 2, and missing on API version 1. A plugin that needs version 2 should say so once rather than throw:

if (!(mc2.apiVersion >= 2)) {
  mc2.notify("My Plugin needs a newer version of MC². Update MC² to use it.");
} else {
  module.exports = { onload() { /* ... */ } };
}

Errors

Value methods return Promises. A failure rejects with { code, message }:

codeWhen
"permission"The player has not granted the permission the call needs.
"not-found"No such pack, mod, server, world, section or file.
"bad-args"A missing or malformed argument.
"failed"The work itself failed: a download, a request, a server that cannot start.

Contribution calls (addWidget, addMenuItem and the rest) do not throw. A refused one writes its reason to the plugin console.

Permissions

Declare what the plugin needs in permissions. The player sees each one, with the text below, before the plugin runs.

PermissionPlayers readGrants
instancesRead instanceslistInstances, instances.*, pack events
launchLaunch the gamelaunch
uiNavigate the appopenSection, openURL, clipboard.write, addWidget, addInstanceTab, addMenuItem, setBadge
storageSave plugin datastorage.*, getData, setData
networkNetworkfetch, request
modsManage modsmods.*, mod events
serversControl serversservers.*, server events
keybindsChange keybindskeybinds.*
worldsRead worldsworlds.*
friendsSee friendsfriends.list, friend events
logsRead game logsgame-crash, log-line
appearanceChange the looksetBackground

Needing nothing: log, notify, addCommand, addTab, on for events that need nothing, and settings.*.

How consent works

  • Installing a plugin, or switching on one never approved, shows every permission it declares. Allow grants them all. Cancelling an install removes the plugin; cancelling a switch-on leaves it off.
  • A plugin gets what it declares and the player approved. mc2.permissions lists exactly that.
  • An update that declares a new permission keeps running with the old grants, shows Wants new permission on its row, and asks for only the new ones.
  • A plugin that declares no permissions installs without asking.
  • Removing a plugin forgets its approvals, so installing it again asks again.

Ask for the fewest you can. Review warns about a permission you declare and never use, and about a call that needs one you did not declare.

The mc2 API

mc2 is on window in main.js and in every tab and card. lodestone, the API's name before MC² was renamed, is the same object. Permissions are shown beside each call.

Core

mc2.apiVersion        // 2
mc2.pluginId          // "my-plugin"
mc2.version           // your manifest version (main.js only)
mc2.permissions       // what the player granted (main.js only)

mc2.log("text");       // the plugin console; console.log works too
mc2.notify("text");    // a toast

mc2.addCommand({ id, name, icon, callback });   // ⌘K / Ctrl+K palette. main.js only
mc2.on("instance-launch", (e) => {});        // see Events. main.js only

Calling addCommand again with the same id replaces the command. Plugin commands are listed after MC²'s own, by name.

Packs

mc2.listInstances();               // [instances] [{ id, name, version, loader }]
await mc2.instances.get(id);       // [instances] { id, name, version, loader, loaderVersion,
                                   //   group, lastPlayed, playtimeSeconds, memoryMB }
await mc2.instances.running();     // [instances] [{ id, pid, startedAt }], one per game window
mc2.launch(id);                    // [launch]
mc2.openSection("servers");        // [ui]
  • listInstances() answers at once in main.js, from a copy MC² refreshes whenever packs change. In a tab or card it returns a Promise. Without instances it returns an empty list.
  • loaderVersion, group, lastPlayed and memoryMB may be null. Dates are ISO 8601 text.
  • openSection takes home, instances, discover, servers, friends, locker, skins, game, settings (or preferences) and plugins.

Mods mods

await mc2.mods.list(instanceId);
// [{ id, name, version, enabled, source: "modrinth" | "curseforge" | "file", projectId }]
await mc2.mods.install(instanceId, { modrinth: "sodium" });   // { installed: [names] }
await mc2.mods.install(instanceId, { curseforge: 394468 });
await mc2.mods.remove(instanceId, modId);
await mc2.mods.setEnabled(instanceId, modId, false);
await mc2.mods.updates(instanceId);   // [{ id, name, current, latest }]
  • list returns mods only, not resource packs or shaders. Pass a mod's id to remove and setEnabled.
  • projectId is the Modrinth id, the CurseForge project number, or null for a file added by hand. version is the file name without .jar.
  • install takes a Modrinth slug or id, or a CurseForge project number, and picks the newest build for the pack's version and loader. Modrinth installs bring their required dependencies. A project the pack already has is updated in place: the new file arrives first, then the old one is deleted.
  • CurseForge installs fail with "failed" when CurseForge is unreachable, or when the author has switched off third-party downloads.
  • updates checks Modrinth mods only.

Servers servers

await mc2.servers.list();
// servers MC² hosts: [{ id, name, status, port, players }]
// status: "running" | "stopped" | "starting" | "stopping"
await mc2.servers.start(id);
await mc2.servers.stop(id);
await mc2.servers.status("play.example.net");
// { online: true, players, max, motd, version } or { online: false }
await mc2.servers.played();          // [{ name, address, instanceId }]
  • players is null unless the server is running and has answered a status check. A sleeping server reads as "stopped".
  • start fails with "failed" until the server's EULA has been accepted in MC².
  • status pings any address the way the game does, SRV records included.

Keybinds, worlds, friends

await mc2.keybinds.get();                         // [keybinds] { "key.jump": "key.keyboard.space", ... }
await mc2.keybinds.set("key.jump", "key.keyboard.space");  // [keybinds]

await mc2.worlds.list(instanceId);
// [worlds] [{ name, folder, lastPlayed, sizeBytes, mode }]
await mc2.worlds.backup(instanceId, folder);     // [worlds] into the pack's backups

await mc2.friends.list();
// [friends] [{ username, uuid, online, playing: { pack, server } | null }]
  • Keybinds are MC²'s global profile, applied to every pack's options.txt at launch. Actions and keys are letters, digits, dots, dashes and underscores, and keys start with key..
  • mode is lowercase: "survival", "creative", "hardcore" and so on. folder is what backup takes.
  • A friend's playing.server is always null for now: friends share only the pack.

The app ui

mc2.openURL("https://modrinth.com/mod/sodium");   // the default browser; http and https only
await mc2.clipboard.write("https://mclo.gs/abc");

Network network

const res = await mc2.fetch("https://api.example.com/x", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ hello: "world" }),
});
res.status;    // 200
res.headers;   // names in lower case
res.body;      // text; JSON.parse it yourself

// API 1, still supported: GET only, a callback, and a non-2xx answer is an error
mc2.request("https://api.example.com/x", (err, body) => {});
  • Methods: GET, POST, PUT, PATCH, DELETE, HEAD. A body that is not text is sent as JSON; GET and HEAD cannot carry one.
  • fetch resolves for any status, so check res.status. A response over 10 MB is refused, and requests time out after 30 seconds.
  • Public http and https addresses only. localhost, private and link-local ranges, Tailscale addresses, and .local, .lan and .internal names are refused.

Storage storage

await mc2.storage.set("state", { any: ["JSON", 1, true] });
await mc2.storage.get("state");   // the value, or null
await mc2.storage.set("state", null);   // deletes it
await mc2.storage.keys();

// API 1, still supported: text only, synchronous in main.js
mc2.setData("key", "value");
mc2.getData("key");

Storage belongs to one plugin and stays on the player's computer. storage and getData/setData are kept apart and never read each other's keys. Prefer mc2.storage: getData in main.js reads a copy taken at load, so it does not see what a tab saved since.

Events

Listen in main.js with mc2.on(name, fn). An event that needs a permission is only delivered when it is granted.

EventPayloadNeeds
app-loadnone
instance-launch{ id, name, version }
game-exit{ id, name, code, crashed, seconds }. crashed is a non-zero exit the player did not ask for.
game-crash{ id, name, summary, culprit, logTail }. summary is the Crash Doctor's headline, culprit the mod it blames or "", logTail the last 200 lines as one string.logs
log-line{ id, line }, at most 50 a second per gamelogs
instance-created, instance-removed{ id, name }instances
mod-installed, mod-removed{ instanceId, name }mods
server-start, server-stop{ id, name }servers
friend-online, friend-offline{ username, uuid }friends
theme-change{ id }, when the player picks a look
settings-change{ key, value }, only for your own settings

Adding to MC²

Everything here is drawn natively on both systems; only the body of a tab or card is your HTML. Call these from main.js, usually in onload. Calling one again with the same id replaces what it added.

// A sidebar tab. No permission.
mc2.addTab({ id: "dash", title: "Dashboard", icon: "gauge", file: "panel.html" });   // or html: "..."

// A card on the Play screen, below "Jump back in". 80 to 400 points tall.   [ui]
mc2.addWidget({ id: "today", title: "Playtime", file: "widget.html", height: 150 });

// A tab in a pack's page, after MC²'s own. Its page reads mc2.instanceId.   [ui]
mc2.addInstanceTab({ id: "notes", title: "Notes", icon: "note.text", file: "notes.html" });

// An item in the right-click and ••• menus.   [ui]
mc2.addMenuItem({
  id: "update-all",
  where: "instance",               // "instance" | "server" | "world" | "mod"
  title: "Update all mods",
  icon: "arrow.down.circle",
  callback(ctx) { /* ctx.instanceId */ },
});

// A badge on a sidebar item; null clears it.   [ui]
mc2.setBadge("instances", "3");

// The app background, from your folder; null removes it.   [appearance]
mc2.setBackground({ file: "background.png" });
MenuCallback receives
instance{ instanceId }
server{ serverId }
world{ instanceId, world }, where world is the folder name
mod{ instanceId, modId }
  • Ids are up to 128 characters. Titles are trimmed to 80 and fall back to the id.
  • A card's height defaults to 80 and is held to 80 to 400. MC² reserves it before the page loads, so nothing below the card moves.
  • A badge is up to 8 characters. It sits on home, instances, discover, servers, friends, game or settings. MC²'s own count on an item, such as Friends' requests, wins over it. A plugin can clear only its own badge.
  • A background is a png, jpg, webp, gif or heic in your folder, drawn under a wash of the app's ground colour so text stays readable.

Tabs and cards

A tab or card is your HTML in its own sandboxed web view. Bare HTML is wrapped in a themed page: the app's background (transparent in a card), its font, styled button, .card and code, and --accent set to the app's accent colour. Start the file with <!doctype html> to style it all yourself.

panel.html
<h1>Your packs</h1>
<div id="list"></div>
<script>
  async function render() {
    const packs = await mc2.listInstances();   // a Promise in a page
    for (const p of packs) {
      const b = document.createElement("button");
      b.textContent = p.name;
      b.onclick = () => mc2.launch(p.id);
      document.getElementById("list").appendChild(b);
    }
  }
  render();
</script>
  • The page's mc2 has the data API, storage, settings, notify, log, launch, openSection, setBadge and setBackground, every value method as a Promise and permission-checked the same way. getData resolves the value; request(url) resolves the body, or null when it failed.
  • Not in a page: on, addCommand, addTab, addWidget, addInstanceTab and addMenuItem. These belong to main.js.
  • Your own files load. Relative paths for scripts, styles, images, fonts and media resolve to your plugin's folder. Inline <script> and <style> work. Nothing loads from the internet.
  • A page cannot hear events or call main.js. Have main.js keep what the page shows in mc2.storage, and have the page read it every few seconds. Every first-party plugin works this way.
  • A tab in a pack's page reads the pack it is showing from mc2.instanceId; it is null everywhere else.

Settings

Declare settings in the manifest and MC² draws a settings page with its own controls, under Plugins › your plugin › Settings.

"settings": [
  { "key": "goalHours", "type": "number", "label": "Daily goal (hours)", "default": 2, "min": 0, "max": 24 },
  { "key": "loud",      "type": "toggle", "label": "Play a sound", "default": false },
  { "key": "mode",      "type": "choice", "label": "Mode", "options": ["Simple", "Detailed"], "default": "Simple" },
  { "key": "name",      "type": "text",   "label": "Display name", "default": "" }
]
const goal = await mc2.settings.get("goalHours");   // the player's value, or the default
const all = await mc2.settings.all();                // { goalHours: 2, loud: false, ... }
mc2.on("settings-change", ({ key, value }) => {});
  • Up to 40 settings. A key is up to 64 characters and appears once; a label defaults to the key.
  • An entry MC² cannot draw is dropped on its own: no key, an unknown type, a choice with no options, or a min above its max.
  • A number with both min and max no more than 1,000 apart is a slider, otherwise a field. Numbers are clamped to their range, a choice must be one of its options, and text is kept to 2,000 characters.
  • Change a range or the options in an update and any saved value that no longer fits reads as the default.
  • Settings need no permission, and pages read them too.

Mac and Windows

The same plugin runs unchanged on both. One engine decides every call on both systems, so permissions, arguments, answers and errors are identical. The differences are in the host:

MacWindows
Plugin runtimeWKWebViewWebView2
Plugins folder~/Library/Application Support/MC2/plugins%APPDATA%\MC2\plugins
Command palette⌘KCtrl+K
IconsAny SF SymbolMC²'s own drawings of about 300 SF Symbols. A name it has no drawing of shows that place's default icon.
Origin of your files in a pagemc2-plugin://files/https://mc2-plugin.example/

Use relative paths in pages and never write either origin into your code. Stick to common SF Symbol names (gauge, star, bolt, book, info.circle) and check how they look on Windows.

Testing

In MC²

  • Developer mode, Settings › Extensions › Plugins › Developer mode, checks plugin folders once a second. A changed script or page reloads that plugin; a changed manifest rescans every plugin. It is off by default.
  • The plugin console on the Plugins page shows console.log, mc2.log, uncaught errors, rejected Promises and refused calls. It keeps the last 400 lines.
  • Reload on the Plugins page restarts every plugin.

In Node

fake-mc2.mjs is a fake MC² for plain Node, in plugins/test/ of the MC² repository. It runs main.js unchanged against the whole API, enforces permissions the way the app does, fires events, and moves a fake clock.

import { loadPlugin, check } from "./fake-mc2.mjs";

const h = await loadPlugin("path/to/my-plugin", {
  instances: [{ id: "a", name: "Vanilla Beans", version: "1.21.4", loader: "fabric" }],
});
await h.emit("instance-launch", { id: "a", name: "Vanilla Beans", version: "1.21.4" });
await h.advance(60 * 60 * 1000);       // an hour, running any timers due
await h.runCommand("say-hello");
await h.runMenuItem("pack-info", { instanceId: "a" });
await h.changeSetting("count", false);   // also fires settings-change
check("it noticed", h.notifications.length === 1);

loadPlugin takes the world a test needs: instances, mods, modUpdates, hostedServers, serverStatus, playedServers, friends, storage, settings, a fetch handler, granted to test a refusal, and apiVersion: 1 to test feature detection. Afterwards read notifications, logs, errors, storage, commands, widgets, tabs, badges and callsTo(method). It reads manifest.json, so keep one under that name.

Publishing

  1. Push the plugin to a public GitHub repo. mc2-plugin-<id> is the convention.
  2. Make a GitHub Release whose assets are every file in the folder: manifest.json, main.js, your pages and images. The manifest asset must be named manifest.json. MC² installs the assets of the latest release, not the repo's files.
  3. Tag it with the version. Use the manifest's version in plain numbers, such as v1.2.0. MC² offers Update when the latest release's tag is newer than the installed version.
  4. Install it yourself. Use Plugins › Browse › Install from GitHub · Unreviewed with owner/repo. Anyone can install it this way, marked Unreviewed.
  5. Submit it for review. That is how it gets listed in Browse.

An install replaces the plugin's folder with the release's files, so never keep anything in the folder you need to survive an update. Storage and settings live elsewhere and are kept.

Review

Every plugin in Browse, and every update to it, was approved by a person. Approval pins the release's exact files by their SHA-256 hashes, and MC² refuses a file that does not match. A file changed after install makes the plugin unreviewed again.

Submitting

  1. Sign in to MC². Use the Minecraft account you will publish under: it is your creator identity.
  2. Prove the repo is yours. Add mc2-claim.txt to the root of the repo's default branch, containing your Minecraft UUID. MC² shows it, with a copy button, the first time you submit.
  3. Submit. Plugins › My plugins › Submit for review: the owner/repo and a release tag, or no tag for the latest release.
  4. Watch My plugins. Each submission reads In review, Approved, Changes requested with the reviewer's notes, or Rejected with the reason. MC² tells you when it moves.

Automated checks

These run before a person looks. An error refuses the submission at once, with the reason; a warning goes to the reviewer.

Check
Errorid is not 2 to 64 lowercase letters, digits or dashes (no underscores), or belongs to another creator
Errorname is missing, or version does not look like 1.2.3
ErrorAn unknown permission, or main or a themes file missing from the release
ErrorMore than 50 files, over 5 MB in all, a text file over 1 MB, or a file name other than letters, digits, ., _ and -
ErrorCode that cannot be read: a line over 1,000 characters, minified files, _0x names, long \x escape runs, atob on a large literal, eval( or new Function(, even in a comment
WarningNo description
WarningA call or event that needs a permission you did not declare, or a declared permission never used
Ship readable source.

No bundlers, minifiers or obfuscators. A reviewer has to be able to read every line, and the checks refuse code that looks generated.

Updates and takedowns

  • Each update is a new submission. Submitting again replaces one still waiting. The reviewer sees the diff against your last approved version, and players stay on that version until the update is approved.
  • A plugin found harmful can be taken down. MC² switches it off on every computer and shows the reason on its row.

Creators

  • Plugin Creator: an approved plugin.
  • Popular Creator: a plugin with 100 active players over 30 days, or in the top 10% of listed plugins.
  • Featured Creator: one of the month's top 3 by active players. The month's leaders are on Plugins.
  • Built in: a plugin with 500 active players over 30 days, or in the all-time top 10, may apply from My plugins to become part of MC², with your name on it.

Players are counted, never downloads: each MC² reports the plugins it has switched on at most once a day.

Limits

Plugin id2 to 64 of a-z, 0-9, -
Release50 files, 5 MB in all, 1 MB per text file, no folders
fetch10 MB per response, 30 second timeout, public http and https only
log-line50 lines a second per game
game-crash logTailThe last 200 lines
Card height80 to 400 points
Badge8 characters
Contribution id, title128 and 80 characters
Settings40 per plugin, 64-character keys, 2,000-character text
WatchdogPinged every 5 seconds, Not responding after 10
Plugin consoleThe last 400 lines

Examples of all of it in use: the four first-party plugins, Playtime Goals, Mod Updates, Server Pulse and Crash Share.