Files
factorio-clusterio/packages/lib/src/plugin.ts
T
bbassieandClaude Opus 5.5 bf33f4f52e Refuse to start without required mods and download them
requiredMods entries are now Factorio dependency strings, and a mod
listed twice gives a version range. The plugin loader validates them.

The host refuses to start an instance whose mod pack is missing a
required mod of a loaded plugin, has it disabled or has it outside the
version range.

On start the controller resolves the required mods of its plugins and
their dependencies for the default mod pack's Factorio version and
downloads the ones missing from the mod store. The resolver and portal
download move from the ControlConnection handlers into Controller
methods so both paths share them.

Subspace Storage requires subspace_storage >= 1.99.0, and the
integration tests build a stub of that mod for the test mod pack.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 15:19:05 +00:00

176 lines
5.0 KiB
TypeScript

/**
* Plugin interfaces and utilities.
* @module lib/plugin
*/
import type { Static } from "@sinclair/typebox";
import type { Logger } from "./logging.js";
import type { ConfigSchema, FieldDefinition } from "./config/index.js";
import type { PermissionDefinition } from "./permissions.js";
import type { PlayerStats, Role } from "./data/index.js";
import type { SyncHook } from "./SyncHook.js";
import type { ErrorClass } from "./link/index.js";
import { ModDependency } from "./data/ModInfo.js";
export const PluginFeatureFlags = [
/** The plugin requires module code to be patched into the save */
"SavePatching",
/** The plugin requires access to script commands over rcon */
"ScriptCommands",
/** The plugin requires UDP messaging with the Factorio server */
"LuaUdp",
] as const;
/** Used to define the plugin export in plugins */
export type PluginDeclaration = {
name: string;
title: string;
description?: string;
controllerEntrypoint?: string;
controllerConfigFields?: Record<string, FieldDefinition>;
hostEntrypoint?: string;
hostConfigFields?: Record<string, FieldDefinition>;
instanceEntrypoint?: string;
instanceConfigFields?: Record<string, FieldDefinition>;
ctlEntrypoint?: string;
webEntrypoint?: string;
ctlConfigFields?: Record<string, FieldDefinition>;
migrationEntrypoint?: string;
features?: (typeof PluginFeatureFlags)[number][];
/**
* Factorio mods the plugin needs in the instance's mod pack, as Factorio
* dependency strings like `"subspace_storage >= 2.3.0"`.
*/
requiredMods?: string[];
messages?: any[];
errors?: ErrorClass[];
permissions?: PermissionDefinition[];
routes?: string[];
};
/**
* Check if a plugin is expected to ship a web build.
*
* Mirrors the rule used by the create tool: a web build is generated when the
* plugin has a web or controller entrypoint or defines config fields.
*/
export function pluginNeedsWebBuild(info: PluginDeclaration) {
return Boolean(
info.webEntrypoint
|| info.controllerEntrypoint
|| info.controllerConfigFields
|| info.hostConfigFields
|| info.instanceConfigFields
|| info.ctlConfigFields
);
}
/**
* Parse the requiredMods of a plugin
*
* A mod listed more than once must satisfy every entry, which gives a range.
*
* @throws Error if an entry is invalid or has a dependency prefix.
*/
export function pluginRequiredMods(pluginInfo: PluginDeclaration) {
return (pluginInfo.requiredMods ?? []).map(spec => {
const dependency = new ModDependency(spec);
if (dependency.type !== "required") {
throw new Error(`requiredMods entry "${spec}" can not have a dependency prefix`);
}
return dependency;
});
}
export type PluginNodeEnvInfo = PluginDeclaration & {
/**
* Path to the folder with the static files that should be hosted on the web
* server in order for the web interface to be able to load the plugin.
*/
webStaticPath: string;
/**
* Absolute path to the package.json file for the plugin.
*/
packagePath: string;
requirePath: string;
version: string;
manifest: any;
/**
* NPM package this plugin is published as. Not present if the package
* is private or the path used to load it does not match the name of the
* package.
*/
npmPackage?: string;
/**
* Directory of an npm package providing a plugin with the same name
* that was skipped on startup as this plugin was already in the list.
*/
skippedNpmPackage?: string;
};
export type PluginWebEnvInfo = PluginDeclaration & {
container?: any;
package?: any;
enabled?: boolean;
error?: string;
};
/**
* Information about the event.
*/
export interface PlayerEvent {
type: "join" | "leave" | "import" | "promote" | "demote" | "ban" | "unban" | "whitelisted" | "unwhitelisted";
/** Name of the player that caused the event */
name: string,
/**
* Only present for type "leave" and "ban". Reason for player leaving the
* game, one of the possible reasons in defines.disconnect_reason
* or "server_quit" if the server exits while the player is online.
* When type is "ban" this is the reason given for the ban.
*/
reason?: string;
/**
* Statistics recorded for this player on the instance this event
* originated from.
*/
stats: PlayerStats,
}
export type PluginLoadContext<
Context extends object,
Info extends PluginDeclaration = PluginNodeEnvInfo
> = Context & {
logger: Logger;
plugin: Info;
};
/** Hooks for migrating data that Clusterio stores on behalf of plugins */
export type MigrationHooks = {
controllerConfig: SyncHook<ConfigSchema>;
hostConfig: SyncHook<ConfigSchema>;
instanceConfig: SyncHook<ConfigSchema>;
role: SyncHook<Static<typeof Role.jsonSchema>>;
};
export type MigrationContext = PluginLoadContext<{ hooks: MigrationHooks }>;
export type PluginClass<
Context extends object,
Info extends PluginDeclaration,
> = {
new (...args: any[]): any;
fromContext(context: PluginLoadContext<Context, Info>): {
init(): Promise<void>;
detachHooks(): void;
};
};
export type PluginType =
Extract<keyof PluginDeclaration, `${string}Entrypoint`> extends `${infer P}Entrypoint` ? P : never;