Script Arguments

A script button can hand your script a value when it runs. One script, several buttons or alternates, each passing a different value: “split by word”, “split by line”, “merge selected”. This page is the whole contract, and the last section is written to be pasted into an AI assistant.

How a value reaches your script

While a script button runs, Code Runner sets one global object, codeRunner, and removes it again the moment the script finishes. Nothing else in After Effects ever sees it.

codeRunner = {
  version: "2.1.0",            // the Code Runner version that ran the button
  button: {
    id: "mu33q5ws-341807c1",   // the button's permanent id
    name: "Regrouper",         // the button's name
    kind: "script",
    argument: "a"              // the value, or "" when the button has none
  },
  modifiers: {                 // what was held at the click
    alt: false,
    shift: false,
    ctrl: false,
    meta: false
  }
};

Facts your script can rely on:

• codeRunner.button.argument is always a string. With no value set it is "", so you can test it without guarding for undefined.
• The object exists only during a Code Runner run. Running the same file from File > Scripts finds no codeRunner at all, so check for it before reading it.
• The modifiers are booleans captured at the click. On macOS, a Ctrl alternate is pressed with Command and reports as ctrl.
• The global is removed after every run, even one that throws, so a stale value can never leak into the next click.

Where the value comes from

Three places, and a fixed order:

1. An argument alternate. In the button editor, Alternates > Run this script with a value adds a row with its own value, a name, and an optional modifier chord. Holding that chord at the click, or picking the row from the long-press flyout, runs the script with that row’s value.
2. The button’s own Value. The Value field on a script button is the default a plain click passes. Leave it empty and a plain click passes "".
3. Nothing. A script button with no Value and no alternates still gets the codeRunner object, with argument set to "".

An alternate’s value always wins over the button’s own when an alternate is what is running.

Writing a script that takes a value

Read the value once, fall back to something sensible, and branch on it:

(function () {
  var mode = "";
  if (typeof codeRunner !== "undefined" && codeRunner.button) {
    mode = codeRunner.button.argument;
  }
  if (!mode) mode = "characters";   // what a plain click, or File > Scripts, should do

  switch (mode) {
    case "characters": splitByCharacters(); break;
    case "words":      splitByWords();      break;
    case "lines":      splitByLines();      break;
    default:           alert("Unknown mode: " + mode);
  }
})();

Two habits make the button editor better at helping:

• Compare against literal strings (mode === "words", case "lines":, mode.indexOf("x")). The Value field reads your script and suggests the values it finds compared this way, so nobody has to remember them.
• Say what you accept when the value is unknown. A silent fallback teaches nobody which values exist.

If your script has a dialog, the usual shape is: a value means run headless, no value means show the dialog.

Converting a KBar script

Scripts written for KBar read kbar.button.argument or kbar.argument. They never see codeRunner, so a value set in Code Runner is ignored and the script falls back to its dialog.

Code Runner notices this. When a script button’s Value field or an argument alternate is set on a script that reads kbar but not codeRunner, the field shows a warning and offers to add a short adapter at the top of the script. You see the exact lines first, and nothing is written until you save the button. The block is:

// Added by Code Runner so this script's
// existing argument handling works here too.
if (typeof codeRunner !== "undefined" && codeRunner.button) {
  if (typeof kbar === "undefined" || (kbar && kbar.viaCodeRunner)) {
    $.global.kbar = codeRunner.button.argument
      ? { viaCodeRunner: true, argument: codeRunner.button.argument, button: { argument: codeRunner.button.argument } }
      : undefined;
  }
}

What it does: when Code Runner is running the script, it publishes the value under both KBar spellings, so the script’s own kbar checks pass unchanged. When a real KBar is running the script, the block leaves KBar’s object alone. When neither is present, the script sees no kbar and takes its normal path.

You can also convert by hand: replace each read of kbar.button.argument or kbar.argument with codeRunner.button.argument, guarded by the typeof codeRunner check above.

For an AI assistant

Paste this when asking an assistant to write or adapt a script for Code Runner:

Write an Adobe After Effects ExtendScript (ES3: no let/const, no arrow functions,
no Array.prototype.map/forEach, no JSON unless the script provides it) that can
be run from a Code Runner button.

Contract: while Code Runner runs the script, a global object `codeRunner` exists:
  codeRunner.button.argument  string, "" when no value was set
  codeRunner.button.name      string
  codeRunner.button.id        string
  codeRunner.modifiers        { alt, shift, ctrl, meta } booleans, captured at the click
  codeRunner.version          string
The object is absent when the file is run from File > Scripts, so always test
`typeof codeRunner !== "undefined" && codeRunner.button` before reading it.

Rules:
1. Read the value once into a local, fall back to a default when it is "".
2. Branch on the value by comparing against literal strings (===, switch/case,
   or indexOf), so Code Runner can suggest the accepted values in its editor.
3. If the script has a dialog, a value means run without the dialog.
4. Wrap changes to the project in app.beginUndoGroup / app.endUndoGroup.
5. Never leave anything on $.global; Code Runner removes `codeRunner` itself.
6. If the script already reads KBar arguments (kbar.button.argument or
   kbar.argument), keep those reads and add this block at the very top of the
   file, above everything except #target and #include lines:

   // Added by Code Runner so this script's
   // existing argument handling works here too.
   if (typeof codeRunner !== "undefined" && codeRunner.button) {
     if (typeof kbar === "undefined" || (kbar && kbar.viaCodeRunner)) {
       $.global.kbar = codeRunner.button.argument
         ? { viaCodeRunner: true, argument: codeRunner.button.argument, button: { argument: codeRunner.button.argument } }
         : undefined;
     }
   }

Accepted values for this script: <list them>