NovelAI Journal
Back to NovelAI

Journal entry

Introducing NovelAI User Scripts

Published

In 2021 we announced that we wanted to add scripting functionality to NovelAI. For various reasons the plans fell by the wayside. However, the time for scripting has finally come and we’re excited to share with you a new way to customize NovelAI.

While scripting opens up powerful customization options, it is an advanced feature. Creating scripts requires scripting knowledge, and even installing and configuring scripts may be more complex than typical NovelAI features.

What does scripting mean? What are user scripts?

Scripts are pieces of code, written by you or other users, that you can add to an individual story or apply to your account to add new functionality to NovelAI. These could range from small utilities and organizational tools all the way to overhauls of how lorebooks work or even small text-based games, inventory/RPG systems, and much more!

**Do I need to code to use scripts?
**You don’t need to code to use scripts created by others, but you will need to code if you want to create your own scripts. Scripts are written in TypeScript or JavaScript.

If you only wish to use scripts other people have written, go to the #novelai-scripts channel in Anlatan discord server to find them.

**Are scripts safe to use?
**We’ve tried our best to limit the amount of damage a script can do, but for scripting to be as powerful and useful as we want it to be there will always be some risk involved.

Scripts aren’t able to leak information to third parties or change your account details, but they can — if given permission — freely modify the contents of any stories they are run on. This means either by accident or malice they could delete, alter, or corrupt the contents of the story. You should only ever download and add scripts from sources and people you trust.

Our support cannot help with debugging issues caused by scripts and cannot recover data loss caused by scripts. Downloading a backup of a story (or all of your stories at once) before adding a new script is highly recommended.

**Where can I find scripts?
**You can share your scripts or use scripts other people have written at the #novelai-scripts channel in our discord.

**How do I add/create a script?
**Scripts can be added through the User Scripts modal. The model can be accessed through:

  • The goose menu in the left sidebar
  • The advanced tab in the right sidebar (when a story is selected)
  • Pressing Alt+X as a keyboard shortcut

When you add or create a script, you’ll have the choice of adding as one of two types:

  • Account scripts save to your account and run on every story
  • Story scripts save to the story file and run on only that story

**Help! A script made it so I can’t use the website!
**If you’ve accidentally made the website unusable by adding a user script to your account or story, you can force the website to not load scripts by going to http://novelai.net/stories?noscript=true.

Scripting Limitations

There are limitations to what scripting is able to do. Some for practical reasons, some for security reasons. Notable ones are listed below:

  • Currently, most generation related parts of the API only support generations made with GLM 4.6.
  • Scripts only function in stories that use Editor V2. Editor V2 has been the default for quite a while now and most or all of your stories likely use it. To use scripts on an Editor V1 story you will first need to convert it to Editor V2.
  • Scripts cannot make network requests. They can only interact with specific NovelAI api endpoints using the scripting api.
  • Scripts cannot directly access or modify the DOM. They can alter the page only through creating UI elements through the api and cannot directly create elements to place into the DOM.

Documentation and Examples

Our docs page has been updated with information on scripting including a full api reference, additional pages on specific topics within the scripting api, and a few example scripts. The documentation does expect you to be familiar with the fundamentals of programming in TypeScript/JavaScript.

Can’t find what you need there? 
Come visit our Discord. Our team or other community members may be able to help!