cyclops-infobook-html 4.0.1 → 5.1.0

package/README.md

@@ -13,11 +13,12 @@ This tool is the basis for the following mod-specific plugins:
 
 ## Usage
 
-This tool allows Cyclops infobooks to be exported as an HTML website in three phases:
+This tool allows Cyclops infobooks to be exported as an HTML website in four phases:
 
 1. Metadata generation: A preparation step for generating all required metadata that is needed for serializing the infobook to HTML.
 2. Icon generation: Exporting item and block icons to PNG files. 
 3. HTML generation: Serialization to HTML based on the infook XML and metadata.
+4. Icon compression: Optionally compress icons within the output directory.
 
 ### 1. Metadata Generation
 
@@ -64,13 +65,28 @@ If you want to re-download the mods without re-installing Forge, you can run `ge
 
 ### 2. Icon Generation
 
-This phase should be done using the [Icon Exporter mod](https://github.com/CyclopsMC/IconExporter).
+This phase can be done manually using the [Icon Exporter mod](https://github.com/CyclopsMC/IconExporter), or automatically.
+
+#### Manual icon generation
 
 Simply create a modpack with all the mods that were downloaded in the previous step (including the Item Exporter mod),
 start a world, and run the `/iconexporter export 64` command.
 
 Next, copy the resulting contents of `icon-exports-x64` to `icons` in your project directory.
 
+#### Automatic icon generation
+
+The `generate-icons` command can be executed,
+which will cause a Headless Minecraft instance to be downloaded and started,
+and the Icon Exporter mod to be ran.
+
+When running this on a headless machine, you should have `xvfb` installed and running.
+For example:
+```
+$ sudo apt-get install -y xvfb
+$ xvfb-run --auto-servernum --server-args="-screen 0 1920x1080x24" generate-icons
+```
+
 ### 3. HTML Generation
 
 Before you start this phase, make sure the following files and directories are present:
@@ -130,6 +146,11 @@ Before you start this phase, make sure the following files and directories are p
 This phase can be started by executing `generate-cyclops-infobook-html config.json /output`.
 Afterwards, the contents of `/output` can be hosted on any Web server.
 
+### 4. Icon Compression
+
+Using the `compress-icons` command, icons within the `output/` directory will be compressed.
+This is recommended when deploying the output to a web server.
+
 ### Plugins
 
 Optionally, plugins can be loaded to for example add support for non-default appendix handlers.

package/bin/compress-icons.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/bin/compress-icons.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = require("fs");
+const minimist = require("minimist");
+const path_1 = require("path");
+const IconsCompressor_1 = require("../lib/icon/IconsCompressor");
+// Process CLI args
+const args = minimist(process.argv.slice(2));
+if (args.help || args._.length < 1) {
+    printUsage();
+}
+function run(outputDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const iconsDir = (0, path_1.resolve)(outputDir, 'assets', 'icon');
+        if (!fs.existsSync(iconsDir)) {
+            process.stderr.write(`Icons directory not found: ${iconsDir}\n`);
+            process.exit(1);
+        }
+        const compressor = new IconsCompressor_1.IconsCompressor(iconsDir);
+        yield compressor.compress();
+    });
+}
+function printUsage() {
+    process.stdout.write(`compress-icons Losslessly compress PNG icons in the HTML output directory
+Usage:
+  compress-icons /path/to/output
+Options:
+  --help  print this help message
+`);
+    process.exit(1);
+}
+run(args._[0]).catch((e) => {
+    // tslint:disable-next-line:no-console
+    console.error(e);
+    process.exit(1);
+});
+//# sourceMappingURL=compress-icons.js.map

package/bin/generate-icons.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/bin/generate-icons.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = require("fs");
+const minimist = require("minimist");
+const path_1 = require("path");
+const IconsGenerator_1 = require("../lib/icon/IconsGenerator");
+// Process CLI args
+const args = minimist(process.argv.slice(2));
+if (args.help || args._.length < 1) {
+    printUsage();
+}
+function run(configPath) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        if (!config.minecraft) {
+            process.stderr.write('Missing "minecraft" field in config\n');
+            process.exit(1);
+        }
+        if (!config.neoforge && !config.forge) {
+            process.stderr.write('Missing "neoforge" or "forge" field in config\n');
+            process.exit(1);
+        }
+        const generator = new IconsGenerator_1.IconsGenerator({
+            modsDir: (0, path_1.join)(process.cwd(), args['mods-dir'] || (0, path_1.join)('server', 'mods')),
+            iconsDir: (0, path_1.join)(process.cwd(), args['icons-dir'] || 'icon'),
+            workDir: (0, path_1.join)(process.cwd(), args['work-dir'] || 'headlessmc'),
+            minecraftVersion: config.minecraft,
+            neoforgeVersion: config.neoforge || config.forge,
+            githubToken: args['github-token'] || process.env.GITHUB_TOKEN,
+            iconExporterVersion: args['icon-exporter-version'],
+            headlessMcVersion: args['headlessmc-version'],
+            launchTimeoutMs: args.timeout ? parseInt(args.timeout, 10) * 1000 : undefined,
+        });
+        yield generator.generate();
+    });
+}
+function printUsage() {
+    process.stdout.write(`generate-icons Download IconExporter and HeadlessMC, launches Minecraft headlessly, and exports item icons
+Usage:
+  generate-icons /path/to/modpack.json
+Options:
+  --help                   print this help message
+  --mods-dir               directory containing mod JARs (default: server/mods)
+  --icons-dir              output directory for icons (default: icons)
+  --work-dir               working directory for HeadlessMC (default: headlessmc)
+  --github-token           GitHub token for downloading from GitHub Packages
+  --icon-exporter-version  version of the IconExporter artifact (default: 1.4.0-174)
+  --headlessmc-version     version of HeadlessMC to use (default: 2.8.0)
+  --timeout                timeout in seconds for the full icon generation (default: 1800)
+`);
+    process.exit(1);
+}
+run(args._[0]).catch((e) => {
+    // tslint:disable-next-line:no-console
+    console.error(e);
+    process.exit(1);
+});
+//# sourceMappingURL=generate-icons.js.map

package/bin/generate-infobook-html.js

@@ -1,7 +1,15 @@
 #!/usr/bin/env node
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-const tslib_1 = require("tslib");
 const fs = require("fs");
 const minimist = require("minimist");
 const path_1 = require("path");
@@ -26,7 +34,7 @@ Options:
     process.exit(1);
 }
 function create() {
-    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+    return __awaiter(this, void 0, void 0, function* () {
         // Create infobook from config
         const config = JSON.parse(fs.readFileSync(args._[0], "utf8"));
         // Override baseUrl
@@ -43,18 +51,18 @@ function create() {
             process.stderr.write('Could not find a "mod_assets" folder, make sure to create one with generate-mod-metadata.\n');
             process.exit(1);
         }
-        // Check if icons are available
-        if (!fs.existsSync('icons')) {
-            process.stderr.write('Could not find a "icons" folder, make sure to create one with output from the IconExporter mod.\n');
+        // Check if icon are available
+        if (!fs.existsSync('icon')) {
+            process.stderr.write('Could not find a "icon" folder, make sure to create one with output from the IconExporter mod.\n');
             process.exit(1);
         }
         // Read resources
         const resourceLoader = new ResourceLoader_1.ResourceLoader();
-        yield resourceLoader.loadIcons('icons');
+        yield resourceLoader.loadIcons('icon');
         yield resourceLoader.loadItemTranslationKeys('registries');
         yield resourceLoader.loadFluidTranslationKeys('registries');
         yield resourceLoader.loadKeybindings(config.keybindings);
-        yield resourceLoader.loadAll(process.cwd(), 'mod_assets');
+        yield resourceLoader.loadAll(process.cwd(), 'mod_assets', config.excludedModLanguages || []);
         // Setup infobook loader
         const infoBookInitializer = new InfoBookInitializer_1.InfoBookInitializer(config);
         infoBookInitializer.registerAppendixHandler('advancement_rewards', new InfoBookAppendixHandlerAdvancementRewards_1.InfoBookAppendixHandlerAdvancementRewards(resourceLoader.getResourceHandler()));
@@ -68,7 +76,7 @@ function create() {
         const headSuffixGetters = [];
         if (config.plugins) {
             for (const pluginPath of config.plugins) {
-                const plugin = require(path_1.join(process.cwd(), pluginPath));
+                const plugin = require((0, path_1.join)(process.cwd(), pluginPath));
                 plugin.load(infoBookInitializer, resourceLoader, config);
                 if (plugin.assetsPath) {
                     assetsPaths.push(plugin.assetsPath);

package/bin/generate-mod-metadata.js

@@ -1,7 +1,15 @@
 #!/usr/bin/env node
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-const tslib_1 = require("tslib");
 const fs = require("fs");
 const minimist = require("minimist");
 const path_1 = require("path");
@@ -12,12 +20,12 @@ if (args.help || args._.length !== 2) {
     printUsage();
 }
 function run(command, configPath) {
-    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+    return __awaiter(this, void 0, void 0, function* () {
         // Create mod loader
         const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
         const modLoader = new ModLoader_1.ModLoader({
             mods: config.mods,
-            path: path_1.join(process.cwd(), 'server'),
+            path: (0, path_1.join)(process.cwd(), 'server'),
             loader: 'forge' in config ? { versionForge: config.forge } : { versionNeoForge: config.neoforge },
             versionMinecraft: config.minecraft,
         });
@@ -30,11 +38,11 @@ function run(command, configPath) {
                 break;
             case 'extractmc':
                 yield modLoader.extractMinecraftAssets();
-                yield modLoader.copyModAssets(path_1.join(process.cwd(), 'mod_assets'));
+                yield modLoader.copyModAssets((0, path_1.join)(process.cwd(), 'mod_assets'));
                 break;
             case 'extractmods':
                 yield modLoader.extractModsAssets();
-                yield modLoader.copyModAssets(path_1.join(process.cwd(), 'mod_assets'));
+                yield modLoader.copyModAssets((0, path_1.join)(process.cwd(), 'mod_assets'));
                 break;
             case 'generate':
                 if (!modLoader.isForgeInstalled()) {
@@ -63,10 +71,10 @@ function run(command, configPath) {
                 if (lastError) {
                     throw lastError;
                 }
-                yield modLoader.copyRegistries(path_1.join(process.cwd(), 'registries'));
+                yield modLoader.copyRegistries((0, path_1.join)(process.cwd(), 'registries'));
                 yield modLoader.extractMinecraftAssets();
                 yield modLoader.extractModsAssets();
-                yield modLoader.copyModAssets(path_1.join(process.cwd(), 'mod_assets'));
+                yield modLoader.copyModAssets((0, path_1.join)(process.cwd(), 'mod_assets'));
                 break;
             default:
                 printUsage();

package/index.d.ts

@@ -1,3 +1,5 @@
+export * from "./lib/icon/IconsCompressor";
+export * from "./lib/icon/IconsGenerator";
 export * from "./lib/infobook/appendix/IInfoBookAppendixHandler";
 export * from "./lib/infobook/appendix/InfoBookAppendixAd";
 export * from "./lib/infobook/appendix/InfoBookAppendixHandlerAbstractRecipe";

package/index.js

@@ -1,27 +1,42 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-const tslib_1 = require("tslib");
-tslib_1.__exportStar(require("./lib/infobook/appendix/IInfoBookAppendixHandler"), exports);
-tslib_1.__exportStar(require("./lib/infobook/appendix/InfoBookAppendixAd"), exports);
-tslib_1.__exportStar(require("./lib/infobook/appendix/InfoBookAppendixHandlerAbstractRecipe"), exports);
-tslib_1.__exportStar(require("./lib/infobook/appendix/InfoBookAppendixHandlerAdvancementRewards"), exports);
-tslib_1.__exportStar(require("./lib/infobook/appendix/InfoBookAppendixHandlerCraftingRecipe"), exports);
-tslib_1.__exportStar(require("./lib/infobook/appendix/InfoBookAppendixHandlerSmeltingRecipe"), exports);
-tslib_1.__exportStar(require("./lib/infobook/appendix/InfoBookAppendixHandlerImage"), exports);
-tslib_1.__exportStar(require("./lib/infobook/appendix/InfoBookAppendixHandlerKeybinding"), exports);
-tslib_1.__exportStar(require("./lib/infobook/appendix/InfoBookAppendixTagIndex"), exports);
-tslib_1.__exportStar(require("./lib/infobook/FileWriter"), exports);
-tslib_1.__exportStar(require("./lib/infobook/IFileWriter"), exports);
-tslib_1.__exportStar(require("./lib/infobook/IFluid"), exports);
-tslib_1.__exportStar(require("./lib/infobook/IInfoAppendix"), exports);
-tslib_1.__exportStar(require("./lib/infobook/IInfoBook"), exports);
-tslib_1.__exportStar(require("./lib/infobook/IInfobookPlugin"), exports);
-tslib_1.__exportStar(require("./lib/infobook/IInfoSection"), exports);
-tslib_1.__exportStar(require("./lib/infobook/IItem"), exports);
-tslib_1.__exportStar(require("./lib/infobook/InfoBookInitializer"), exports);
-tslib_1.__exportStar(require("./lib/modloader/ModLoader"), exports);
-tslib_1.__exportStar(require("./lib/parse/XmlInfoBookParser"), exports);
-tslib_1.__exportStar(require("./lib/resource/ResourceHandler"), exports);
-tslib_1.__exportStar(require("./lib/resource/ResourceLoader"), exports);
-tslib_1.__exportStar(require("./lib/serialize/HtmlInfoBookSerializer"), exports);
+__exportStar(require("./lib/icon/IconsCompressor"), exports);
+__exportStar(require("./lib/icon/IconsGenerator"), exports);
+__exportStar(require("./lib/infobook/appendix/IInfoBookAppendixHandler"), exports);
+__exportStar(require("./lib/infobook/appendix/InfoBookAppendixAd"), exports);
+__exportStar(require("./lib/infobook/appendix/InfoBookAppendixHandlerAbstractRecipe"), exports);
+__exportStar(require("./lib/infobook/appendix/InfoBookAppendixHandlerAdvancementRewards"), exports);
+__exportStar(require("./lib/infobook/appendix/InfoBookAppendixHandlerCraftingRecipe"), exports);
+__exportStar(require("./lib/infobook/appendix/InfoBookAppendixHandlerSmeltingRecipe"), exports);
+__exportStar(require("./lib/infobook/appendix/InfoBookAppendixHandlerImage"), exports);
+__exportStar(require("./lib/infobook/appendix/InfoBookAppendixHandlerKeybinding"), exports);
+__exportStar(require("./lib/infobook/appendix/InfoBookAppendixTagIndex"), exports);
+__exportStar(require("./lib/infobook/FileWriter"), exports);
+__exportStar(require("./lib/infobook/IFileWriter"), exports);
+__exportStar(require("./lib/infobook/IFluid"), exports);
+__exportStar(require("./lib/infobook/IInfoAppendix"), exports);
+__exportStar(require("./lib/infobook/IInfoBook"), exports);
+__exportStar(require("./lib/infobook/IInfobookPlugin"), exports);
+__exportStar(require("./lib/infobook/IInfoSection"), exports);
+__exportStar(require("./lib/infobook/IItem"), exports);
+__exportStar(require("./lib/infobook/InfoBookInitializer"), exports);
+__exportStar(require("./lib/modloader/ModLoader"), exports);
+__exportStar(require("./lib/parse/XmlInfoBookParser"), exports);
+__exportStar(require("./lib/resource/ResourceHandler"), exports);
+__exportStar(require("./lib/resource/ResourceLoader"), exports);
+__exportStar(require("./lib/serialize/HtmlInfoBookSerializer"), exports);
 //# sourceMappingURL=index.js.map

package/lib/icon/IconsCompressor.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Losslessly compresses PNG icon files using OptiPNG.
+ * Mimics how ImgBot compresses images: lossless PNG compression at optimization level 7
+ * with metadata stripping.
+ */
+export declare class IconsCompressor {
+    private readonly iconsDir;
+    constructor(iconsDir: string);
+    /**
+     * Compress all PNG files in the icon directory using OptiPNG.
+     */
+    compress(): Promise<void>;
+    /**
+     * Get the path to the optipng binary from optipng-bin package.
+     * Uses require.resolve to find the package root, then constructs the vendor binary path.
+     */
+    getOptipngPath(): string;
+}

package/lib/icon/IconsCompressor.js

@@ -0,0 +1,81 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IconsCompressor = void 0;
+const child_process_1 = require("child_process");
+const fs = require("fs");
+const path_1 = require("path");
+const util_1 = require("util");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+/**
+ * Losslessly compresses PNG icon files using OptiPNG.
+ * Mimics how ImgBot compresses images: lossless PNG compression at optimization level 7
+ * with metadata stripping.
+ */
+class IconsCompressor {
+    constructor(iconsDir) {
+        if (!iconsDir) {
+            throw new Error('Missing iconsDir argument');
+        }
+        this.iconsDir = iconsDir;
+    }
+    /**
+     * Compress all PNG files in the icon directory using OptiPNG.
+     */
+    compress() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const optipngPath = this.getOptipngPath();
+            if (!fs.existsSync(optipngPath)) {
+                throw new Error(`OptiPNG binary not found at: ${optipngPath}. Ensure optipng-bin is installed.`);
+            }
+            const files = yield fs.promises.readdir(this.iconsDir);
+            const pngFiles = files.filter((f) => f.endsWith('.png'));
+            if (pngFiles.length === 0) {
+                process.stdout.write(`No PNG files found in ${this.iconsDir}\n`);
+                return;
+            }
+            process.stdout.write(`Compressing ${pngFiles.length} icons in ${this.iconsDir}...\n`);
+            let compressed = 0;
+            let errors = 0;
+            let totalSavedBytes = 0;
+            for (const file of pngFiles) {
+                const filePath = (0, path_1.join)(this.iconsDir, file);
+                const sizeBefore = fs.statSync(filePath).size;
+                try {
+                    yield execFileAsync(optipngPath, ['-o7', '-strip', 'all', '-quiet', filePath]);
+                    const sizeAfter = fs.statSync(filePath).size;
+                    totalSavedBytes += sizeBefore - sizeAfter;
+                    compressed++;
+                }
+                catch (err) {
+                    process.stderr.write(`Warning: failed to compress ${file}: ${err}\n`);
+                    errors++;
+                }
+            }
+            const savedKb = (totalSavedBytes / 1024).toFixed(1);
+            process.stdout.write(`Compressed ${compressed} icons (saved ${savedKb} KB)` +
+                (errors > 0 ? `, ${errors} errors` : '') +
+                `\n`);
+        });
+    }
+    /**
+     * Get the path to the optipng binary from optipng-bin package.
+     * Uses require.resolve to find the package root, then constructs the vendor binary path.
+     */
+    getOptipngPath() {
+        const indexPath = require.resolve('optipng-bin');
+        const pkgRoot = (0, path_1.dirname)(indexPath);
+        const binaryName = process.platform === 'win32' ? 'optipng.exe' : 'optipng';
+        return (0, path_1.join)(pkgRoot, 'vendor', binaryName);
+    }
+}
+exports.IconsCompressor = IconsCompressor;
+//# sourceMappingURL=IconsCompressor.js.map

package/lib/icon/IconsGenerator.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Generates icons using the IconExporter mod and HeadlessMC.
+ * This class downloads HeadlessMC and the IconExporter mod, sets up a headless
+ * Minecraft client with NeoForge and all specified mods, launches the game,
+ * runs the iconexporter export command, and copies the resulting icons.
+ */
+export declare class IconsGenerator {
+    private static readonly HEADLESSMC_JAR;
+    private static readonly ICONEXPORTER_JAR;
+    private static readonly HMC_GAME_SUBDIR;
+    private static readonly HMC_CONFIG_SUBDIR;
+    private static readonly ICON_EXPORT_SUBDIR;
+    private static readonly DEFAULT_ICON_SIZE;
+    private static readonly HMC_SPECIFICS_REPO;
+    private readonly modsDir;
+    private readonly iconsDir;
+    private readonly workDir;
+    private readonly minecraftVersion;
+    private readonly neoforgeVersion;
+    private readonly githubToken;
+    private readonly iconExporterArtifact;
+    private readonly iconExporterVersion;
+    private readonly headlessMcVersion;
+    private readonly launchTimeoutMs;
+    constructor(args: IIconsGeneratorArgs);
+    /**
+     * Run the full icon generation pipeline.
+     */
+    generate(): Promise<void>;
+    /**
+     * Download the HeadlessMC launcher jar.
+     */
+    downloadHeadlessMc(): Promise<void>;
+    /**
+     * Download the IconExporter mod from GitHub Maven packages.
+     */
+    downloadIconExporter(): Promise<void>;
+    /**
+     * Set up the game directory with mods and options.
+     */
+    setupGameDirectory(): Promise<void>;
+    /**
+     * Write the HeadlessMC configuration file.
+     */
+    writeHmcConfig(): void;
+    /**
+     * Run the Minecraft client using HeadlessMC and export icons.
+     */
+    runGameAndExportIcons(): Promise<void>;
+    /**
+     * Copy exported icons to the output icons directory.
+     */
+    copyIcons(): Promise<void>;
+    /**
+     * Parse the HeadlessMC `gui` command output and find the numeric button ID for a given
+     * button text label. HeadlessMC's `click` command requires a numeric id, not the text.
+     * The gui table format is:
+     *   id   text                    x    y    w    h    on   type
+     *   0    Multiplayer             140  123  200  20   1    Button
+     *   1    Singleplayer            140  99   200  20   1    Button
+     * Columns are separated by two or more spaces.
+     */
+    findButtonIdByText(guiOutput: string, buttonText: string): number | null;
+    /**
+     * Determine if the Minecraft game has fully loaded based on log output.
+     */
+    isGameFullyLoaded(output: string): boolean;
+    /**
+     * Determine if the HeadlessMC launcher is ready to accept commands based on its startup output.
+     * In non-TTY mode HeadlessMC does not print a '>' prompt, so we detect readiness from the
+     * version-table header or the DefaultCommandLineProvider warning it prints on startup.
+     */
+    isHeadlessMcReady(output: string): boolean;
+    /**
+     * Download the hmc-specifics mod from GitHub Releases into the given mods directory.
+     * This avoids relying on HeadlessMC's built-in `-specifics` auto-download which checks
+     * the GitHub API without authentication and can hit rate limits.
+     */
+    downloadHmcSpecifics(modsDir: string): Promise<void>;
+    /**
+     * Download a file from a URL to a destination path.
+     */
+    downloadFile(url: string, destPath: string, headers?: Record<string, string>): Promise<void>;
+}
+export type IGameState = 'waiting_for_prompt' | 'game_launching' | 'checking_screen' | 'navigating_singleplayer' | 'creating_world' | 'exporting_icons' | 'quitting';
+export interface IIconsGeneratorArgs {
+    /**
+     * Directory containing mod JARs to include in the client (usually server/mods).
+     */
+    modsDir: string;
+    /**
+     * Directory where icons will be written.
+     */
+    iconsDir: string;
+    /**
+     * Working directory for HeadlessMC and game files.
+     */
+    workDir: string;
+    /**
+     * Minecraft version (e.g., "1.21.1").
+     */
+    minecraftVersion: string;
+    /**
+     * NeoForge version (e.g., "21.1.210").
+     */
+    neoforgeVersion: string;
+    /**
+     * GitHub token for downloading from GitHub Packages.
+     * Falls back to GITHUB_TOKEN environment variable.
+     */
+    githubToken?: string;
+    /**
+     * Maven artifact ID for IconExporter (default: iconexporter-{minecraftVersion}-neoforge).
+     */
+    iconExporterArtifact?: string;
+    /**
+     * Version of the IconExporter artifact to download (e.g., "1.4.0-174").
+     */
+    iconExporterVersion?: string;
+    /**
+     * Version of HeadlessMC to download (e.g., "2.8.0").
+     */
+    headlessMcVersion?: string;
+    /**
+     * Timeout in milliseconds for the full game launch and icon export (default: 30 minutes).
+     */
+    launchTimeoutMs?: number;
+}