NovelAI Scripting API Documentation

Welcome to the NovelAI Scripting API documentation. Scripts allow you to extend NovelAI’s functionality with custom UI components, generation hooks, and document manipulation capabilities. They are written in TypeScript, a superset of JavaScript.

Getting Started

The User Scripts modal can be found in the goose menu in the left sidebar, or, when a story is selected, the advanced tab of the right sidebar. Alt+X will also open the modal.

This modal is where you will can import, create, and modify scripts. There are two levels of scripts, account and story. Account scripts are saved to the account and will be loaded when any story is selected. Story scripts are saved to the story file and will be loaded only when that story is loaded.

Sections

• API Reference

• Hooks

• Storage

• UI Extensions

• UI Parts

• Modals and Windows

• Document

• Generating Text

• Context Building

• Story Settings

• Lorebook

• Text-to-Speech

• Utilities

• Messaging

• Permissions

• Decorations

Architecture

Scripts are run executed in an isolated JavaScript interpreter in a Web Worker and can interact with NovelAI only through a set of predefined API methods. As scripts are run in a Web Worker, they don’t block the UI thread and won’t interrupt the main page while running. Because of this most API functions are asynchronous and return promises. If you’re unfamiliar with promises in JavaScript or need a refresher I recommend this page from the MDN Web Docs.

What You Can’t Do

For security and privacy reasons scripts don’t have free reign over the page. There are several things they cannot do. Scripts are not allowed to make arbitrary network requests, access most user account information, directly access the DOM, or alter parts of the page not designated for scripts.

Scripts Are Transient

Scripts can be unloaded at any time, such as when the user disables them, switches stories, or closes the User Scripts modal. Because of this scripts should avoid maintaining important state in memory. Instead they should use the Storage API to persist important data.

I’ve made the website unusable, how do I disable scripts?

If a rogue script has made the website unusable to the point where that script cannot be disabled through the User Scripts modal, you can disable all scripts by adding ?noscript=true to the end of the URL and reloading the page. This will prevent any scripts from loading, allowing you to access the User Scripts modal and disable or remove the problematic script.

Unhandled Promise Rejections

For various technical reasons, unhandled rejected promises in scripts will not show any error message in the UI or console. To avoid silent failures, make sure to properly handle errors in your scripts using .catch on promises or awaiting them in a try/catch block.

Example Scripts

Here’s a few example scripts to get you started. If the links open in a new tab, you can right-click and choose “Save link as…” to download them or save the page once opened.

• Scripting Demo Scenario - A scenario containing an example script demonstrating various scripting features. The demos cover most aspects of scripting and include editable examples.

• Smart Summarizer - Adds a right click option to summarize selected text in the editor.

• Bookmarks - A script that lets you create “bookmarks” in a story. They let you save the current location in the story history and jump back to it later.

• Find & Replace - A script that adds a Find & Replace panel to the UI allowing you to search and replace text in the document.

• Retry Harder - A script that provides an alternative retry button with special prompting.

Some more example scripts can be found in the novelai-script-examples repository on GitHub.

Type Definitions

An m.ts file containing type definitions for the scripting API can be found at http://novelai.net/scripting/types/script-types.d.ts. This file can be used to provide type information and autocompletion in editors that support it.