Scenario scripts · RPGCortex Help

Scripts are small JavaScript programs that run every turn and can reshape how your scenario plays: rewrite what the player typed, add details to what the AI reads, post-process the AI's response, keep counters and manage State Cards.

Writing a script#

Open your scenario in the editor, go to the Script tab and tick Enable Scenario Script. Write your code in Script Source, then press Test Script to run it against some sample text. Output from console.log appears under Logs (last 15 minutes) — press Refresh Logs to update it.

The three hooks#

Define any of these as top-level functions. Each receives a piece of text and returns what should be used instead.

Hook	Runs	Receives
`onInput(text)`	Before the AI is called	The player's input
`onModelContext(text)`	Just before the AI is called	The instructions and context sent to the AI
`onOutput(text)`	After the AI responds	The AI's response

Return an object with the new text:

function onInput(text) {
  // Let players type "look" as a shortcut
  if (text.trim().toLowerCase() === "look") {
    return { text: "I look around carefully." };
  }
  return { text };
}

function onOutput(text) {
  state.turns = (state.turns || 0) + 1;
  return { text };
}

Returning an empty text from onInput or onOutput counts as an error. From onModelContext, empty text means "keep the original".
Return { text, stop: true } (or just the string "stop") to halt the turn. The player sees "Script requested stop".

What scripts can use#

Name	What it is
`text`	The text passed to the current hook.
`state`	An object that persists between turns — store counters, flags and anything JSON-friendly (up to 64 KB). It's saved with each turn, so it follows rewinds and branches.
`info`	Details such as `characterNames` and `actionCount`. In `onModelContext` it also includes `maxChars` and `memoryLength`.
`history`	Recent turns, each with `text`, `rawText` and `type`.
`storyCards`	The adventure's State Cards (also available as `cards` and `worldInfo`).
`addStoryCard`, `updateStoryCard`, `removeStoryCard`	Create, change or remove State Cards. Locked cards can't be changed or removed by scripts. A script can create up to 300 cards.
`rollTable(name)`	In `onOutput` only: roll on a Table card by name. Returns the result, or `null` if there's no such table.
`console.log(...)`	Write to the logs.

A scenario can also run scripts written by others:

Tick Mark as Script to add a scenario to your own Scripts, where you and others can attach it elsewhere. This doesn't change its visibility.
In the Scripts section of the Script tab, press + Add Script to browse your saved scripts (Saved) and ones you made (My Scripts). A scenario can attach up to 3 scripts; each has an Enabled toggle and a Remove button.
Attached scripts run from top to bottom, alongside your scenario's own script.
Attaching copies the script's code at that moment — later edits by its author don't carry over automatically.

Players can find scripts in Discover → Filters → Content Type → Scripts, and add them to an adventure with More → Attach scripts on a scenario's page (up to 3 per adventure in total). Script source code is only visible to its author.

Limits and behavior#

Scripts run in a secure sandbox with a time limit of about 2.5 seconds and 16 MB of memory per run.
Scripts can be up to 65,535 characters.
If a script errors during play, the turn carries on without that script's changes.
Any script turns off streaming — responses appear all at once rather than word by word.
Changing your script makes your content rating out of date, so you'll need to Check Rating again before publishing changes.

Writing a script#

The three hooks#

What scripts can use#

Sharing and attaching scripts#

Limits and behavior#