@noita-ts/create-mod 0.1.0

package/dist/index.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import * as p from "@clack/prompts";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+function bail(msg) {
+    p.cancel(msg);
+    process.exit(1);
+}
+function cancellable(value) {
+    return p.isCancel(value) ? bail("Cancelled.") : value;
+}
+async function main() {
+    p.intro("@noita-ts/create-mod");
+    const dirArg = process.argv[2];
+    const location = dirArg ??
+        cancellable(await p.text({
+            message: "Select a directory:",
+            validate(v) {
+                if (!v) {
+                    return "A dir name is required";
+                }
+                if (fs.existsSync(v)) {
+                    return `Location "${v}" already exists.`;
+                }
+            },
+        }));
+    const modId = cancellable(await p.text({
+        message: "Mod ID:",
+        placeholder: "my-ts-mod",
+        initialValue: path
+            .basename(location)
+            .replaceAll(/\s+/g, "-")
+            .toLowerCase(),
+        validate(v) {
+            if (!v) {
+                return "Name is required";
+            }
+            if (!/^[a-z0-9-_]{1,32}$/.test(v)) {
+                return "Use up to 32 lowercase alphanumeric characters, hyphens, and underscores only";
+            }
+        },
+    }));
+    const name = cancellable(await p.text({
+        message: "Name:",
+        placeholder: "Example TS Mod",
+    }));
+    const description = cancellable(await p.text({
+        message: "Description:",
+        placeholder: "A mod written in typescript via noita-ts",
+    }));
+    const unsafe = cancellable(await p.confirm({
+        message: "Unsafe? (aka 'no API restrictions', prevents publishing to Steam Workshop)",
+        initialValue: false,
+    }));
+    const author = cancellable(await p.text({
+        message: "Author (leave empty to skip):",
+        placeholder: "",
+    }));
+    const extraBaseDeps = cancellable(await p.multiselect({
+        message: "Extra base dependencies (space to select, enter to confirm/skip):",
+        required: false,
+        options: [
+            {
+                value: "@noita-ts/nxml",
+                hint: "a library for convenient Noita XML file editing, wrapper around Nathans NXML fork",
+            },
+            {
+                value: "@noita-ts/pollnet",
+                hint: "a networking library, wrapper around pollnet",
+            },
+            {
+                value: "@noita-ts/ffi",
+                hint: "a set of Noita engine modding utitiles",
+            },
+        ],
+    }));
+    const workshop = !unsafe &&
+        cancellable(await p.confirm({
+            message: "Setup (some of) Steam Workshop metadata?",
+            initialValue: true,
+        }));
+    let workshopName;
+    let workshopDescription;
+    if (workshop) {
+        workshopName = cancellable(await p.text({
+            message: "Workshop Name:",
+            placeholder: "My TS Mod",
+            initialValue: name,
+        }));
+        workshopDescription = cancellable(await p.text({
+            message: "Workshop Description:",
+            placeholder: "A description for the Steam Workshop",
+            initialValue: description,
+        }));
+    }
+    copyDir(path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "template"), location);
+    const pkg = {
+        name: modId,
+        description,
+        ...(author ? { author } : {}),
+        version: "0.1.0",
+        private: true,
+        ["noita.name"]: name,
+        ["noita.compat"]: 12,
+        ...(unsafe ? { ["noita.unsafe"]: true } : {}),
+        ...(workshopName ? { ["noita.workshop.name"]: workshopName } : {}),
+        ...(workshopDescription
+            ? { ["noita.workshop.description"]: workshopDescription }
+            : {}),
+        scripts: {
+            start: "nts run",
+            build: "nts build",
+        },
+        dependencies: {
+            "@noita-ts/base": "latest",
+            ...Object.fromEntries(extraBaseDeps.map((dep) => [dep, "latest"])),
+        },
+    };
+    fs.writeFileSync(path.join(location, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
+    p.note([`cd ${location}`, `npm install`, `npm start`, `npx nts publish`].join("\n"), "Next steps");
+    p.outro("Happy modding!");
+}
+function copyDir(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDir(srcPath, destPath);
+        }
+        else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@noita-ts/create-mod",
+  "version": "0.1.0",
+  "description": "Scaffold a new noita-ts mod",
+  "type": "module",
+  "bin": "./dist/index.js",
+  "files": [
+    "dist",
+    "template"
+  ],
+  "scripts": {
+    "prepublishOnly": "rm -rf dist && npm run build",
+    "build": "tsc"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.3.2",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.0.1"
+  }
+}

package/template/readme.md

@@ -0,0 +1,48 @@
+## A noita-ts mod template
+
+Includes a basic `init.ts` and `settings.ts` file setup, as well as generates
+a sensible `package.json` that is ready to run.
+
+A `workshop-preview.png` file in the root package directory will be used for
+the workshop preview if present.
+
+The keys from the `package.json` file used by `nts` to produce a mod:
+
+- `"name": "example-mod"`\
+  Name of the package also doubles as mod ID, although you can override it in `noita.id`.
+- `"description": "An example mod written in TypeScript using noita-ts"`\
+  Description of the npm package, also doubles as in-game mod description unless overridden by `noita.description`.
+- `"author": "necauqua"`\
+  Author of the package, not actually used in mod creation (yet).
+- `"noita.id": "example-mod"`\
+  Can be used to set the mod ID and free up the npm package name.
+- `"noita.name": "Example TypeScript Mod"`\
+  Name of the mod shown in-game (defaults to `noita.id`/`name`)
+- `"noita.description": "An example mod written in TypeScript using noita-ts"`\
+  Description of the mod shown in-game, defaults to package description.
+- `"noita.unsafe": false`\
+  Sets the `"request_no_api_restrictions"="1"` key in mod.xml - unsafe mods cannot be published to the workshop and must be installed manually, but are not sandboxed - meaning you can do network/file access, ffi and literally anything at all, including being a crypto miner.
+- `"noita.workshop.id": 0`\
+  This will be set by the publish command automatically. If you want to publish the mod as a separate workshop item (e.g. after deleting the original), remove this, otherwise don't touch it
+- `"noita.workshop.name": "Example TypeScript Mod"`\
+  Name of the mod on the steam workshop page, defaults to value of noita.name
+- `"noita.workshop.description": "Uploaded to the workshop!"`\
+  The description of the mod on the steam workshop page, defaults to value of `noita.description`.
+- `"noita.workshop.tags": []`\
+  Tags for the mod on the steam workshop page, just sets the corresponding key in `mod.xml`.
+- `"noita.workshop.skip-files": []`\
+  Files to skip when uploading to the workshop, just sets the corresponding key in `mod.xml`.
+- `"noita.workshop.skip-folders": []`\
+  Folders to skip when uploading to the workshop, just sets the corresponding key in `mod.xml`.
+- `"noita.compat": 12`\
+  API compatibility version, should Noita release a big update that changes this number, an icon "this mod has not been tested with latest mod api" will be shown in the modlist.
+- `"noita.ui-newgame-name": null`\
+  This and everything below is just setting other mod.xml properties:
+  - `"noita.ui-newgame-description": null`
+  - `"noita.ui-newgame-gfx-banner-bg": null`
+  - `"noita.ui-newgame-gfx-banner-fg": null`
+  - `"noita.is-game-mode": false`
+  - `"noita.game-mode-supports-save-slots": false`
+  - `"noita.is-translation": false`
+  - `"noita.translation-xml-path": null`
+  - `"noita.translation-csv-path": null`

package/template/src/init.ts

@@ -0,0 +1,5 @@
+import mod from "@noita-ts/base";
+
+mod.on("PlayerSpawned", () => {
+  GamePrint("Hello World");
+});

package/template/src/settings.ts

@@ -0,0 +1,28 @@
+// By doing settings in such a way, we can have auto-completable
+//`mod.settings.checkbox` anywhere, and it would also have a correct `boolean`
+// type.
+//
+// Additionally, you also can declare something like this anywhere:
+// ```typesctipt
+// declare global {
+//   interface SettingsShape {
+//     a_setting_we_just_use_to_persist_stuff: string
+//   }
+// }
+// And just get/set/delete it via `mod.settings.<name> = <value>` for convenience.
+// It will use `mod_id.setting_name` key for the actual stored setting of course.
+declare global {
+  interface SettingsShape extends ExtractSettings<
+    typeof import("./settings")
+  > {}
+}
+
+export default [
+  {
+    id: "checkbox",
+    ui_name: "checkbox",
+    ui_description: "This is a test setting",
+    value_default: false,
+    scope: ModSettingScope.Runtime,
+  },
+] as const satisfies ModSetting[];

package/template/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "@noita-ts/base/mod-tsconfig.json",
+}