Scripting Guide

Differences from discord.js

What carries over from discord.js, what is intentionally different, and a migration mapping for developers who know the library.

If you have written discord.js bots, GuildScript will feel familiar: builders have the same names and methods, events have the same names, and payload fields match discord.js properties closely. But agents are not discord.js programs. This page lists every difference that matters, and why it exists.

The big picture

There is no Client

The platform owns the Discord connection, the token, the intents, and the event loop. An agent never logs in and never registers listeners; it is the listener for the one event you selected. Anything in discord.js that hangs off client (client.user, client.guilds.cache, client.ws.ping, REST calls) has no equivalent, by design: an agent only sees the server it runs in.

// discord.js
const client = new Client({ intents: [GatewayIntentBits.GuildMessages, ...] });
client.on("messageCreate", async (message) => {
  if (message.content === "!hi") await message.reply("Hello!");
});
client.login(process.env.TOKEN);

// GuildScript (upload on the messageCreate event)
export async function onMessage(message) {
  if (message.author.bot) return;
  if (message.content === "!hi") await message.reply("Hello!");
}

Snapshots instead of class instances

Payload objects are JSON snapshots taken when the event fired, with async action methods attached. The practical consequences:

• No managers or caches. Where discord.js has guild.members.cache (a Collection), GuildScript has explicit calls: guild.members.fetch(id), guild.members.list({ limit }), or plain arrays like member.roleIds.
• Collections become arrays. Anything iterable is a normal array: message.attachments, mentions.users (an array of IDs), guild.channels.list().
• Data can go stale. A snapshot reflects the moment of the event. When freshness matters, call the object's fetch() method to get an updated snapshot.
• Actions return new snapshots. channel.setName(...) resolves to the updated channel data rather than mutating the object you hold.

Errors are values, not exceptions

In discord.js a failed API call rejects and, unhandled, can crash your process. In GuildScript every Discord, database, and AI action catches its own failure and returns { error, code } (or a fallback like null). Your run continues; you decide what matters. Only bugs in your own code throw, and those are reported to the agent's error channel. There is rarely a reason to write try/catch in an agent.

What is intentionally restricted, and why

Migration mapping

Porting checklist

1. Delete client setup, intents, login, and any process.env usage.
2. Split each client.on block into its own file with one exported async function.
3. Change imports from "discord.js" to "discord" and remove imports that no longer exist (Client, GatewayIntentBits, Partials).
4. Replace cache access (*.cache) with payload fields, list() calls, or fetch() calls.
5. Replace in-memory state and timers with db documents and timestamps.
6. Replace thrown-error handling with result checks (if (x?.error)).
7. Upload each file with /agents on its matching event and set an error channel.