This page lists everything a script can use: the event table each trigger passes in, and the mw.* and regex.* functions. For how to create scripts, triggers, run order and limits, see Scripts.
Conventions
Every function follows the same return rules:
-
Success returns the value: a record table, a list of them, or
truefor toggles and deletes. -
Refusal returns two values,
niland a reason string such as"not_found". Check for it:local msg, err = mw.messages.get(id) if not msg then print("could not read: " .. err) return end -
A malformed call (wrong argument types, a bad regex) raises an error. Catch it with
pcallif you need to.
Message numbers are the #N the chat shows, from 1. Ranges such as first, last include both ends.
Common refusals
| Reason | When |
|---|---|
"no_permission" |
The person the script runs for lacks the namespace's script permission (see Script permissions). Reads are never refused this way. |
"no_chat" |
A chat function was called with no chat, such as a command picked off a chat page. |
"test_run" |
A function that writes data or needs a chat was called in Run test. |
"not_allowed" |
A function that starts a generation, memory job or image request was called from a trigger that may not. |
"not_found" |
The id names nothing you may use. |
"not_in_chat" |
A character is neither the chat's player nor a participant. |
"generating" |
The message is being generated. |
"held_for_review" |
Content moderation held a character or lore write for review. |
"hold_limit" |
Too much of your content is already held for review. |
Targets
mw.messages.delete, set_visible and select take a target, which is one of:
| Target | Example |
|---|---|
| A message id | "0b6e…" |
| A message number | 12 |
| A range of numbers, both ends included | "3-7" |
| A list of any of these | {1, "4-6", id} |
Records
| Record | Fields |
|---|---|
| Message | id, number, position (the same as number), character_id, author = {id, name}, author_is_player, text, visible_to_ai, generating, version, version_count, created_at. author.id is nil for a speaker with no character (an imported speaker, a narrator or a deleted character). |
| Version | index (from 1), text, active, origin ("original", "edit", "continue", "regenerate", "refine", "split", "merge" or "append"), generating, created_at. |
| Image | id, message_id, content_type, width, height, description, caption_status ("none", "pending", "done", "failed"), url. The url is a signed link that expires (within two days by default); fetch it again rather than storing it. |
| Character | id, name, description, pronouns, appearance, creator, creator_notes, character_version, talkativeness, site_visibility. description and appearance are nil when a site character's content is hidden from you. |
| Prompt | id, name, enabled, purpose, site_visibility, blocks. Each block has id, name, enabled (its switch in this prompt), block_enabled (its own switch), site_visibility. |
| Lore book | id, name, description, global, priority, order_adjustment, token_budget, scan_depth, recursive, site_visibility, forced. mw.lore.book adds entries. |
| Lore entry | id, name, content, keywords, activation, book_id, enabled, order. content and keywords are nil when the book's content is hidden from you. |
| Injection | id, key, content, position, depth, role, condition, enabled, uses, remaining, order, active (whether it applies to the next generation). |
| Memory job | id, tag, status, label, range_start, range_end. |
Events
Every script gets a global event table. Every event has these fields:
| Field | Type | What it holds |
|---|---|---|
trigger |
string | The trigger that ran this script, such as "user_message". |
chat_id |
string | The chat the event happened in. mw.messages.*, mw.generation.*, mw.memory.*, mw.vars.* and mw.injections.* act on it. |
user_message
Outgoing user message. Runs when the player sends a message or saves an edit, before it is stored. Blank text with no images skips scripts. Only the chat owner's own messages run them.
| Field | Type | What it holds |
|---|---|---|
text |
string | The message text after template rendering. An earlier script may already have rewritten it. |
character_id |
string | The author: the chat's player for a new message, the message's author for an edit. |
message_id |
string or nil | The edited message, or nil for a new message. |
edit |
bool | true when an existing message is being edited. |
images |
array of string | The ids of the images sent with the message (already stored, so mw.images.get and mw.images.caption work on them), or the edited message's images. |
Return a string to replace the text, or nothing to keep it. Returning blank text cancels a send unless images are attached; a blank edit is refused.
return event.text .. " *waves*"
ai_generation
Incoming AI generation. Runs when an AI reply finishes successfully, before it is saved. A stopped or failed reply runs no scripts.
| Field | Type | What it holds |
|---|---|---|
text |
string | The reply's full text. A continue includes the original text before the new part. An earlier script may already have rewritten it. |
message_id |
string | The message the reply is written into. |
character_id |
string | The character who spoke. |
mode |
string | "new", "regenerate", "continue" or "refine". |
script_triggered |
bool | true when a script started this generation through mw.generation.*. |
Return a string to replace the saved text, or nothing to keep it. The prompt inspector still shows what the model sent. mw.generation.* is refused here.
return (event.text:gsub("%s+$", ""))
lore_activated
Lore book activated. Runs when a generation activates lore, after the lore is resolved and before the prompt is sent.
| Field | Type | What it holds |
|---|---|---|
character_id |
string | The character about to speak. |
books |
array of {id, name} |
Each book with at least one activated entry, once. |
entries |
array of {id, name, book_id} |
Every activated entry, with the book it activated from. |
script_triggered |
bool | true when a script started this generation through mw.generation.*. |
Return values are ignored. Changes to lore or prompts apply from the next generation, because this one's prompt is already built. mw.generation.* is refused here.
for _, e in ipairs(event.entries) do
mw.lore.set_entry_enabled(e.book_id, e.id, false)
end
image_described
Image described. Runs when an image in a chat gets a description: from a caption model, typed by a person, or set by a script outside this trigger. It runs before replies waiting on the caption read it. Avatars run no scripts, and only the chat owner's own descriptions run them.
| Field | Type | What it holds |
|---|---|---|
text |
string | The new description. An earlier script may already have rewritten it. |
image_id |
string | The described image. |
message_id |
string or nil | The message the image belongs to, or nil for an image still in the composer. |
by |
string | "model", "person" or "script". |
model_id |
string or nil | The caption model, when by is "model". |
tag |
string or nil | The tag passed to mw.images.caption(id, {tag = …}) or to the mw.images.request(prompt, {tag = …}) that brought the image. |
data |
any | The opts.data passed alongside the tag, as given. It is held in memory, so it is nil after a server restart. |
Return a string to replace the saved description, or nothing to keep it; blank is ignored. mw.images.set_description here saves without running this trigger again. mw.generation.* is refused here.
return (event.text:gsub("^This image shows ", ""))
command
Command palette. Runs when picked from the command palette as lua: <name>. See Commands for declaring parameters.
| Field | Type | What it holds |
|---|---|---|
args |
table | The parameters by name. |
args values by parameter type:
| Type | Value |
|---|---|
string, choices |
The text. |
integer, number |
A number. |
boolean |
A boolean. |
character, participant |
A character record. |
message |
A message record. |
lore_book, lore_entry, prompt, prompt_block |
Its record. |
model |
{id, name, api_model_id, completion_mode} |
chat |
{id, name} |
script |
{id, name, description, trigger, enabled} |
A blank optional parameter is nil. Return a string or number to show it as a notice; nothing shows none. Off a chat page, chat_id is nil and chat functions return nil, "no_chat".
When another script calls the command with mw.commands.run, it runs with the caller's event and trigger, with only event.args replaced, and its return values go back to the caller unchanged.
---@param who participant Who speaks
mw.generation.generate(event.args.who.id)
return event.args.who.name .. " is up"
quick_reply
Quick reply. Runs when its button above the composer is clicked, or quick reply: <name> is picked from the palette, in a chat with a player character.
| Field | Type | What it holds |
|---|---|---|
text |
string | What is in the composer when it runs; may be blank. |
| Return | Effect |
|---|---|
| A string | Replaces the composer's text. |
{"message", text} |
Sends text as if typed and sent: templates, {! !} blocks and Outgoing user message scripts run, staged images go with it, and the composer is cleared. |
{"clear"} |
Empties the composer. |
nil or nothing |
Changes nothing. |
return {"message", event.text .. " *waves*"}
inline
Inline, in a sent message. Runs once for each {! … !} block when a message containing them is sent from the composer. See Inline scripts.
| Field | Type | What it holds |
|---|---|---|
character_id |
string | The player character sending the message. |
images |
array of string | The ids of the images being sent. |
index |
integer | This block's position among the message's blocks, from 1. |
Return a string or number to put in the block's place, or nothing to remove the block.
for _, m in ipairs(mw.messages.list()) do
if m.character_id == event.character_id then mw.messages.set_visible(m.id, false) end
end
mw.messages
Messages in the current chat. Writing needs scripts.messages; list, get, last, select and versions are always allowed.
mw.messages.list
mw.messages.list([first [, last]]) returns the chat's messages in order: all of them, or those numbered first to last inclusive. last defaults to the end.
mw.messages.get
mw.messages.get(id) returns the message with this id, or nil, "not_found".
mw.messages.last
mw.messages.last() returns the newest message, or nil in an empty chat. Its number is the newest #N.
mw.messages.select
mw.messages.select(target) returns the messages a target names, in order. It always returns a list, empty when none match.
mw.messages.create
mw.messages.create(author, text) posts text as a new message and returns it.
| Argument | What it takes |
|---|---|
author |
The chat's player or a participant: its character id or {id = character_id}. Or {name = "Narrator"} for a speaker with no character. Another message's author table works. |
text |
The message text. |
Refuses "not_in_chat" for a character outside the chat, and "blank_name" for a blank name.
mw.messages.create({name = "Narrator"}, "Thunder rolls over the hills.")
mw.messages.edit
mw.messages.edit(id, text) saves text as the message's new active version and returns the message. Refuses "generating".
mw.messages.delete
mw.messages.delete(target) deletes messages. For one id or number it returns true, or nil, "not_found". For a range or list it returns how many were deleted. If any of them is generating, it refuses "generating" and deletes nothing.
mw.messages.set_visible
mw.messages.set_visible(target, visible) shows messages to the AI's prompt (true) or hides them (false). For one id or number it returns the message, or nil, "not_found". For a range or list it updates them at once and returns the messages that changed.
mw.messages.versions
mw.messages.versions(id) returns the message's versions (swipes), oldest first, as version records.
mw.messages.set_version
mw.messages.set_version(id, index) makes version index (from 1, as in versions) the active one and returns the message. Refuses "not_found" or "generating".
mw.messages.merge
mw.messages.merge(ids) merges two or more consecutive messages into the first: its new active version joins their texts, and the rest are deleted. Returns the merged message. Refuses "not_found", "too_few", "not_contiguous" or "generating".
mw.messages.split
mw.messages.split(id, match [, multi]) splits the message before the first paragraph (after its first paragraph) whose text contains match, or before every such paragraph when multi is true, as the split editor's markers do. The pieces keep the author and visibility. Returns the resulting messages in order. Refuses "no_match" or "generating".
mw.messages.set_author
mw.messages.set_author(id, author) changes who wrote the message without adding a version. author is a participant's character id, {id = character_id}, or {name = "text"}. Returns the message. Refuses "not_in_chat", "blank_name" or "generating".
mw.images
Images in the current chat. list and get are always allowed; the rest need scripts.images.
mw.images.list
mw.images.list(message_id) returns the images attached to the message, in order, as image records, or nil, "not_found".
mw.images.get
mw.images.get(id) returns one image record, or nil, "not_found".
mw.images.caption
mw.images.caption(id, opts?) has the chat's caption model describe the image in the background and returns true. The description arrives as an image_described run.
| Option | What it does |
|---|---|
tag |
A string that comes back as event.tag. |
data |
Any value, at most 64 KB, that comes back as event.data. |
Refuses "not_found", "no_captioner", "data_too_large", or "same_image" when an Image described script asks for its own image.
mw.images.set_description
mw.images.set_description(id, text) saves text as the image's description, kept over any caption still running; blank clears it. Runs Image described (with by = "script") except from inside it. Returns the image, or nil, "not_found".
mw.images.request
mw.images.request(prompt?, opts?) asks the player for an image: the chat shows a dialog with prompt and a Choose image button, and the image joins the composer like any upload. Returns true at once. The image arrives as an Image described run once it is described, with opts.tag and opts.data as event.tag and event.data. A newer request replaces an open one. Refuses "not_allowed" in Lore book activated, or "data_too_large".
mw.generation
Starts AI replies in the current chat. Needs scripts.generation, and works only in Outgoing user message, Command palette, Quick reply and inline scripts; elsewhere it returns nil, "not_allowed".
mw.generation.generate
mw.generation.generate(character_id [, guide]) queues a reply from a participant, steered by the optional guide text. Returns true, or nil and a reason such as "busy".
mw.generation.regenerate
mw.generation.regenerate(message_id [, guide]) queues a new version of the last AI reply, steered by the optional guide. Returns true, or nil and a reason such as "not_last".
mw.memory
Memory Book commands for the current chat; see Memory. highest is always allowed; the rest need scripts.memory. create, next, catch_up and run_side_prompt follow the same trigger rule as mw.generation and return nil, "not_allowed" elsewhere. Jobs run in the background without token confirmation but keep the configured review policy.
mw.memory.create
mw.memory.create(start, finish) queues a memory for the inclusive message range. Returns its job, or nil and a reason.
mw.memory.next
mw.memory.next() queues a memory for every unprocessed message. Returns its job, or nil, "empty_scene" when none remain.
mw.memory.catch_up
mw.memory.catch_up(start, finish, chunk) queues consecutive memory jobs over the inclusive range, chunk messages each. chunk must be 5 through 250. Returns a list of jobs.
mw.memory.run_side_prompt
mw.memory.run_side_prompt(side_prompt_id [, start [, finish]]) queues a side prompt over the optional inclusive range. Omitted endpoints use its checkpoint and latest defaults. Returns its job; refuses "not_found" for an unknown side prompt.
mw.memory.set_side_prompt_enabled
mw.memory.set_side_prompt_enabled(side_prompt_id_or_all, enabled) enables or disables one global side prompt, or every one for the literal "all". Returns how many changed (0 for "all" with none). If an update fails it refuses with that reason, and the side prompts updated before it stay changed.
mw.memory.highest
mw.memory.highest() returns the processed boundary as a message number, or nil when it is clear.
mw.memory.set_highest
mw.memory.set_highest(number_or_nil) sets the processed boundary to a positive message number, or clears it with nil. Returns true.
mw.characters
Every character you may use, not only this chat's. list, get and find are always allowed; the rest need scripts.characters.
mw.characters.list
mw.characters.list() returns every usable character (your own and the site's) as character records.
mw.characters.get
mw.characters.get(id) returns the character, or nil, "not_found".
mw.characters.find
mw.characters.find(name) returns the first usable character with this whole name, ignoring case and surrounding spaces (your own before the site's, then the oldest), or nil, "not_found". Names are not unique.
mw.characters.update
mw.characters.update(id, fields) updates the given fields, such as {name = "Ciri"}, and returns the character.
mw.characters.set_avatar
mw.characters.set_avatar(character, prompt?, describe?) asks the player for an image that becomes the character's avatar. character is its id or record. The chat shows a dialog with prompt and a Choose image button. Returns true at once; the avatar is set when the image is chosen.
The new avatar is described when the images.auto_caption setting is on and the character's Appearance follows its avatar; describe set to true or false overrides both. The description fills an appearance nobody wrote. A newer request replaces an open one. Needs a chat. Refuses "not_found", or "not_allowed" in Lore book activated.
mw.characters.set_appearance
mw.characters.set_appearance(character, text) saves text as how the character looks (character is its id or record); blank clears it. Returns the character.
mw.prompts and mw.blocks
Prompts and their blocks; see Prompts. mw.prompts.list is always allowed; the switches need scripts.prompts.
mw.prompts.list
mw.prompts.list() returns every prompt you may use (your own and the site's) with its blocks, as prompt records.
mw.prompts.set_enabled
mw.prompts.set_enabled(prompt_id, enabled) turns a prompt on or off and returns true.
mw.prompts.set_block_enabled
mw.prompts.set_block_enabled(prompt_id, block_id, enabled) turns a block on or off in this prompt only (its membership switch) and returns true.
mw.blocks.set_enabled
mw.blocks.set_enabled(block_id, enabled) turns a block on or off in every prompt that holds it (its own switch) and returns true.
mw.lore
Lore books and entries; see Lore. books and book are always allowed; the rest need scripts.lore.
mw.lore.books
mw.lore.books() returns every lore book you may use, as book records.
mw.lore.book
mw.lore.book(id) returns the book with its entries.
mw.lore.create_book
mw.lore.create_book(fields) creates a book from fields such as {name = "Places"} and returns it.
mw.lore.update_book
mw.lore.update_book(id, fields) updates the book's given fields and returns it.
mw.lore.delete_book
mw.lore.delete_book(id) deletes the book and returns true. Entries in no other book become unlinked.
mw.lore.create_entry
mw.lore.create_entry(book_id, fields) creates an entry in the book from fields such as {name = …, content = …, keywords = …} and returns it.
mw.lore.create_entry(book.id, {name = "Harbor", content = "Fog hides the harbor at dawn.", keywords = {"harbor", "docks"}})
mw.lore.update_entry
mw.lore.update_entry(id, fields) updates the entry's given fields and returns it.
mw.lore.delete_entry
mw.lore.delete_entry(id) deletes the entry from every book and returns true.
mw.lore.set_entry_enabled
mw.lore.set_entry_enabled(book_id, entry_id, enabled) turns an entry on or off within this book only and returns true.
mw.lore.set_chat_bound
mw.lore.set_chat_bound(book_id, bound) binds the book to the current chat (true) or unbinds it (false) and returns true. Needs a chat.
mw.vars and mw.globals
Variables that templates read; see Variables. get and list are always allowed; set needs scripts.variables. Values are strings, numbers, booleans and tables of them; anything else raises. A malformed key refuses with the key's error.
mw.vars.get
mw.vars.get(key) returns the chat variable's value (vars.<key> in templates), or nil when it is unset.
mw.vars.set
mw.vars.set(key, value) sets the chat variable, as {% setvar %} does, and returns true. A nil value deletes it.
mw.vars.list
mw.vars.list() returns every chat variable as a table of key = value.
mw.globals.get
mw.globals.get(key) returns the global variable's value as your chats read it (globals.<key>: site globals overlaid by your own), or nil when it is unset.
mw.globals.set
mw.globals.set(key, value) sets your own global variable, never the site's, as {% setglobalvar %} does, and returns true. A nil value deletes it.
mw.globals.list
mw.globals.list() returns every global variable your chats read, as a table of key = value.
mw.injections
The current chat's injections. list and get are always allowed; the rest need scripts.injections.
Injection fields match the chat's injections panel:
| Field | What it takes |
|---|---|
key |
A name to find the injection by. |
content |
The text to inject. |
position |
A lore slot such as "after_author_note" or "at_depth". |
depth |
The depth, for "at_depth". |
role |
"system", "user" or "assistant". |
condition |
When it applies; false clears it. |
enabled |
Whether it is on. |
uses |
How many successful replies it lasts for; false clears it. |
order |
Its order among injections. |
mw.injections.list
mw.injections.list() returns every injection in the chat, spent and disabled ones included, in application order.
mw.injections.get
mw.injections.get(key_or_id) returns the injection with this key or id.
mw.injections.create
mw.injections.create(fields) creates an injection and returns it.
mw.injections.create({key = "mood", content = "Rain falls.", uses = 3})
mw.injections.update
mw.injections.update(key_or_id, fields) updates the injection's given fields and returns it.
mw.injections.set_enabled
mw.injections.set_enabled(key_or_id, enabled) turns the injection on or off and returns true.
mw.injections.rearm
mw.injections.rearm(key_or_id) restores a limited injection's remaining replies to its uses and returns it.
mw.injections.delete
mw.injections.delete(key_or_id) deletes the injection and returns true.
mw.injections.clean_up
mw.injections.clean_up() deletes the chat's spent injections and returns how many.
mw.commands
mw.commands.run
mw.commands.run(name [, args]) runs the enabled Command palette script with this name as if picked from the palette, and returns what it returns. It is always allowed; the command's own calls are checked as usual. Your own command is preferred over a site command of the same name.
| Argument | What it takes |
|---|---|
name |
The command script's name. |
args |
A table keyed by ---@param name. An entity is its id or its record table. |
The command runs with this script's event, trigger and permissions. Refuses "not_found" for no such command, "<param>: <problem>" for a bad argument, and "too_deep" past 3 nested calls. A failing command fails this call.
local notice = mw.commands.run("Weather", {season = "winter"})
mw.roll
mw.roll(dice) rolls dice such as "2d6+1", "d6" or "D20" and returns the total. It is always allowed.
if mw.roll("d20") >= 15 then return event.text .. " (success)" end
regex
PCRE regular expressions, which Lua's own patterns lack. Always allowed. Positions are byte positions from 1.
flags is a string of any of these letters:
| Flag | Meaning |
|---|---|
i |
Ignore case. |
m |
^ and $ match at line breaks. |
s |
. matches newlines. |
x |
Extended: whitespace and # comments in the pattern are ignored. |
U |
Ungreedy: quantifiers are lazy by default. |
An unknown flag or an invalid pattern raises an error.
A match table is {text, start, finish, groups, named}: the matched text, its first and last byte, the numbered groups, and the named groups.
regex.test
regex.test(s, pattern [, flags]) returns whether pattern matches anywhere in s.
regex.match
regex.match(s, pattern [, flags [, init]]) returns the first match at or after byte init as a match table, or nil when there is none.
regex.match_all
regex.match_all(s, pattern [, flags [, limit]]) returns every match (at most limit) as an array of match tables.
regex.replace
regex.replace(s, pattern, repl [, flags [, limit]]) replaces matches (at most limit) and returns the new string and the number of replacements. repl is either a template, where $1 is a group, ${name} a named group and $$ a literal $, or a function that receives the match table and returns a string, or nil or false to keep the match.
local text = regex.replace(event.text, [[\b(\w+) \1\b]], "$1", "i")
regex.split
regex.split(s, pattern [, flags [, limit]]) returns the pieces of s between matches (at most limit splits).
regex.escape
regex.escape(s) returns s with every regex metacharacter escaped, to match it literally.