Plugins

List module paths in "plugins" in gameshipper.json. A plugin is one file, or a folder with a package.json main or an index.mjs:

export default {
  name: 'myplugin',
  // The game calls these as await gameshipper.plugins.myplugin.doThing(arg).
  // They run in Electron's main process with full Node.js access.
  main: { async doThing(arg) { return `did ${arg}`; } },
  // Optional build hooks.
  async beforePackage(ctx) { /* ctx.appDir, ctx.targets, ctx.config, ctx.log() */ },
  async afterPackage(ctx) { /* ctx.target, ctx.outDir, ctx.executable */ },
};

Plugin and function names use letters, digits and _, and no two plugins may share a name, even in different letter case. A single-file plugin is copied alone, so one that imports other files or packages gets a PLUGIN_IMPORTS_NOT_COPIED warning: bundle it into one file or make it a folder plugin. A folder plugin is copied with its node_modules, except:

• anywhere in it: .env and .env.* files, steam_appid.txt, .git, .DS_Store, Thumbs.db, and the Steamworks SDK (anything named steamworks_sdk*, redistributable_bin, or a folder holding a redistributable_bin/);
• at its top: every dot file and folder (.npmrc, .vscode, .github, ...) and out/;
• every node_modules/.bin.

Its main must be a packaged file inside the folder, and a link out of the folder (or to nothing, or into a loop) fails the build with PLUGIN_LOAD_FAILED. A plugin's files are never copied into the game itself. A failing beforePackage stops the build (PLUGIN_HOOK_FAILED), as does a hook still running after 5 minutes; a failing afterPackage fails that target. afterPackage runs before the Mac app is signed, so it may still change the app. The hooks run for desktop targets only. Only use plugins you trust: they run with the same rights as the game.

Each build and play loads plugins afresh. A process that stays running (such as an MCP server) picks up an edited ES module plugin's own entry file, but a CommonJS plugin, and any file a plugin imports, keeps its first-loaded code until that process restarts.