Merge pull request #787 from Cooldude2606/fix/plugin-template

Plugin templates no longer depend on a dev install of Clusterio

clean.js

@@ -81,7 +81,7 @@ async function removeExecutionArtifacts() {
  * Main function for this script
  */
 async function main() {
-	await yargs
+	await yargs(process.argv.slice(2))
 		.scriptName("clean")
 		.usage("$0 <command> [options]")
 		.option("dry", {

eslint.config.mjs

@@ -494,6 +494,7 @@ export default defineConfig([{
 	"rules": {
 		"node/no-missing-require": "off",
 		"node/no-missing-import": "off",
+		"@stylistic/indent": "off",
 		"spaced-comment": "off",
 		"comma-spacing": "off",
 		"max-len": "off",

packages/create/template.js

@@ -3,6 +3,8 @@ const { logger } = require("./logging");
 const fs = require("fs-extra");
 const path = require("path");
 
+const _package = require("./package.json");
+
 async function copyTemplateFile(src, dst, properties) {
 	logger.verbose(`Writing ${dst} from template ${src}`);
 
@@ -102,6 +104,7 @@ async function copyPluginTemplates(pluginName, templates) {
 		prepare.push("tsc --build");
 		files.set("tsconfig.json", path.join(templatePath, "tsconfig.json"));
 		files.set("tsconfig.node.json", path.join(templatePath, "tsconfig.node.json"));
+		files.set("tsconfig.base.json", path.join(templatePath, "tsconfig.base.json"));
 		if (webpack) {
 			files.set("tsconfig.browser.json", path.join(templatePath, "tsconfig.browser.json"));
 		}
@@ -139,7 +142,6 @@ async function copyPluginTemplates(pluginName, templates) {
 
 	// Files for lua modules
 	if (templates.includes("module")) {
-		files.set(".luacheckrc", path.join(commonPath, ".luacheckrc"));
 		files.set("module/module.json", path.join(commonPath, "module/module.json"));
 		files.set("module/control.lua", path.join(commonPath, "module/control.lua"));
 		files.set("module/module_exports.lua", path.join(commonPath, "module/module_exports.lua"));
@@ -147,7 +149,6 @@ async function copyPluginTemplates(pluginName, templates) {
 			files.set("module/globals.lua", path.join(commonPath, "module/globals.lua"));
 		} else {
 			files.set(`instance.${ext}`, path.join(templatePath, `instance_empty.${ext}`));
-			pluginContexts += 1;
 		}
 	}
 
@@ -164,18 +165,25 @@ async function copyPluginTemplates(pluginName, templates) {
 
 	// Properties that will control the replacements in the templates
 	const properties = {
-		config: config,
+		// Weather this is ts or js
 		typescript: !javascriptOnly,
+		ext: ext,
+		// Which templates where requested
+		multi_context: pluginContexts > 1,
 		controller: templates.includes("controller"),
 		host: templates.includes("host"),
 		instance: templates.includes("instance"),
 		module: templates.includes("module"),
 		ctl: templates.includes("ctl"),
 		web: templates.includes("web"),
-		multi_context: pluginContexts > 1,
-		plugin_name: pluginName,
+		// Macro flags for context requirements
+		webpack: webpack,
+		config: config,
+		// String values for package json
+		clusterio_version: _package.version,
+		node_version: _package.engines.node,
 		prepare: prepare.join(" && "),
-		ext: ext,
+		plugin_name: pluginName,
 	};
 
 	// Write all the template files

packages/create/templates/common/.gitignore

@@ -1,3 +1,2 @@
-dist/
 node_modules/
-package-lock.json
+dist/

packages/create/templates/common/.npmignore

@@ -1,3 +1,3 @@
 webpack.config.js
-dist/web/build
 dist/browser
+dist/web

packages/create/templates/common/module/control.lua

@@ -1,3 +1,14 @@
+--[[
+The 'control' file within factorio is used as the entry point for mods, in Clusterio this is only a convention
+You can change which files are loaded (exports event handlers) and required (no events) by Clusterio within module.json
+It is highly advised to use FMTK (justarandomgeek.factoriomod-debug) when writing Lua code for factorio
+Most of your code will be within this one file, but you can create more and require them
+
+clusterio_api exposes functions to enable communication with your InstancePlugin 
+compat exposes shims to simplify compatibly between factorio versions, use the following to require 2.0
+`assert(compat.version_ge("2.0.0"), "__plugin_name__ requires factorio 2.0")`
+]]
+
 local clusterio_api = require("modules/clusterio/api")
 local compat = require("modules/clusterio/compat")
 
@@ -6,10 +17,12 @@ local compat = require("modules/clusterio/compat")
 local MyModule = {
 }
 
---- script_data is 'synced' between players, you should use your plugin name to avoid name conflicts
--- The following helper function is desync safe and avoids name conflicts after being called during on_server_startup
--- There are edge cases in the following events: pre player left, player left, console command, and config changed
--- If you use any of these events and access globalData then make sure to call this function first
+--[[
+`compat.script_data` persists between restarts and is shared between modules, therefore you should use your plugin name to avoid conflicts
+The following helper function is desync safe and avoids name conflicts after being called during `clusterio_api.events.on_server_startup`
+There are edge cases in the following events: pre player left, player left, console command, and config changed
+If you use any of these events and access `script_data` then make sure to call this function first
+]]
 local script_data = {}
 local function setup_script_data()
 	if compat.script_data["__plugin_name__"] == nil then
@@ -28,12 +41,13 @@ end
 
 --- Public methods should be available though your top level module table
 function MyModule.foo()
-	game.print("foo")
+	game.print("foo: " .. (script_data.counter or 0))
 end
 
 --- Private methods should be local to the file, this will prevent others from calling it
 local function bar()
-	game.print("bar")
+	script_data.counter = (script_data.counter or 0) + 1
+	game.print("bar: " .. script_data.counter)
 end
 
 --- Clusterio provides a few custom events, on_server_startup is the most useful and should be used in place of on_init
@@ -61,7 +75,7 @@ local function on_nth_tick_300()
 	bar()
 end
 
---- Factorio events are accessible through defines.events, you can have one handler per event per module
+--- Factorio events are accessible through defines.events, you can have one handler per event per file
 local e = defines.events
 local events = {
 	[clusterio_api.events.on_server_startup] = on_server_startup,
@@ -73,7 +87,7 @@ local on_nth_tick = {
 	[300] = on_nth_tick_300,
 }
 
---- Always return the top level module table from control, this is how clusterio will access your event handlers
+--- Always return the top level module table from control, this is how Clusterio will access your event handlers
 MyModule.events = events --- @package
 MyModule.on_nth_tick = on_nth_tick --- @package
 return MyModule

packages/create/templates/common/module/globals.lua

@@ -1,3 +1,9 @@
---- Expose any globals here, typically just your control file if you want to access it through rcon or commands
--- luacheck: globals __plugin_name__
+--[[
+It is best practice to not expose any globals because all modules share a global environment
+However, sometimes you need globals, for example to access functions within rcon commands
+Therefore, we advise that this should be the only file in your module to expose globals
+Typically this would be your control file as shown in the example below
+]]
+
+-- Access using `/sc __plugin_name__.foo()`
 __plugin_name__ = require("modules/__plugin_name__/control")

packages/create/templates/common/module/module_exports.lua

@@ -1,4 +1,8 @@
---- Can contain anything you want to allow other plugins to have access to, this example exposes the control file
---- If you only export a single file then it may be better to rename that file to module_exports and save the redirection
--- Access the exports from other modules using require("modules/__plugin_name__")
+--[[
+It is typical for a module to have a control file as the entry point, although this is not a requirement
+Therefore, Clusterio allows you to specify a single default export that can be accessed by other modules
+You are not required to specify any default export, but note that a module can still require yours directly
+]]
+
+-- Access using `local __plugin_name__ = require("modules/__plugin_name__")`
 return require("modules/__plugin_name__/control")

packages/create/templates/common/package.json

@@ -12,10 +12,10 @@
 		"prepare": "__prepare__"
 	},
 	"engines": {
-		"node": ">=18"
+		"node": "__node_version__"
 	},
 	"peerDependencies": {
-		"@clusterio/lib": "workspace:*"
+		"@clusterio/lib": "^__clusterio_version__"
 	},
 	"devDependencies": {
 //%// Typescript and type declarations
@@ -32,13 +32,13 @@
 		"react": "^18.2.0",
 		"react-dom": "^18.2.0",
 //%endif
-//%if web | controller // The controller uses webpack even when there is no plugin code
+//%if webpack
 		"webpack": "^5.88.2",
 		"webpack-cli": "^5.1.4",
 		"webpack-merge": "^5.9.0",
-		"@clusterio/web_ui": "workspace:*",
+		"@clusterio/web_ui": "^__clusterio_version__",
 //%endif
-		"@clusterio/lib": "workspace:*"
+		"@clusterio/lib": "^__clusterio_version__"
 	},
 	"dependencies": {
 		"@sinclair/typebox": "^0.30.4"

packages/create/templates/common/webpack.config.js

@@ -18,9 +18,7 @@ module.exports = (env = {}) => merge(common(env), {
 			exposes: {
 				"./": "./index.__ext__",
 				"./package.json": "./package.json",
-//%if web
 				"./web": "./web/index.__ext__x",
-//%endif
 			},
 			shared: {
 				"@clusterio/lib": { import: false },

packages/create/templates/plugin-js/controller.js

@@ -1,7 +1,7 @@
 "use strict";
 const lib = require("@clusterio/lib");
 const { BaseControllerPlugin } = require("@clusterio/controller");
-//%if multi_context // Subscribing requires multi context
+//%if multi_context // Messages requires multi context
 
 const {
 	PluginExampleEvent, PluginExampleRequest,
@@ -9,7 +9,7 @@ const {
 //%if controller & web // Subscribing requires web content and the controller
 	ExampleSubscribableUpdate, ExampleSubscribableValue,
 //%endif
-//%if multi_context // Subscribing requires multi context
+//%if multi_context // Messages requires multi context
 } = require("./messages");
 //%endif
 
@@ -26,7 +26,8 @@ class ControllerPlugin extends BaseControllerPlugin {
 //%endif
 //%if controller & web // Subscribing requires web content and the controller
 		this.controller.subscriptions.handle(ExampleSubscribableUpdate, this.handleExampleSubscription.bind(this));
-		this.exampleDatabase = new Map(); // If needed, replace with loading from database file
+		// If needed, replace with loading from database file such as lib.Datastore
+		this.exampleDatabase = new Map([["foo", new ExampleSubscribableValue("foo", 0, false)]]);
 //%endif
 //%if multi_context // Subscribing requires multi context
 	}
@@ -70,6 +71,7 @@ class ControllerPlugin extends BaseControllerPlugin {
 //%if controller & web // Subscribing requires web content and the controller
 
 	async handleExampleSubscription(request) {
+		this.logger.info(JSON.stringify(request));
 		const values = [...this.exampleDatabase.values()].filter(
 			value => value.updatedAtMs > request.lastRequestTimeMs,
 		);

packages/create/templates/plugin-js/index.js

@@ -7,12 +7,14 @@ lib.definePermission({
 	name: "__plugin_name__.example.permission.event",
 	title: "Example permission event",
 	description: "Example Description. Event. Change me in index.js",
+	grantByDefault: true,
 });
 
 lib.definePermission({
 	name: "__plugin_name__.example.permission.request",
 	title: "Example permission request",
 	description: "Example Description. Request. Change me in index.js",
+	grantByDefault: true,
 });
 //%endif
 //%if controller & web // Subscribing requires web content and the controller
@@ -21,6 +23,7 @@ lib.definePermission({
 	name: "__plugin_name__.example.permission.subscribe",
 	title: "Example permission subscribe",
 	description: "Example Description. Subscribe. Change me in index.js",
+	grantByDefault: true,
 });
 //%endif
 //%if web
@@ -29,6 +32,7 @@ lib.definePermission({
 	name: "__plugin_name__.page.view",
 	title: "Example page view permission",
 	description: "Example Description. View. Change me in index.js",
+	grantByDefault: true,
 });
 //%endif
 

packages/create/templates/plugin-js/instance.js

@@ -24,18 +24,26 @@ class InstancePlugin extends BaseInstancePlugin {
 	}
 
 	async onStart() {
+		// Called once rcon becomes available
 		this.logger.info("instance::onStart");
 	}
 
 	async onStop() {
+		// Called during normal exits before rcon becomes unavailable
 		this.logger.info("instance::onStop");
 	}
 
+	onExit() {
+		// Called during all exits, including crashes and init failures, rcon is not available
+		this.logger.info("instance::onExit");
+	}
+
+
 	async onPlayerEvent(event) {
 		this.logger.info(`onPlayerEvent::onPlayerEvent ${JSON.stringify(event)}`);
 //%if module
 		if (this.instance.status === "running") {
-			this.sendRcon("/sc __plugin_name__.foo()");
+			await this.sendRcon("/sc __plugin_name__.foo()");
 		}
 //%endif
 	}

packages/create/templates/plugin-js/web/plugin.jsx

@@ -12,7 +12,7 @@ import React, {
 import {
 	BaseWebPlugin, PageLayout, PageHeader, Control, ControlContext, notifyErrorHandler,
 } from "@clusterio/web_ui";
-//%if multi_context // Subscribing requires multi context
+//%if multi_context // Messages requires multi context
 
 import {
 	PluginExampleEvent, PluginExampleRequest,
@@ -20,7 +20,7 @@ import {
 //%if controller // Subscribing requires web content and the controller
 	ExampleSubscribableUpdate, ExampleSubscribableValue,
 //%endif
-//%if multi_context // Subscribing requires multi context
+//%if multi_context // Messages requires multi context
 } from "../messages";
 //%endif
 
@@ -35,9 +35,9 @@ function MyTemplatePage() {
 
 	return <PageLayout nav={[{ name: "__plugin_name__" }]}>
 		<PageHeader title="__plugin_name__" />
-		//%if controller // Subscribing requires web content and the controller
+//%if controller // Subscribing requires web content and the controller
 		Synced: {String(synced)} Data: {JSON.stringify([...subscribableData.values()])}
-		//%endif
+//%endif
 	</PageLayout>;
 }
 
@@ -57,7 +57,7 @@ export class WebPlugin extends BaseWebPlugin {
 				permission: "__plugin_name__.example.permission.subscribe",
 //%endif
 //%if !controller
-				permission: undefined, // "__plugin_name__.example.permission.request",
+				permission: "__plugin_name__.example.permission.view",
 //%endif
 				content: <MyTemplatePage/>,
 			},

packages/create/templates/plugin-ts/controller.ts

@@ -1,6 +1,6 @@
 import * as lib from "@clusterio/lib";
 import { BaseControllerPlugin, InstanceInfo } from "@clusterio/controller";
-//%if multi_context // Subscribing requires multi context
+//%if multi_context // Messages requires multi context
 
 import {
 	PluginExampleEvent, PluginExampleRequest,
@@ -8,7 +8,7 @@ import {
 //%if controller & web // Subscribing requires web content and the controller
 	ExampleSubscribableUpdate, ExampleSubscribableValue,
 //%endif
-//%if multi_context // Subscribing requires multi context
+//%if multi_context // Messages requires multi context
 } from "./messages";
 //%endif
 
@@ -25,7 +25,8 @@ export class ControllerPlugin extends BaseControllerPlugin {
 //%endif
 //%if controller & web // Subscribing requires web content and the controller
 		this.controller.subscriptions.handle(ExampleSubscribableUpdate, this.handleExampleSubscription.bind(this));
-		this.exampleDatabase = new Map(); // If needed, replace with loading from database file
+		// If needed, replace with loading from database file such as lib.Datastore
+		this.exampleDatabase = new Map([["foo", new ExampleSubscribableValue("foo", 0, false)]]);
 //%endif
 //%if multi_context // Subscribing requires multi context
 	}
@@ -69,6 +70,7 @@ export class ControllerPlugin extends BaseControllerPlugin {
 //%if controller & web // Subscribing requires web content and the controller
 
 	async handleExampleSubscription(request: lib.SubscriptionRequest) {
+		this.logger.info(JSON.stringify(request));
 		const values = [...this.exampleDatabase.values()].filter(
 			value => value.updatedAtMs > request.lastRequestTimeMs,
 		);

packages/create/templates/plugin-ts/index.ts

@@ -6,12 +6,14 @@ lib.definePermission({
 	name: "__plugin_name__.example.permission.event",
 	title: "Example permission event",
 	description: "Example Description. Event. Change me in index.ts",
+	grantByDefault: true,
 });
 
 lib.definePermission({
 	name: "__plugin_name__.example.permission.request",
 	title: "Example permission request",
 	description: "Example Description. Request. Change me in index.ts",
+	grantByDefault: true,
 });
 //%endif
 //%if controller & web // Subscribing requires web content and the controller
@@ -20,6 +22,7 @@ lib.definePermission({
 	name: "__plugin_name__.example.permission.subscribe",
 	title: "Example permission subscribe",
 	description: "Example Description. Subscribe. Change me in index.ts",
+	grantByDefault: true,
 });
 //%endif
 //%if web
@@ -28,6 +31,7 @@ lib.definePermission({
 	name: "__plugin_name__.page.view",
 	title: "Example page view permission",
 	description: "Example Description. View. Change me in index.ts",
+	grantByDefault: true,
 });
 //%endif
 //%if config

packages/create/templates/plugin-ts/instance.ts

@@ -31,18 +31,25 @@ export class InstancePlugin extends BaseInstancePlugin {
 	}
 
 	async onStart() {
+		// Called once rcon becomes available
 		this.logger.info("instance::onStart");
 	}
 
 	async onStop() {
+		// Called during normal exits before rcon becomes unavailable
 		this.logger.info("instance::onStop");
 	}
 
+	onExit() {
+		// Called during all exits, including crashes and init failures, rcon is not available
+		this.logger.info("instance::onExit");
+	}
+
 	async onPlayerEvent(event: lib.PlayerEvent) {
 		this.logger.info(`onPlayerEvent::onPlayerEvent ${JSON.stringify(event)}`);
 //%if module
 		if (this.instance.status === "running") {
-			this.sendRcon("/sc __plugin_name__.foo()");
+			await this.sendRcon("/sc __plugin_name__.foo()");
 		}
 //%endif
 	}

packages/create/templates/plugin-ts/tsconfig.base.json

@@ -0,0 +1,13 @@
+{
+	"compilerOptions": {
+		"composite": true,
+		"declaration": true,
+		"declarationMap": true,
+		"incremental": true,
+		"sourceMap": true,
+		"strict": true,
+		"esModuleInterop": true,
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+	},
+}

packages/create/templates/plugin-ts/tsconfig.browser.json

@@ -1,8 +1,13 @@
 {
-	"extends": "../../tsconfig.browser.json",
-	"references": [
-		{ "path": "../../packages/lib/tsconfig.browser.json" },
-		{ "path": "../../packages/web_ui/tsconfig.browser.json" },
-	],
+	"extends": "./tsconfig.base.json",
+	"compilerOptions": {
+		"lib": ["dom", "es2023"],
+		"module": "es2022",
+		"moduleResolution": "bundler",
+		"target": "es2022",
+		"jsx": "react-jsx",
+		"noEmitOnError": true,
+		"outDir": "${configDir}/dist/browser",
+	},
 	"include": [ "web/**/*.tsx", "web/**/*.ts", "messages.ts", "package.json" ],
 }

packages/create/templates/plugin-ts/tsconfig.node.json

@@ -1,8 +1,13 @@
 {
-	"extends": "../../tsconfig.node.json",
-	"references": [
-		{ "path": "../../packages/lib/tsconfig.node.json" },
-	],
+	"extends": "./tsconfig.base.json",
+	"compilerOptions": {
+		"lib": ["es2023"],
+		"module": "node16",
+		"moduleResolution": "node16",
+		"target": "es2022",
+		"forceConsistentCasingInFileNames": true,
+		"outDir": "${configDir}/dist/node"
+	},
 	"include": ["./**/*.ts"],
 	"exclude": ["test/*", "./dist/*"],
 }

packages/create/templates/plugin-ts/web/plugin.tsx

@@ -12,7 +12,7 @@ import React, {
 import {
 	BaseWebPlugin, PageLayout, PageHeader, Control, ControlContext, notifyErrorHandler,
 } from "@clusterio/web_ui";
-//%if multi_context // Subscribing requires multi context
+//%if multi_context // Messages requires multi context
 
 import {
 	PluginExampleEvent, PluginExampleRequest,
@@ -20,7 +20,7 @@ import {
 //%if controller & web // Subscribing requires web content and the controller
 	ExampleSubscribableUpdate, ExampleSubscribableValue,
 //%endif
-//%if multi_context // Subscribing requires multi context
+//%if multi_context // Messages requires multi context
 } from "../messages";
 //%endif
 
@@ -35,9 +35,9 @@ function MyTemplatePage() {
 
 	return <PageLayout nav={[{ name: "__plugin_name__" }]}>
 		<PageHeader title="__plugin_name__" />
-		//%if controller // Subscribing requires web content and the controller
+//%if controller // Subscribing requires web content and the controller
 		Synced: {String(synced)} Data: {JSON.stringify([...subscribableData.values()])}
-		//%endif
+//%endif
 	</PageLayout>;
 }
 
@@ -57,7 +57,7 @@ export class WebPlugin extends BaseWebPlugin {
 				permission: "__plugin_name__.example.permission.subscribe",
 //%endif
 //%if !controller
-				permission: undefined, // "__plugin_name__.example.permission.request",
+				permission: "__plugin_name__.example.permission.view",
 //%endif
 				content: <MyTemplatePage/>,
 			},

pnpm-workspace.yaml

@@ -4,3 +4,5 @@ packages:
   - "external_plugins/*"
   - "external_plugins/*/*"
   - "test/"
+
+linkWorkspacePackages: true