synthetic-factorio 0.0.1

package/README.md

@@ -0,0 +1,45 @@
+# Synthetic Factorio
+
+Synthetic Factorio nodeJS runtime for unit testing mods.
+
+This is **not** a Factorio emulator, it is not a game that can be played.
+
+```typescript
+import { ModManager, FactorioEngine } from 'synthetic-factorio';
+
+const manager = new ModManager();
+// install vanilla "mod" data from https://github.com/wube/factorio-data (requires git CLI)
+await manager.installVanillaMods();
+// install mod by name from mod portal (requires FACTORIO_USERNAME and FACTORIO_TOKEN env variables)
+await manager.installPortalMod('SimpleSeablock');
+// install a mod in development from local files
+manager.installDirectoryMod('my-mod', './my-mod-files', { clearCache: true });
+
+// initialize the synthetic factorio engine and specify the mods that should be active
+// vanilla "mods" need to be specified, including "base", however "core" does not need to be listed
+const engine = new FactorioEngine({
+    mods: ['base', 'space-age', 'quality', 'recycler', 'elevated-rails', 'my-mod']
+});
+// run all mods through their settings phase
+engine.runSettingsPhase();
+// customize settings for your specific test run
+engine.setSettings({ startup: { 'my-mod-setting': true } });
+// run all mods through their data phase
+engine.runDataPhase();
+
+// read the data.raw collection and run test assertions
+console.log(engine.getRawData()['item']['stone-furnace']);
+
+// run control phase - NOTE: control phase support is currently very limited
+engine.runControlPhase(['my-mod']);
+
+// run any registered on_init callbacks
+engine.triggerInit();
+
+// trigger an event with the payload of your choice
+// Partial on the generic and casts on the sub-properties are recommended to avoid the need to setup the entire event payload
+engine.triggerEvent<Partial<runtime.on_chunk_generated>>(defines.events.on_chunk_generated, {
+    position: { x: 0, y: 0 },
+    surface: { name: 'nauvis' } as runtime.LuaSurface,
+});
+```

package/dist/FactorioEngine.d.ts

@@ -0,0 +1,98 @@
+import { LuaState } from 'lua-state';
+export interface FactorioEngineOptions {
+    /**
+     * List of mods to execute. Include "vanilla" mods like base or elevated-rails if needed.
+     */
+    mods: string[];
+    /**
+     * Directory where mods are executed from
+     */
+    modDir?: string;
+    /**
+     * Any mod in this list will be ignored when checking dependencies of other installed mods.
+     */
+    ignoredDependencies?: string[];
+    /**
+     * Calls to log() in mods will be funnelled through this callback. Defaults to console.log if not specified.
+     * @param message the message to log
+     */
+    logHandler?: (message: string) => void;
+}
+type SettingValue = number | boolean | string | runtime.Color;
+interface SettingsData {
+    global?: Record<string, SettingValue>;
+    player?: Record<string, SettingValue>;
+    startup?: Record<string, SettingValue>;
+}
+interface SettingsHolder {
+    global: Record<string, runtime.ModSetting>;
+    player_default: Record<string, runtime.ModSetting>;
+    startup: Record<string, runtime.ModSetting>;
+    get_player_settings: () => Record<string, runtime.ModSetting>;
+}
+type EventPayload = Omit<runtime.EventData, "name" | "tick"> & Partial<Pick<runtime.EventData, "name" | "tick">>;
+/**
+ * A synthetic factorio runtime to run lua scripts and inspect their results
+ */
+export declare class FactorioEngine {
+    luaState: LuaState;
+    readonly mods: string[];
+    readonly modDir: string;
+    settings: SettingsHolder;
+    private remoteInterfaces;
+    private remoteHandlers;
+    private ignoredDependencies;
+    private logHandler;
+    private modRuntimes;
+    constructor(options: FactorioEngineOptions);
+    /**
+     * Run the settings phase for all mods in dependency order and populate settings with the resulting defaults
+     * @param mods Run the specified mods in order. Omit to run all mods in dependency order.
+     */
+    runSettingsPhase(mods?: string[] | undefined): void;
+    /**
+     * Run the data phase for all mods in dependency order
+     * @param mods Run the specified mods in order. Omit to run all mods in dependency order.
+     */
+    runDataPhase(mods?: string[] | undefined): void;
+    private buildModsGlobal;
+    /**
+     * Get the current data.raw prototype collection
+     * @returns data collection
+     */
+    getRawData(): prototype.dataCollection;
+    /**
+     * Apply settings that will be retrievable by mods
+     * @param settings Settings to apply
+     */
+    setSettings(settings: SettingsData): void;
+    private mergeSettings;
+    /**
+     * Run the control phase for all mods in dependency order
+     * @param mods Run the specified mods in order. Omit to run all mods in dependency order.
+     */
+    runControlPhase(mods?: string[] | undefined): void;
+    /**
+     * Trigger registered on_init handlers for all mods in dependency order
+     * @param mods Run the specified mods in order. Omit to run all mods in dependency order.
+     */
+    triggerInit(mods?: string[] | undefined): void;
+    /**
+     * Trigger an event for all mods in dependency order
+     * @param eventType The event type to trigger
+     * @param payload The event payload
+     * @param mods Run the specified mods in order. Omit to run all mods in dependency order.
+     */
+    triggerEvent<T extends EventPayload>(eventType: defines.events, payload: T, mods?: string[] | undefined): void;
+    registerRemote(iface: string, fn: string, handler: (...args: any[]) => any): void;
+    private initModRuntime;
+    private postModRuntime;
+    private runModFile;
+    private getModOrder;
+    private getModPath;
+    private getModInfo;
+    private initLua;
+    private setPackagePaths;
+    private setModContext;
+}
+export {};

package/dist/FactorioEngine.js

@@ -0,0 +1,292 @@
+import { LuaState } from 'lua-state';
+import { existsSync } from 'node:fs';
+import path, { dirname } from 'node:path';
+import { modDir } from "./defaultValues.js";
+import { getDependencies, getModInfo } from "./modInfoUtil.js";
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/**
+ * A synthetic factorio runtime to run lua scripts and inspect their results
+ */
+export class FactorioEngine {
+    luaState;
+    mods;
+    modDir;
+    settings;
+    remoteInterfaces;
+    remoteHandlers;
+    ignoredDependencies;
+    logHandler;
+    modRuntimes = {};
+    constructor(options) {
+        this.luaState = this.initLua();
+        this.mods = options.mods;
+        this.modDir = options.modDir || modDir();
+        this.ignoredDependencies = options.ignoredDependencies || [];
+        this.logHandler = options.logHandler || console.log;
+        this.settings = {
+            startup: {},
+            global: {},
+            player_default: {},
+            // This should handle proper per-player settings, good enough for now
+            get_player_settings: () => settings.player_default,
+        };
+        this.remoteInterfaces = {};
+        this.remoteHandlers = {};
+    }
+    /**
+     * Run the settings phase for all mods in dependency order and populate settings with the resulting defaults
+     * @param mods Run the specified mods in order. Omit to run all mods in dependency order.
+     */
+    runSettingsPhase(mods = undefined) {
+        const modOrder = mods || this.getModOrder();
+        this.luaState.setGlobal('mods', this.buildModsGlobal());
+        for (let mod of modOrder) {
+            this.runModFile(mod, 'settings.lua');
+        }
+        this.luaState.setGlobal('mods', null);
+        const data = this.getRawData();
+        const settingsData = {
+            startup: {},
+            global: {},
+            player: {},
+        };
+        for (let settingType of ['bool-setting', 'int-setting', 'double-setting', 'string-setting', 'color-setting']) {
+            if (data[settingType]) {
+                for (let name in data[settingType]) {
+                    let setting = data[settingType][name];
+                    if (setting.setting_type === 'startup') {
+                        settingsData.startup[setting.name] = setting.default_value;
+                    }
+                    else if (setting.setting_type === 'runtime-global') {
+                        settingsData.global[setting.name] = setting.default_value;
+                    }
+                    else if (setting.setting_type === 'runtime-per-user') {
+                        settingsData.player[setting.name] = setting.default_value;
+                    }
+                }
+            }
+        }
+        this.setSettings(settingsData);
+    }
+    /**
+     * Run the data phase for all mods in dependency order
+     * @param mods Run the specified mods in order. Omit to run all mods in dependency order.
+     */
+    runDataPhase(mods = undefined) {
+        this.luaState.setGlobal('settings', { startup: this.settings?.startup });
+        this.luaState.setGlobal('mods', this.buildModsGlobal());
+        const modOrder = mods || this.getModOrder();
+        for (const mod of modOrder) {
+            this.runModFile(mod, 'data.lua');
+        }
+        for (const mod of modOrder) {
+            this.runModFile(mod, 'data-updates.lua');
+        }
+        for (const mod of modOrder) {
+            this.runModFile(mod, 'data-final-fixes.lua');
+        }
+        this.luaState.setGlobal('mods', null);
+    }
+    buildModsGlobal() {
+        const modsGlobal = {};
+        for (const modName of this.mods) {
+            modsGlobal[modName] = this.getModInfo(modName).version;
+        }
+        return modsGlobal;
+    }
+    /**
+     * Get the current data.raw prototype collection
+     * @returns data collection
+     */
+    getRawData() {
+        return (this.luaState.getGlobal('data.raw') || {});
+    }
+    /**
+     * Apply settings that will be retrievable by mods
+     * @param settings Settings to apply
+     */
+    setSettings(settings) {
+        this.mergeSettings(this.settings.global, settings.global);
+        this.mergeSettings(this.settings.startup, settings.startup);
+        this.mergeSettings(this.settings.player_default, settings.player);
+    }
+    mergeSettings(settings, values) {
+        for (const key in values) {
+            settings[key] = { value: values[key] };
+        }
+    }
+    /**
+     * Run the control phase for all mods in dependency order
+     * @param mods Run the specified mods in order. Omit to run all mods in dependency order.
+     */
+    runControlPhase(mods = undefined) {
+        const modOrder = mods || this.getModOrder();
+        for (const mod of modOrder) {
+            this.initModRuntime(mod);
+            this.luaState.setGlobal('script', {
+                on_init: (handler) => {
+                    this.modRuntimes[mod].initHandlers.push(handler);
+                },
+                on_event: (eventType, handler) => {
+                    this.modRuntimes[mod].eventHandlers[eventType] ||= [];
+                    this.modRuntimes[mod].eventHandlers[eventType].push(handler);
+                },
+            });
+            this.luaState.eval(`script.mod_name = '${mod}'`);
+            this.runModFile(mod, 'control.lua');
+            this.postModRuntime(mod);
+        }
+    }
+    /**
+     * Trigger registered on_init handlers for all mods in dependency order
+     * @param mods Run the specified mods in order. Omit to run all mods in dependency order.
+     */
+    triggerInit(mods = undefined) {
+        const modOrder = mods || this.getModOrder();
+        for (const mod of modOrder) {
+            this.initModRuntime(mod);
+            const handlers = this.modRuntimes[mod].initHandlers || [];
+            for (const handler of handlers) {
+                handler();
+            }
+            this.postModRuntime(mod);
+        }
+    }
+    /**
+     * Trigger an event for all mods in dependency order
+     * @param eventType The event type to trigger
+     * @param payload The event payload
+     * @param mods Run the specified mods in order. Omit to run all mods in dependency order.
+     */
+    triggerEvent(eventType, payload, mods = undefined) {
+        const modOrder = mods || this.getModOrder();
+        for (const mod of modOrder) {
+            this.initModRuntime(mod);
+            const handlers = this.modRuntimes[mod].eventHandlers[eventType] || [];
+            payload.name ??= eventType;
+            payload.tick ??= 0;
+            for (let handler of handlers) {
+                handler(payload);
+            }
+            this.postModRuntime(mod);
+        }
+    }
+    registerRemote(iface, fn, handler) {
+        this.remoteInterfaces[iface] ||= {};
+        this.remoteInterfaces[iface][fn] = true;
+        this.remoteHandlers[iface] ||= {};
+        this.remoteHandlers[iface][fn] = handler;
+    }
+    initModRuntime(mod) {
+        this.modRuntimes[mod] ??= { eventHandlers: {}, initHandlers: [], storage: {} };
+        this.luaState.setGlobal('storage', this.modRuntimes[mod].storage);
+        this.luaState.setGlobal('remote', {
+            interfaces: this.remoteInterfaces,
+            call: (iface, fn, ...args) => {
+                return this.remoteHandlers[iface][fn](...args);
+            }
+        });
+    }
+    postModRuntime(mod) {
+        this.modRuntimes[mod].storage = this.luaState.getGlobal('storage');
+    }
+    runModFile(modName, fileName) {
+        const targetFile = path.join(this.getModPath(modName), fileName);
+        if (existsSync(targetFile)) {
+            this.setModContext(modName);
+            this.luaState.evalFile(targetFile);
+        }
+    }
+    getModOrder() {
+        const modGraph = {};
+        for (const modName of this.mods) {
+            const dependencyInfo = getDependencies(this.getModPath(modName));
+            var incompat = dependencyInfo.incompatible.find(d => this.mods.includes(d));
+            if (incompat) {
+                throw new Error(`Failed to load mods, ${modName} and ${incompat} are incompatible`);
+            }
+            const dependencies = dependencyInfo.required.filter(d => !this.ignoredDependencies.includes(d) || this.mods.includes(d));
+            // If an optional dependency is installed, treat it as a regular one because it influences load order the same way
+            // If an optional dependency is not installed, ignore it
+            dependencies.push(...dependencyInfo.optional.filter(d => this.mods.includes(d)));
+            modGraph[modName] = dependencies;
+        }
+        const modOrder = ['core'];
+        for (const modName of this.mods) {
+            const dependencies = modGraph[modName];
+            const unmetDeps = dependencies.filter(d => !this.mods.includes(d));
+            if (unmetDeps.length) {
+                throw new Error(`Mod ${modName} is missing dependencies ${unmetDeps}`);
+            }
+        }
+        let finished = false;
+        while (!finished) {
+            finished = true;
+            let targetMod = undefined;
+            for (let key in modGraph) {
+                finished = false;
+                if (!targetMod && modGraph[key].length === 0) {
+                    targetMod = key;
+                }
+            }
+            if (finished) {
+                return modOrder;
+            }
+            if (!targetMod) {
+                throw new Error(`Circular dependency detected, failed to finish resolving ${JSON.stringify(modGraph)}`);
+            }
+            modOrder.push(targetMod);
+            delete modGraph[targetMod];
+            for (const key in modGraph) {
+                const index = modGraph[key].indexOf(targetMod);
+                if (index >= 0) {
+                    modGraph[key].splice(index, 1);
+                }
+            }
+        }
+        return modOrder;
+    }
+    getModPath(modName) {
+        return path.join(this.modDir, `../mods/__${modName}__`);
+    }
+    getModInfo(modName) {
+        return getModInfo(this.getModPath(modName));
+    }
+    initLua() {
+        const luaState = new LuaState();
+        luaState.setGlobal('log', s => this.logHandler(s));
+        const utilPath = path.join(__dirname, '../util_scripts');
+        luaState.evalFile(path.join(utilPath, 'data_setup.lua'));
+        luaState.evalFile(path.join(utilPath, 'defines.lua'));
+        luaState.evalFile(path.join(utilPath, 'require_handler.lua'));
+        /*Lua 5.3 deprecates math.atan2, but Factorio is on Lua 5.2.1
+        Could downgrade Lua, but for now this patch seems to do it */
+        luaState.eval('math.atan2 = math.atan');
+        return luaState;
+    }
+    setPackagePaths(...paths) {
+        this.luaState.eval(`package.path = '${[...paths].join(';').replace(/\\/g, '/')}'`);
+    }
+    setModContext(modName) {
+        this.setPackagePaths(
+        // This is the main import path. The engine will try to rewrite mods to match this path first, making them relative to whatever mod's file is currently running
+        // When a mod imports from another mod via __modname__.path syntax, that mod is injected at the root
+        // See require_handler.lua for more
+        `${this.modDir}/?.lua`, // importing from other mods is allowed, using the __modname__/path syntax
+        // These all become active in the "second attempt" import if the first one fails
+        `${this.modDir}/__core__/lualib/?.lua`, // lualib files are available to import by name to all mods
+        `${this.modDir}/__base__/?.lua`, // Some mods require from vanilla mods without specifying modname, which Factorio allows, so add them back in as lower priority
+        `${this.modDir}/__space-age__/?.lua`, `${this.modDir}/__elevated-rails__/?.lua`, `${this.modDir}/__quality__/?.lua`, `${this.modDir}/__recycler__/?.lua`);
+        // Used by require_handler.lua to keep track of the current "state"
+        this.luaState.eval(`current_mod_root_path = '${modName}'`);
+        // see require_handler.lua
+        if (modName === 'core' || modName === 'base' || modName === 'quality' || modName === 'recycler' || modName === 'elevated-rails' || modName === 'space-age') {
+            this.luaState.setGlobal('suppress_require_errors', true);
+        }
+        else {
+            this.luaState.setGlobal('suppress_require_errors', false);
+        }
+    }
+}

package/dist/ModManager.d.ts

@@ -0,0 +1,77 @@
+export interface ModManagerOptions {
+    /**
+     * Directory where mods are installed
+     */
+    modDir?: string;
+    /**
+     * Working directory for files like mod downloads
+     */
+    workingDir?: string;
+}
+export interface ModInstallOptions {
+    /**
+     * Clear previously-installed files and re-install
+     */
+    clearCache?: boolean;
+}
+export interface ModDownloadOptions extends ModInstallOptions {
+    /**
+     * Clear previously-downloaded files and force re-download
+     */
+    clearDownload?: boolean;
+    /**
+     * Check if a newer version exists and download if needed
+     */
+    checkLatest?: boolean;
+}
+export interface ModPortalDownloadOptions extends ModDownloadOptions {
+    /**
+     * Version of the mod to download, if omitted either installs latest from portal or uses latest downloaded depending on `checkLatest` option.
+     */
+    version?: string;
+    /**
+     * True to skip installing dependent mods. By default all required dependent mods are installed.
+     */
+    skipDependencies?: boolean;
+    /**
+     * Dependencies in this list will be skipped, useful for skipping large asset-only deps that are not needed for testing.
+     */
+    omitDependencies?: string[];
+}
+/**
+ * Utility class to download/install mods so they can be found by FactorioEngine
+ */
+export declare class ModManager {
+    readonly modDir: string;
+    readonly workingDir: string;
+    constructor(options?: ModManagerOptions);
+    /**
+     * Download all vanilla "mod" data from https://github.com/wube/factorio-data
+     * Requires git to be available at the command line
+     * @param options Mod Installation options
+     */
+    installVanillaMods(options?: ModDownloadOptions): Promise<void>;
+    /**
+     * Install mod from a directory - essentially a directory copy to the correct location
+     * @param modName Name of the mod
+     * @param sourcePath Path to copy from
+     * @param options Mod Installation Options
+     */
+    installDirectoryMod(modName: string, sourcePath: string, options?: ModInstallOptions): void;
+    /**
+     * Downloads and installs a mod from Factorio's mod portal.
+     * Requires the environment variables FACTORIO_USERNAME and FACTORIO_TOKEN to be set
+     * @param modName Name of the mod
+     * @param options Mod Installation Optiions
+     */
+    installPortalMod(modName: string, options?: ModPortalDownloadOptions): Promise<void>;
+    private getModInfo;
+    /**
+     * Install a mod from a zip file
+     * @param modName Name of the mod
+     * @param sourcePath Path to the zip file
+     * @param options Mod Installation Options
+     */
+    installZipMod(modName: string, sourcePath: string, options?: ModInstallOptions): Promise<void>;
+    private getModPath;
+}