Undercards Script

Looking to install the script? Click Here

Contributing

You'll need Node.js 24. The tests need at least 22.18, which is where Node started running TypeScript files without a flag.

git clone https://github.com/UCProjects/UnderScript.git
cd UnderScript
npm install

Building

• npm run build builds the script once into dist/.
• npm start rebuilds whenever a file in src/ changes. It also includes files named *.local.js (or in a *.local folder), which are left out of normal builds, and writes the translations to lang/underscript.ignore.json.
• Files and folders with .ignore in the name are never built or committed, so they're a good place for scratch work.

Trying it out

Install a userscript manager such as Tampermonkey, allow it to access file URLs, and add a script that loads your build. Chrome, Edge and Opera also need "Developer mode" turned on at chrome://extensions (edge://extensions, opera://extensions), or "Allow User Scripts" for Tampermonkey on Chrome 138 or newer:

// ==UserScript==
// @name     UnderScript (dev)
// @match    https://*.undercards.net/*
// @exclude  https://*.undercards.net/*/*
// @run-at   document-body
// @grant    none
// @require  https://unpkg.com/[email protected]/dist/showdown.min.js
// @require  https://unpkg.com/[email protected]/dist/umd/popper.min.js
// @require  https://unpkg.com/[email protected]/umd/index.all.min.js
// @require  https://unpkg.com/[email protected]/dist/axios.min.js
// @require  https://unpkg.com/[email protected]/build/global/luxon.min.js
// @require  https://raw.githubusercontent.com/feildmaster/SimpleToast/3.0.0/dist/simpletoast.js
// @require  file:///path/to/UnderScript/dist/underscript.js
// ==/UserScript==

The @require lines before the last one are copied from src/meta.js, which is the source of truth if they ever change. Tampermonkey does not re-read the header of a local script, so copy any change into it by hand. Disable the regular UnderScript while you test. If both are enabled, whichever loads second stops with "UnderScript loaded twice" in the console, and that may be your build.

Before opening a pull request

• npm run lint and npm test should pass. npm run css checks the stylesheets.
• Add a line to the ## Unreleased section of changelog.md for anything a player or plugin author would notice. Don't add a version number or date.
• Don't include lang/underscript.json, it's generated by the build.
• Open the pull request against master.

Plugin Registry

Community plugins are listed in plugins.json, which UnderScript fetches from master to populate the "Community Plugins" menu. To add a plugin, open a pull request with an entry:

{
  "name": "Deck Tracker",
  "author": "feildmaster",
  "updateURL": "https://github.com/UCProjects/plugin-tracker/releases/latest/download/tracker.meta.js"
}

• name must match the name the plugin passes to underscript.plugin(name), otherwise UnderScript can't tell that it's already installed.
• updateURL points at anything the version can be read from: a userscript (or .meta.js) file, a gist, or a github release. The install link is taken from its @downloadURL, or from the release's .user.js asset.
• downloadURL is only needed when the install link can't be derived from updateURL.
• A plugin needs at least one of updateURL and downloadURL. With only downloadURL, UnderScript reads the version from it and installs from it, the same as plugin.updater('https://...').

Pull requests that change plugins.json are checked automatically. The file must be valid JSON, every entry needs a valid name and author and at least one of updateURL and downloadURL (https links only), and UnderScript must be able to read a version and an install link from them, and that link has to answer and not be a web page. Run npm run plugins to see the same errors locally, or npm run plugins -- --offline to skip the network part.

To try entries out before pushing them, declare the file as a plugins.json resource in your development userscript header:

// @grant    GM_getResourceText
// @resource plugins.json file:///path/to/UnderScript/plugins.json

Translations

English strings live in lang/en. To translate them into another language, generate a template from your language code (for example fr):

npm install
npm run lang -- fr

This creates lang/fr/*.json, with one file per English file. Each string appears twice: a // line with the English text, and the real key with an empty value for you to fill in.

"//dismiss": "Dismiss",
"dismiss": "Fermer"

• Only edit the values. Leave the // lines alone, they're just there for reference.
• Strings left empty fall back to English, so a partial translation is fine. An array (a list of strings) is only used once every entry in it is filled in.
• Keep placeholders such as $1 and {{...}} in your translation exactly as they are.
• Run the command again after pulling changes. It adds new strings, never overwrites your translations, and prints how many are left in each file.
• If the English text of a string you already translated changes, its comment becomes //dismiss!. Review your translation, then remove the ! from the key to clear the flag.
• Keys that no longer exist in English are moved to the bottom of the file and reported as unknown. Delete them or move them to the right key.

lang/underscript.json is generated by the build, so don't edit it or include it in your pull request.