isaacscript 3.16.0 → 3.16.1-dev.1

package/dist/commands/publish/prePublish.js

@@ -0,0 +1,105 @@
+import { PACKAGE_JSON, fatalError, getPackageJSONVersion, getPackageManagerInstallCommand, isFile, readFile, updatePackageJSON, writeFile, } from "isaacscript-common-node";
+import { CONSTANTS_TS_PATH, METADATA_XML_PATH, VERSION_TXT_PATH, } from "../../constants.js";
+import { execShell, execShellString } from "../../exec.js";
+import { gitCommitAllAndPush } from "../../git.js";
+import { getPackageManagerUsedForExistingProject } from "../../packageManager.js";
+/**
+ * Before uploading the project, we want to update dependencies, increment the version, and perform
+ * some other steps.
+ */
+export async function prePublish(args, typeScript) {
+    const skipUpdate = args.skipUpdate === true;
+    const skipLint = args.skipLint === true;
+    const dryRun = args.dryRun === true;
+    const verbose = args.verbose === true;
+    const packageManager = getPackageManagerUsedForExistingProject(args);
+    execShellString("git pull --rebase");
+    execShellString("git push");
+    await updateDependencies(skipUpdate, dryRun, packageManager, verbose);
+    incrementVersion(args, typeScript);
+    tryRunNPMScript("build", verbose);
+    if (!skipLint) {
+        tryRunNPMScript("lint", verbose);
+    }
+}
+async function updateDependencies(skipUpdate, dryRun, packageManager, verbose) {
+    if (skipUpdate) {
+        return;
+    }
+    console.log(`Updating dependencies in the "${PACKAGE_JSON}" file...`);
+    const hasNewDependencies = await updatePackageJSON(undefined);
+    if (hasNewDependencies) {
+        const command = getPackageManagerInstallCommand(packageManager);
+        execShellString(command, verbose);
+        if (!dryRun) {
+            gitCommitAllAndPush("chore: update dependencies", verbose);
+        }
+    }
+}
+function incrementVersion(args, typeScript) {
+    const skipIncrement = args.skipIncrement === true;
+    const verbose = args.verbose === true;
+    if (skipIncrement) {
+        return;
+    }
+    const versionCommandArgument = getVersionCommandArgument(args);
+    // We always use `npm` here to avoid differences with the version command between package
+    // managers. The "--no-git-tag-version" flag will prevent npm from both making a commit and adding
+    // a tag.
+    execShellString(`npm version ${versionCommandArgument} --no-git-tag-version`, verbose);
+    if (!typeScript) {
+        const version = getPackageJSONVersion(undefined);
+        writeVersionToConstantsTS(version);
+        writeVersionToMetadataXML(version);
+        writeVersionToVersionTXT(version);
+    }
+}
+function getVersionCommandArgument(args) {
+    const { setVersion } = args;
+    if (setVersion !== undefined) {
+        // They want to use a specific version, which was manually specified.
+        return setVersion;
+    }
+    const major = args.major === true;
+    if (major) {
+        return "major";
+    }
+    const minor = args.minor === true;
+    if (minor) {
+        return "minor";
+    }
+    const patch = args.patch === true;
+    if (patch) {
+        return "patch";
+    }
+    // Default to a patch version.
+    return "patch";
+}
+function writeVersionToConstantsTS(version) {
+    if (!isFile(CONSTANTS_TS_PATH)) {
+        console.log('Skipping writing the version to "constants.ts" since it was not found.');
+        return;
+    }
+    const constantsTS = readFile(CONSTANTS_TS_PATH);
+    const newConstantsTS = constantsTS.replace(/const VERSION = ".+"/, `const VERSION = "${version}"`);
+    writeFile(CONSTANTS_TS_PATH, newConstantsTS);
+    console.log(`The version of ${version} was written to: ${CONSTANTS_TS_PATH}`);
+}
+function writeVersionToMetadataXML(version) {
+    const metadataXML = readFile(METADATA_XML_PATH);
+    const newMetadataXML = metadataXML.replace(/<version>.+<\/version>/, `<version>${version}</version>`);
+    writeFile(METADATA_XML_PATH, newMetadataXML);
+    console.log(`The version of ${version} was written to: ${METADATA_XML_PATH}`);
+}
+function writeVersionToVersionTXT(version) {
+    writeFile(VERSION_TXT_PATH, version);
+    console.log(`The version of ${version} was written to: ${VERSION_TXT_PATH}`);
+}
+function tryRunNPMScript(scriptName, verbose) {
+    console.log(`Running: ${scriptName}`);
+    const { exitStatus, stdout } = execShell("npm", ["run", scriptName], verbose, true);
+    if (exitStatus !== 0) {
+        execShellString("git reset --hard", verbose); // Revert the version changes.
+        fatalError(`Failed to run "${scriptName}":`, stdout);
+    }
+}

package/dist/commands/publish/publish.js

@@ -0,0 +1,39 @@
+import { getPackageJSONField, getPackageJSONVersion, } from "isaacscript-common-node";
+import { execShellString } from "../../exec.js";
+import { getReleaseGitCommitMessage, gitCommitAllAndPush } from "../../git.js";
+import { getInputString } from "../../prompt.js";
+import { publishIsaacScriptMod } from "./isaacscriptMod.js";
+import { prePublish } from "./prePublish.js";
+import { validate } from "./validate.js";
+export async function publish(args, config, typeScript) {
+    const { setVersion } = args;
+    const verbose = args.verbose === true;
+    validate(typeScript, setVersion, verbose);
+    await prePublish(args, typeScript);
+    await (typeScript
+        ? publishTypeScriptProject(args)
+        : publishIsaacScriptMod(args, config));
+}
+async function publishTypeScriptProject(args) {
+    const dryRun = args.dryRun === true;
+    const verbose = args.verbose === true;
+    const projectName = getPackageJSONField(undefined, "name");
+    const version = getPackageJSONVersion(undefined);
+    if (dryRun) {
+        execShellString("git reset --hard", verbose); // Revert the version changes.
+    }
+    else {
+        const releaseGitCommitMessage = getReleaseGitCommitMessage(version);
+        gitCommitAllAndPush(releaseGitCommitMessage, verbose);
+        let command = "npm publish --access=public";
+        if (args.otp === true) {
+            const otpCode = await getInputString("Type in the two-factor OTP code tied to the npm account. (Just press enter if you do not have 2FA enabled on your npm account.)");
+            if (otpCode !== "") {
+                command += ` --otp=${otpCode}`;
+            }
+        }
+        execShellString(command, verbose);
+    }
+    const dryRunSuffix = dryRun ? " (dry-run)" : "";
+    console.log(`Published ${projectName} version ${version} successfully${dryRunSuffix}.`);
+}

package/dist/commands/publish/validate.js

@@ -0,0 +1,46 @@
+import chalk from "chalk";
+import { PACKAGE_JSON, fatalError, isFile, isGitRepository, isGitRepositoryClean, isLoggedInToNPM, } from "isaacscript-common-node";
+import { CWD, PROJECT_NAME } from "../../constants.js";
+import { execPowershell } from "../../exec.js";
+export function validate(typeScript, setVersion, verbose) {
+    if (!isGitRepository(CWD)) {
+        fatalError("Failed to publish since the current working directory is not inside of a git repository.");
+    }
+    if (!isGitRepositoryClean(CWD)) {
+        fatalError("Failed to publish since the Git repository was dirty. Before publishing, you must push any current changes to git. (Version commits should not contain any code changes.)");
+    }
+    if (!isFile(PACKAGE_JSON)) {
+        fatalError(`Failed to find the "${PACKAGE_JSON}" file in the current working directory.`);
+    }
+    if (setVersion !== undefined && /^\d+\.\d+\.\d+$/.exec(setVersion) === null) {
+        fatalError(chalk.red(`The version of "${setVersion}" does not match the semantic versioning format.`));
+    }
+    if (typeScript) {
+        validateTypeScriptProject();
+    }
+    else {
+        validateIsaacScriptMod(verbose);
+    }
+}
+function validateTypeScriptProject() {
+    if (!isLoggedInToNPM()) {
+        fatalError('Failed to publish since you are not logged in to npm. Try doing "npm login".');
+    }
+}
+function validateIsaacScriptMod(verbose) {
+    validateIsaacScriptOtherCopiesNotRunning(verbose);
+}
+function validateIsaacScriptOtherCopiesNotRunning(verbose) {
+    if (process.platform !== "win32") {
+        return;
+    }
+    // From: https://securityboulevard.com/2020/01/get-process-list-with-command-line-arguments/
+    const stdout = execPowershell("Get-WmiObject Win32_Process -Filter \"name = 'node.exe'\" | Select-Object -ExpandProperty CommandLine", verbose);
+    const lines = stdout.split("\r\n");
+    const otherCopiesOfRunningIsaacScript = lines.filter((line) => line.includes("node.exe") &&
+        line.includes("isaacscript") &&
+        !line.includes("isaacscript publish"));
+    if (otherCopiesOfRunningIsaacScript.length > 0) {
+        fatalError(chalk.red(`Other copies of ${PROJECT_NAME} appear to be running. You must close those copies before publishing.`));
+    }
+}

package/dist/common.js

@@ -0,0 +1,65 @@
+// These are functions copied from `isaacscript-common`.
+import { fatalError } from "isaacscript-common-node";
+import { parseIntSafe } from "isaacscript-common-ts";
+import { DOOR_SLOT_TO_DOOR_SLOT_FLAG } from "./objects/copied/doorSlotToDoorSlotFlag.js";
+import { ROOM_SHAPE_TO_DOOR_SLOT_COORDINATES } from "./objects/copied/roomShapeToDoorSlotCoordinates.js";
+/** This is copied from `isaacscript-common`. */
+export function getJSONRoomDoorSlotFlags(jsonRoom) {
+    const roomShapeString = jsonRoom.$.shape;
+    const roomShapeNumber = parseIntSafe(roomShapeString);
+    if (roomShapeNumber === undefined) {
+        fatalError(`Failed to parse the "shape" field of a custom stage room: ${roomShapeString}`);
+    }
+    const roomShape = roomShapeNumber;
+    let doorSlotFlags = 0;
+    for (const door of jsonRoom.door) {
+        const existsString = door.$.exists;
+        if (existsString !== "True" && existsString !== "False") {
+            fatalError(`Failed to parse the "exists" field of a custom stage room door: ${existsString}`);
+        }
+        if (existsString === "False") {
+            continue;
+        }
+        const xString = door.$.x;
+        const x = parseIntSafe(xString);
+        if (x === undefined) {
+            fatalError(`Failed to parse the "x" field of a custom stage room door: ${xString}`);
+        }
+        const yString = door.$.y;
+        const y = parseIntSafe(yString);
+        if (y === undefined) {
+            fatalError(`Failed to parse the "y" field of a custom stage room door: ${yString}`);
+        }
+        const doorSlot = getRoomShapeDoorSlot(roomShape, x, y);
+        if (doorSlot === undefined) {
+            fatalError(`Failed to retrieve the door slot for a custom stage room door at coordinates: [${x}, ${y}]`);
+        }
+        const doorSlotFlag = doorSlotToDoorSlotFlag(doorSlot);
+        doorSlotFlags = addFlag(doorSlotFlags, doorSlotFlag);
+    }
+    return doorSlotFlags;
+}
+/** This is copied from `isaacscript-common`. */
+function getRoomShapeDoorSlot(roomShape, x, y) {
+    // The type assertion is necessary for some reason.
+    const doorSlotCoordinates = ROOM_SHAPE_TO_DOOR_SLOT_COORDINATES[roomShape];
+    for (const [doorSlotString, coordinates] of Object.entries(doorSlotCoordinates)) {
+        const doorSlot = parseIntSafe(doorSlotString);
+        const [doorX, doorY] = coordinates;
+        if (x === doorX && y === doorY) {
+            return doorSlot;
+        }
+    }
+    return undefined;
+}
+/** This is copied from `isaacscript-common`. */
+function doorSlotToDoorSlotFlag(doorSlot) {
+    return DOOR_SLOT_TO_DOOR_SLOT_FLAG[doorSlot];
+}
+/** This is copied from `isaacscript-common`. */
+function addFlag(flags, ...flagsToAdd) {
+    for (const flagToAdd of flagsToAdd) {
+        flags |= flagToAdd; // eslint-disable-line no-bitwise,no-param-reassign
+    }
+    return flags;
+}

package/dist/configFile.js

@@ -0,0 +1,54 @@
+import { fatalError, getJSONC, isFile, writeFile, } from "isaacscript-common-node";
+import path from "node:path";
+import { Config } from "./classes/Config.js";
+import { getModsDir } from "./commands/init/getModsDir.js";
+import { promptSaveSlot } from "./commands/init/promptSaveSlot.js";
+import { CONFIG_FILE_NAME, CONFIG_FILE_PATH, CWD } from "./constants.js";
+const NUM_INDENT_SPACES = 2;
+export async function getConfigFromFile(args, typeScript) {
+    const yes = args.yes === true;
+    const dev = args.dev === true;
+    const existingConfig = getExistingConfig();
+    if (existingConfig !== undefined) {
+        return existingConfig;
+    }
+    // No config file exists, so prompt the user for some information and create one.
+    const modsDirectory = await getModsDir(args, typeScript);
+    const saveSlot = await promptSaveSlot(args, yes);
+    const config = new Config(modsDirectory, saveSlot, dev);
+    createConfigFile(CWD, config, typeScript);
+    return config;
+}
+function getExistingConfig() {
+    if (!isFile(CONFIG_FILE_PATH)) {
+        return undefined;
+    }
+    const config = getJSONC(CONFIG_FILE_PATH);
+    validateMandatoryConfigFields(config);
+    return config;
+}
+/**
+ * Even though some fields are always initialized in the class, it may not be necessarily exist in
+ * the JSON file.
+ */
+function validateMandatoryConfigFields(config) {
+    if (config["modsDirectory"] === undefined) {
+        errorMissing("modsDirectory", "This should be equal to the directory where Isaac mods live on your system.");
+    }
+    if (config["saveSlot"] === undefined) {
+        errorMissing("saveSlot", "This should be equal to the save slot that you test your mods on.");
+    }
+}
+function errorMissing(field, description) {
+    fatalError(`The "${CONFIG_FILE_NAME}" file is missing a "${field}" value. ${description} Please add it.`);
+}
+export function createConfigFile(projectPath, config, typeScript) {
+    if (typeScript) {
+        return;
+    }
+    const configFilePath = path.join(projectPath, CONFIG_FILE_NAME);
+    const configContents = JSON.stringify(config, undefined, NUM_INDENT_SPACES);
+    // Add a newline at the end to satisfy Prettier.
+    const configContentsWithNewline = `${configContents}\n`;
+    writeFile(configFilePath, configContentsWithNewline);
+}

package/dist/constants.js

@@ -0,0 +1,61 @@
+import { PACKAGE_JSON, TSCONFIG_JSON, dirName } from "isaacscript-common-node";
+import os from "node:os";
+import path from "node:path";
+const __dirname = dirName();
+// Miscellaneous
+export const CWD = process.cwd();
+export const CURRENT_DIRECTORY_NAME = path.basename(CWD);
+export const HOME_DIR = os.homedir();
+export const FILE_SYNCED_MESSAGE = "File synced:";
+export const COMPILATION_SUCCESSFUL_MESSAGE = "Compilation successful.";
+export const MOD_UPLOADER_PATH = "C:\\Program Files (x86)\\Steam\\steamapps\\common\\The Binding of Isaac Rebirth\\tools\\ModUploader\\ModUploader.exe";
+export const PROJECT_NAME = "IsaacScript";
+// `isaacscript`
+export const REPO_ROOT = path.join(__dirname, "..");
+// `isaacscript/custom-stage`
+const CUSTOM_STAGE_PATH = path.join(REPO_ROOT, "custom-stage");
+export const CUSTOM_STAGE_FILES_DIR = path.join(CUSTOM_STAGE_PATH, "isaacscript-custom-stage");
+export const SHADERS_XML_PATH = path.join(CUSTOM_STAGE_PATH, "shaders.xml");
+export const XML_CONVERTER_PATH = path.join(CUSTOM_STAGE_PATH, "xml-converter.exe");
+// `isaacscript/isaacscript-watcher`
+export const DISABLE_IT_FILE = "disable.it";
+export const WATCHER_MOD_NAME = "isaacscript-watcher";
+export const WATCHER_MOD_SOURCE_PATH = path.join(REPO_ROOT, WATCHER_MOD_NAME);
+// `isaacscript/file-templates`
+export const TEMPLATES_DIR = path.join(REPO_ROOT, "file-templates");
+// `isaacscript/file-templates/static`
+export const TEMPLATES_STATIC_DIR = path.join(TEMPLATES_DIR, "static");
+// `isaacscript/file-templates/dynamic`
+export const TEMPLATES_DYNAMIC_DIR = path.join(TEMPLATES_DIR, "dynamic");
+export const CI_YML = "ci.yml";
+export const CI_YML_TEMPLATE_PATH = path.join(TEMPLATES_DYNAMIC_DIR, ".github", "workflows", CI_YML);
+export const ACTION_YML = "action.yml";
+export const ACTION_YML_TEMPLATE_PATH = path.join(TEMPLATES_DYNAMIC_DIR, ".github", "workflows", "setup", ACTION_YML);
+export const YARNRC_YML = ".yarnrc.yml";
+export const YARNRC_TEMPLATE_PATH = path.join(TEMPLATES_DYNAMIC_DIR, YARNRC_YML);
+const GITIGNORE = "_gitignore"; // Not named ".gitignore" to prevent npm from deleting it.
+export const GITIGNORE_TEMPLATE_PATH = path.join(TEMPLATES_DYNAMIC_DIR, GITIGNORE);
+export const MAIN_TS = "main.ts";
+export const MAIN_TS_TEMPLATE_PATH = path.join(TEMPLATES_DYNAMIC_DIR, "src", MAIN_TS);
+export const MAIN_DEV_TS_TEMPLATE_PATH = path.join(TEMPLATES_DYNAMIC_DIR, "src", "main-dev.ts");
+export const METADATA_XML = "metadata.xml";
+export const METADATA_XML_TEMPLATE_PATH = path.join(TEMPLATES_DYNAMIC_DIR, "mod", METADATA_XML);
+export const README_MD = "README.md";
+// `isaacscript/schemas`
+const SCHEMAS_DIR = path.join(REPO_ROOT, "schemas");
+export const ISAACSCRIPT_SCHEMA_PATH = path.join(SCHEMAS_DIR, "tsconfig-isaacscript-section-schema.json");
+// `project`
+export const CONFIG_FILE_NAME = "isaacscript.json";
+export const CONFIG_FILE_PATH = path.join(CWD, CONFIG_FILE_NAME);
+export const TSCONFIG_JSON_PATH = path.join(CWD, TSCONFIG_JSON);
+export const PACKAGE_JSON_PATH = path.join(CWD, PACKAGE_JSON);
+export const CONSTANTS_TS_PATH = path.join(CWD, "src", "constants.ts");
+// `project/mod`
+export const MOD_SOURCE_PATH = path.join(CWD, "mod");
+export const MAIN_LUA = "main.lua";
+export const METADATA_XML_PATH = path.join(MOD_SOURCE_PATH, "metadata.xml");
+export const VERSION_TXT_PATH = path.join(MOD_SOURCE_PATH, "version.txt");
+// `project/scripts`
+const SCRIPTS_PATH = path.join(CWD, "scripts");
+export const PUBLISH_PRE_COPY_PY_PATH = path.join(SCRIPTS_PATH, "publish_pre_copy.py");
+export const PUBLISH_POST_COPY_PY_PATH = path.join(SCRIPTS_PATH, "publish_post_copy.py");

package/dist/customStage.js

@@ -0,0 +1,298 @@
+import chalk from "chalk";
+import { copyFileOrDirectory, fatalError, getFileNamesInDirectory, getPackageManagerAddCommand, isDirectory, isFile, makeDirectory, readFile, writeFile, } from "isaacscript-common-node";
+import { parseFloatSafe, parseIntSafe } from "isaacscript-common-ts";
+import path from "node:path";
+import * as tstl from "typescript-to-lua";
+import xml2js from "xml2js";
+import { getJSONRoomDoorSlotFlags } from "./common.js";
+import { CUSTOM_STAGE_FILES_DIR, CWD, MOD_SOURCE_PATH, SHADERS_XML_PATH, XML_CONVERTER_PATH, } from "./constants.js";
+import { execExe } from "./exec.js";
+import { getCustomStagesFromTSConfig } from "./tsconfig.js";
+const ISAACSCRIPT_COMMON = "isaacscript-common";
+const ISAACSCRIPT_COMMON_PATH = path.join(CWD, "node_modules", ISAACSCRIPT_COMMON, "dist", "src");
+const METADATA_LUA_PATH = path.join(ISAACSCRIPT_COMMON_PATH, "customStageMetadata.lua");
+const ROOM_VARIANT_MULTIPLIER = 10000;
+const VARIANT_REGEX = / variant="(?<variant>\d+)"/;
+const WEIGHT_REGEX = / weight=".+?"/;
+const EMPTY_SHADER_NAME = "IsaacScript-RenderAboveHUD";
+export async function prepareCustomStages(packageManager, verbose) {
+    const customStagesTSConfig = getCustomStagesFromTSConfig();
+    if (customStagesTSConfig.length === 0) {
+        return;
+    }
+    validateCustomStagePaths(customStagesTSConfig);
+    copyCustomStageFilesToProject();
+    await insertEmptyShader();
+    await fillCustomStageMetadata(customStagesTSConfig, packageManager);
+    combineCustomStageXMLs(customStagesTSConfig, verbose);
+}
+/**
+ * Before we proceed with compiling the mod, ensure that all of the file paths that the end-user put
+ * in their "tsconfig.json" file map to actual files on the file system.
+ */
+function validateCustomStagePaths(customStagesTSConfig) {
+    for (const customStageTSConfig of customStagesTSConfig) {
+        if (customStageTSConfig.backdropPNGPaths !== undefined) {
+            for (const filePaths of Object.values(customStageTSConfig.backdropPNGPaths)) {
+                for (const filePath of filePaths) {
+                    checkFile(filePath);
+                }
+            }
+        }
+        for (const filePath of [
+            customStageTSConfig.decorationsPNGPath,
+            customStageTSConfig.decorationsANM2Path,
+            customStageTSConfig.rocksPNGPath,
+            customStageTSConfig.rocksANM2Path,
+            customStageTSConfig.pitsPNGPath,
+            customStageTSConfig.pitsANM2Path,
+        ]) {
+            checkFile(filePath);
+        }
+        if (customStageTSConfig.doorPNGPaths !== undefined) {
+            for (const filePath of Object.values(customStageTSConfig.doorPNGPaths)) {
+                checkFile(filePath);
+            }
+        }
+        if (customStageTSConfig.shadows !== undefined) {
+            for (const stageShadows of Object.values(customStageTSConfig.shadows)) {
+                for (const stageShadow of stageShadows) {
+                    checkFile(stageShadow.pngPath);
+                }
+            }
+        }
+        if (customStageTSConfig.bossPool !== undefined) {
+            for (const bossPoolEntry of Object.values(customStageTSConfig.bossPool)) {
+                if (bossPoolEntry.versusScreen !== undefined) {
+                    checkFile(bossPoolEntry.versusScreen.namePNGPath);
+                    checkFile(bossPoolEntry.versusScreen.portraitPNGPath);
+                }
+            }
+        }
+    }
+}
+function checkFile(filePath) {
+    if (filePath === undefined) {
+        return;
+    }
+    if (!filePath.includes("gfx/")) {
+        fatalError(`Failed to validate the "${filePath}" file: all PNG file paths must be inside of a "gfx" directory. (e.g. "./mod/resources/gfx/backdrop/foo/nfloor.png")`);
+    }
+    if (!isFile(filePath)) {
+        fatalError(`Failed to find the "${filePath}" file. Check your "tsconfig.json" file and then restart IsaacScript.`);
+    }
+}
+/** The custom stages feature needs some anm2 files in order to work properly. */
+function copyCustomStageFilesToProject() {
+    const dstDirPath = path.join(CWD, "mod", "resources", "gfx", "isaacscript-custom-stage");
+    makeDirectory(dstDirPath);
+    const fileNames = getFileNamesInDirectory(CUSTOM_STAGE_FILES_DIR);
+    for (const fileName of fileNames) {
+        const srcPath = path.join(CUSTOM_STAGE_FILES_DIR, fileName);
+        const dstPath = path.join(dstDirPath, fileName);
+        copyFileOrDirectory(srcPath, dstPath);
+    }
+}
+/**
+ * The custom stage feature requires an empty shader to be present in order to render sprites on top
+ * of the HUD.
+ */
+async function insertEmptyShader() {
+    const shadersXMLDstPath = path.join(CWD, "mod", "content", "shaders.xml");
+    if (!isFile(shadersXMLDstPath)) {
+        copyFileOrDirectory(SHADERS_XML_PATH, shadersXMLDstPath);
+        return;
+    }
+    // The end-user mod might have their own custom shaders, so we need to merge our empty shader
+    // inside the existing "shaders.xml" file.
+    const shadersXMLDstContents = readFile(shadersXMLDstPath);
+    const shadersXMLDst = (await xml2js.parseStringPromise(shadersXMLDstContents));
+    const hasIsaacScriptEmptyShader = shadersXMLDst.shaders.shader.some((shader) => shader.$.name === EMPTY_SHADER_NAME);
+    if (hasIsaacScriptEmptyShader) {
+        // Our empty shader already exists, so we don't have to do anything.
+        return;
+    }
+    const shadersXMLSrcContents = readFile(SHADERS_XML_PATH);
+    const shadersXMLSrc = (await xml2js.parseStringPromise(shadersXMLSrcContents));
+    const isaacScriptEmptyShader = shadersXMLSrc.shaders.shader.find((shader) => shader.$.name === EMPTY_SHADER_NAME);
+    if (isaacScriptEmptyShader === undefined) {
+        fatalError(`Failed to find the empty shader named "${EMPTY_SHADER_NAME}" in the following file: ${SHADERS_XML_PATH}`);
+    }
+    // Add the empty shader to the mod's existing "shaders.xml" file.
+    shadersXMLDst.shaders.shader.push(isaacScriptEmptyShader);
+    const xmlBuilder = new xml2js.Builder();
+    const newXML = xmlBuilder.buildObject(shadersXMLDst);
+    writeFile(shadersXMLDstPath, newXML);
+}
+/**
+ * In order for the custom stage feature to work properly, Lua code will need to know the list of
+ * possible rooms corresponding to a custom stage. In an end-user mod, this is a Lua file located at
+ * `METADATA_LUA_PATH`. By default, the file is blank, and must be filled in by tooling before
+ * compiling the mod.
+ */
+async function fillCustomStageMetadata(customStagesTSConfig, packageManager) {
+    validateMetadataLuaFileExists(packageManager);
+    const customStages = await getCustomStagesWithMetadata(customStagesTSConfig);
+    const customStagesLua = convertCustomStagesToLua(customStages);
+    writeFile(METADATA_LUA_PATH, customStagesLua);
+    console.log(`Wrote custom stage metadata to: ${METADATA_LUA_PATH}`);
+}
+function validateMetadataLuaFileExists(packageManager) {
+    if (!isDirectory(ISAACSCRIPT_COMMON_PATH)) {
+        const addCommand = getPackageManagerAddCommand(packageManager, ISAACSCRIPT_COMMON);
+        fatalError(`${chalk.red(`The custom stages feature requires a dependency of "${ISAACSCRIPT_COMMON}" in the "package.json" file. You can add it with the following command:`)} ${chalk.green(addCommand)}`);
+    }
+    if (!isFile(METADATA_LUA_PATH)) {
+        fatalError(`${chalk.red("Failed to find the custom stage metadata file at:")} ${chalk.red(METADATA_LUA_PATH)}`);
+    }
+}
+/**
+ * This parses all of the end-user's XML files and gathers metadata about all of the rooms within.
+ * (In other words, this creates the full set of `CustomStageLua` objects.)
+ */
+async function getCustomStagesWithMetadata(customStagesTSConfig) {
+    if (!isFile(METADATA_LUA_PATH)) {
+        fatalError(`${chalk.red("Failed to find the custom stage metadata file at:")} ${chalk.red(METADATA_LUA_PATH)}`);
+    }
+    const customStagesLua = [];
+    for (const customStageTSConfig of customStagesTSConfig) {
+        // Some manual input validation was already performed in the `getCustomStagesFromTSConfig`
+        // function.
+        const { name } = customStageTSConfig;
+        const { xmlPath } = customStageTSConfig;
+        const resolvedXMLPath = path.resolve(CWD, xmlPath);
+        if (!isFile(resolvedXMLPath)) {
+            fatalError(`${chalk.red("Failed to find the custom stage XML file at:")} ${chalk.red(resolvedXMLPath)}`);
+        }
+        const xmlContents = readFile(resolvedXMLPath);
+        // eslint-disable-next-line no-await-in-loop, @typescript-eslint/no-unsafe-assignment
+        const jsonRoomsFileAny = await xml2js.parseStringPromise(xmlContents);
+        const jsonRoomsFile = jsonRoomsFileAny;
+        const roomVariantSet = new Set();
+        const customStageRoomsMetadata = [];
+        for (const room of jsonRoomsFile.rooms.room) {
+            const typeString = room.$.type;
+            const type = parseIntSafe(typeString);
+            if (type === undefined) {
+                fatalError(`Failed to parse the type of one of the "${name}" custom stage rooms: ${typeString}`);
+            }
+            const variantString = room.$.variant;
+            const baseVariant = parseIntSafe(variantString);
+            if (baseVariant === undefined) {
+                fatalError(`Failed to parse the variant of one of the "${name}" custom stage rooms: ${variantString}`);
+            }
+            if (roomVariantSet.has(baseVariant)) {
+                fatalError(chalk.red(`There is more than one room with a variant of "${baseVariant}" in the "${resolvedXMLPath}" file. Make sure that each room has a unique variant. (The room variant is also called the "ID" in Basement Renovator.)`));
+            }
+            roomVariantSet.add(baseVariant);
+            const roomVariantPrefix = customStageTSConfig.roomVariantPrefix * ROOM_VARIANT_MULTIPLIER;
+            const variant = roomVariantPrefix + baseVariant;
+            const subTypeString = room.$.subtype;
+            const subType = parseIntSafe(subTypeString);
+            if (subType === undefined) {
+                fatalError(`Failed to parse the sub-type of one of the "${name}" custom stage rooms: ${subTypeString}`);
+            }
+            const shapeString = room.$.shape;
+            const shape = parseIntSafe(shapeString);
+            if (shape === undefined) {
+                fatalError(`Failed to parse the shape of one of the "${name}" custom stage rooms: ${shapeString}`);
+            }
+            const doorSlotFlags = getJSONRoomDoorSlotFlags(room);
+            const weightString = room.$.weight;
+            const weight = parseFloatSafe(weightString);
+            if (weight === undefined) {
+                fatalError(`Failed to parse the weight of one of the "${name}" custom stage rooms: ${weightString}`);
+            }
+            const customStageRoomMetadata = {
+                type,
+                variant,
+                subType,
+                shape,
+                doorSlotFlags,
+                weight,
+            };
+            customStageRoomsMetadata.push(customStageRoomMetadata);
+        }
+        const customStageLua = {
+            ...customStageTSConfig,
+            roomsMetadata: customStageRoomsMetadata,
+        };
+        customStagesLua.push(customStageLua);
+    }
+    return customStagesLua;
+}
+function convertCustomStagesToLua(customStages) {
+    const customStagesString = JSON.stringify(customStages);
+    const fakeTypeScriptFile = `return ${customStagesString}`;
+    const result = tstl.transpileString(fakeTypeScriptFile, {
+        noHeader: true,
+    });
+    if (result.file === undefined || result.file.lua === undefined) {
+        fatalError("Failed to convert the JSON metadata for the custom stages to a Lua file.");
+    }
+    return result.file.lua;
+}
+/** We combine all of the custom stages together and add them to "00.special rooms.xml". */
+function combineCustomStageXMLs(customStagesTSConfig, verbose) {
+    let allRooms = "";
+    for (const customStageTSConfig of customStagesTSConfig) {
+        const xmlPath = path.resolve(CWD, customStageTSConfig.xmlPath);
+        if (!isFile(xmlPath)) {
+            fatalError(`${chalk.red("Failed to find the custom stage XML file at:")} ${chalk.red(xmlPath)}`);
+        }
+        const xmlContents = readFile(xmlPath);
+        // It is easier to work with the XML files as text rather than converting it to JSON and then
+        // converting it back to XML.
+        const lines = xmlContents.trim().split("\n");
+        // Remove the first line of "<?xml version="1.0" ?>".
+        lines.shift();
+        // Remove the second line of "<rooms>".
+        lines.shift();
+        // Remove the last line of "</rooms>".
+        lines.pop();
+        // Change the variants
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (line === undefined) {
+                continue;
+            }
+            if (!line.includes("<room")) {
+                continue;
+            }
+            const match = line.match(VARIANT_REGEX);
+            if (match === null || match.groups === undefined) {
+                continue;
+            }
+            const baseVariantString = match.groups["variant"];
+            if (baseVariantString === undefined) {
+                continue;
+            }
+            const baseVariant = parseIntSafe(baseVariantString);
+            if (baseVariant === undefined) {
+                fatalError(`Failed to parse the variant of one of the custom stage rooms: ${baseVariantString}`);
+            }
+            const roomVariantPrefix = customStageTSConfig.roomVariantPrefix * ROOM_VARIANT_MULTIPLIER;
+            const variant = roomVariantPrefix + baseVariant;
+            const newLine = line
+                .replace(VARIANT_REGEX, ` variant="${variant}"`)
+                .replace(WEIGHT_REGEX, ' weight="0.0"');
+            lines[i] = newLine;
+        }
+        const modifiedRooms = lines.join("\n");
+        allRooms += modifiedRooms;
+    }
+    const combinedXMLFile = `
+<?xml version="1.0" ?>
+<rooms>
+${allRooms}
+</rooms>
+  `.trim();
+    const contentRoomsDir = path.join(MOD_SOURCE_PATH, "content", "rooms");
+    if (!isFile(contentRoomsDir)) {
+        makeDirectory(contentRoomsDir);
+    }
+    const specialRoomsXMLPath = path.join(contentRoomsDir, "00.special rooms.xml");
+    writeFile(specialRoomsXMLPath, combinedXMLFile);
+    // Convert the XML file to an STB file, which is the format actually read by the game.
+    execExe(XML_CONVERTER_PATH, [specialRoomsXMLPath], verbose, contentRoomsDir);
+}