Skip to content

Commit 9ed3c5a

Browse files
DeadIndianDeadIndian
authored
Merge pull request #41 from AdvancedDiscordBot/docs/sync-with-live-code
docs: sync all documentation with live plugin-platform code
2 parents 7c3f29a + 053c573 commit 9ed3c5a

5 files changed

Lines changed: 141 additions & 160 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ ADB is not currently part of any open source contribution program. There is no e
1515

1616
### Build A Platform
1717

18-
- **Core bot** - Stable Discord.js runtime, commands, events, database, scheduling, and AI support.
18+
- **Core platform** - Lean Discord.js runtime, plugin loader/isolation, database, scheduling, and dashboard host. No user-facing commands live in core.
1919
- **Dashboard** - Admin UI for guild settings, plugin management, and activity visibility.
2020
- **Plugin marketplace** - Registry-backed discovery for installable community modules.
2121
- **Plugin API** - Commands, overrides, events, hooks, config schemas, jobs, and models.
@@ -32,7 +32,7 @@ High priority:
3232

3333
Medium priority:
3434

35-
- New core commands only when they belong in the base bot
35+
- New core/platform capabilities only when they belong in the base runtime (loader, isolation, dashboard, RPC)
3636
- Better observability, logs, and admin feedback
3737
- Performance improvements
3838
- Internationalization and accessibility
@@ -141,8 +141,7 @@ See [CREATE-PLUGIN.md](./CREATE-PLUGIN.md) for the complete plugin guide.
141141

142142
## ✅ Development Guidelines
143143

144-
- Follow the existing command and event structure.
145-
- Keep core changes focused; prefer plugins for optional features.
144+
- Core ships no user-facing commands — features live in `adb-plugin-*` packages. Keep core changes focused on the platform (loader, plugin manager, hook bus, dashboard); prefer plugins for optional features.
146145
- Handle Discord permissions and missing guild/member/channel data gracefully.
147146
- Avoid logging tokens, session secrets, connection strings, or user private data.
148147
- Update documentation when behavior, setup, commands, or plugin APIs change.
@@ -159,7 +158,7 @@ For Discord behavior, also test in a private development guild and include the t
159158
## 🧭 Documentation Map
160159

161160
- [README.md](./README.md) - project overview and setup
162-
- [DOCUMENTATION.md](./DOCUMENTATION.md) - slash command reference
161+
- [DOCUMENTATION.md](./DOCUMENTATION.md) - how commands work + official plugin reference
163162
- [ARCHITECTURE.md](./ARCHITECTURE.md) - runtime architecture
164163
- [CREATE-PLUGIN.md](./CREATE-PLUGIN.md) - plugin authoring guide
165164
- [REGISTRY-SETUP.md](./REGISTRY-SETUP.md) - marketplace registry setup

‎CREATE-PLUGIN.md‎

Lines changed: 27 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -117,10 +117,11 @@ async function load(ctx) {
117117
// ✅ Works in both modes — ctx.db routes through RPC when isolated
118118
const config = await ctx.db.getPluginConfig(guildId, "my-plugin");
119119

120-
// ✅ Works in both modes — ctx.discord routes through RPC when isolated
120+
// ⚠️ ctx.discord is the ISOLATED-mode Discord surface (routes through RPC).
121+
// It does NOT exist in direct mode — there, use ctx.client instead.
121122
await ctx.discord.sendToChannel(channelId, { content: "Hello!" });
122123

123-
// ❌ Only works in direct mode
124+
// ❌ Only works in direct mode (ctx.client is null when isolated)
124125
// const guild = ctx.client.guilds.cache.get(guildId);
125126
// await guild.channels.fetch(channelId);
126127
}
@@ -217,17 +218,17 @@ capability you didn't declare):
217218
218219
| Capability | RPC methods it unlocks |
219220
|------------|------------------------|
220-
| `storage:own-collection` | `ctx.db.getPluginConfig/updatePluginConfig/getAllPluginConfigs`, ticket methods, and all `ctx.defineModel()` model ops (`find`, `findOne`, `create`, `updateOne`, `deleteOne`, `countDocuments`, `save`, `markModified`) |
221+
| `storage:own-collection` | `ctx.db.getPluginConfig/updatePluginConfig/getAllPluginConfigs`, ticket methods, and all `ctx.defineModel()` model ops (`find`, `findOne`, `create`, `updateOne`, `deleteOne`, `countDocuments`, `save`) |
221222
| `storage:read-profiles` | `getUserProfile`, `getTopUsers`, `getUserRank`, `checkRoleRewards`, `getServerConfig`, `getServerStats`, `getUserPoints`, `getPointsLeaderboard` |
222223
| `storage:write-profiles` | `updateUserProfile`, `addXP`, `updateUserRoles`, `givePoints`, `updateServerConfig` |
223224
| `discord:SendMessages` | `ctx.discord.sendToChannel()` (sendMessage/sendRichMessage), `ctx.discord.sendDM()` |
224-
| `discord:EmbedLinks` | `discord.sendEmbed` |
225-
| `discord:AddReactions` | `discord.addReaction` |
226-
| `discord:ManageMessages` | `discord.deleteMessage` |
227-
| `discord:ModerateMembers` | `discord.timeout` |
228-
| `discord:KickMembers` | `discord.kick` |
229-
| `discord:BanMembers` | `discord.ban` |
230-
| `discord:ManageRoles` | `ctx.discord.addRole()`, `ctx.discord.removeRole()` |
225+
| `discord:EmbedLinks` | *(capability reserved — no `ctx.discord` accessor yet; embeds go via the `embeds` array of `sendToChannel`/`sendDM`)* |
226+
| `discord:AddReactions` | *(capability reserved — no `ctx.discord` accessor yet)* |
227+
| `discord:ManageMessages` | *(capability reserved — no `ctx.discord` accessor yet)* |
228+
| `discord:ModerateMembers` | *(capability reserved — no `ctx.discord` accessor yet)* |
229+
| `discord:KickMembers` | *(capability reserved — no `ctx.discord` accessor yet)* |
230+
| `discord:BanMembers` | *(capability reserved — no `ctx.discord` accessor yet)* |
231+
| `discord:ManageRoles` | *(capability reserved — no `ctx.discord` accessor yet)* |
231232
| `discord:GuildInfo` | `ctx.discord.getGuild()`, `ctx.discord.getMember()` |
232233
| `discord:ChannelInfo` | `ctx.discord.fetchChannel()` |
233234
| `hooks:subscribe` | `ctx.hooks.on()` |
@@ -301,7 +302,11 @@ const server = await ctx.db.getServerConfig(guildId);
301302
await ctx.db.updateServerConfig(guildId, { aiEnabled: true });
302303
```
303304
304-
### ctx.discord — Discord API (isolated-mode safe)
305+
### ctx.discord — Discord API (isolated mode only)
306+
307+
`ctx.discord` exists **only in isolated mode** — it's the sandboxed RPC surface
308+
for Discord operations. In direct mode there is no `ctx.discord`; use `ctx.client`
309+
(real discord.js) instead.
305310
306311
```javascript
307312
// Send a message
@@ -440,9 +445,10 @@ await ctx.hooks.emitHook("myPluginEvent", { data: "something" });
440445
441446
### ctx.scheduler — Recurring tasks
442447
443-
Signature: `schedule(cronExpression, callback, name)` — **expression first**, name
444-
last. Core runs the cron and invokes your callback on tick; a bundled
445-
`node-cron` will NOT work in an isolated worker, so always use `ctx.scheduler`.
448+
Signature (isolated mode — the default): `schedule(cronExpression, callback, name)`
449+
— **expression first**, name last. Core runs the cron and invokes your callback on
450+
tick; a bundled `node-cron` will NOT work in an isolated worker, so always use
451+
`ctx.scheduler`.
446452
447453
```javascript
448454
await ctx.scheduler.schedule("0 * * * *", async () => {
@@ -453,6 +459,12 @@ await ctx.scheduler.schedule("0 * * * *", async () => {
453459
await ctx.scheduler.cancel("cleanup");
454460
```
455461
462+
> **Direct mode differs.** When your plugin runs direct (`system:raw-client` or
463+
> in-repo), `ctx.scheduler` is the real `TaskScheduler`, whose signature is
464+
> **name-first**: `schedule(name, cronExpression, fn)`, and cancellation is
465+
> `unschedule(name)` — there is no `cancel()`. Only isolated mode uses the
466+
> `schedule(expression, callback, name)` / `cancel(name)` shim shown above.
467+
456468
### ctx.logger — Namespaced logging
457469
458470
```javascript
@@ -725,7 +737,7 @@ doesn't check permissions itself.
725737
726738
## Publishing Your Plugin
727739
728-
1. **Test locally** with the offline harness (`npm test`) — loads your plugin against a mock `ctx`, no bot/Mongo needed.
740+
1. **Test locally** — the [`adb-plugin-template`](https://github.com/AdvancedDiscordBot/adb-plugin-template) repo ships a local mock-`ctx` harness you can run your plugin against with no bot/Mongo. (Note: this repo's own `npm test` runs the platform test suite — broker/manifest/permissions — not your plugin.) Otherwise, test inside a real bot checkout.
729741
2. **Smoke-test in a real bot** — install into the pre-prod bot's `node_modules` and confirm it loads isolated with no `Missing capability` denials or crash-loops in the log.
730742
3. **Bump the version** — npm forbids republishing an existing version. Patch-bump every publish.
731743
4. **`npm publish`** — the package name must start with `adb-plugin-`; `PluginManager` auto-discovers `node_modules/adb-plugin-*`.

‎DOCUMENTATION.md‎

Lines changed: 57 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -1,105 +1,81 @@
11
<div align="center">
22

3-
# 📚 Advanced Discord Bot Slash Command Documentation
3+
# 📚 Advanced Discord Bot Documentation
44

5-
Official command reference for **Advanced Discord Bot (ADB)**.
5+
How commands work in **Advanced Discord Bot (ADB)**.
66

77
</div>
88

99
---
1010

11-
## 💰 Economy Commands
12-
13-
| Command | Description | Usage |
14-
|--------|-------------|-------|
15-
| `/bal [user]` | Check wallet and bank balance. | `/bal` |
16-
| `/buy <item>` | Buy a role from the shop. | `/buy PremiumRole` |
17-
| `/coinflip <bet> <choice>` | Flip a coin and gamble coins. | `/coinflip 100 heads` |
18-
| `/collect` | Collect income from purchased roles. | `/collect` |
19-
| `/deposit <amount \| all>` | Deposit coins into the bank. | `/deposit all` |
20-
| `/diceroll <bet> <number>` | Roll a die and bet on a number. | `/diceroll 50 4` |
21-
| `/economy-setup [options]` | Configure economy settings. Admin only. | `/economy-setup` |
22-
| `/give <recipient> <amount>` | Give coins to another user. | `/give @user 100` |
23-
| `/leaderboard` | Show the richest users. | `/leaderboard` |
24-
| `/shop` | Display roles available for purchase. | `/shop` |
25-
| `/shop-admin <subcommand> [options]` | Manage the role shop. Admin only. | `/shop-admin add PremiumRole` |
26-
| `/steal <victim>` | Attempt to steal coins. | `/steal @user` |
27-
| `/withdraw <amount \| all>` | Withdraw coins into wallet. | `/withdraw 200` |
28-
| `/work` | Work to earn coins. | `/work` |
11+
## 🧩 ADB has no built-in commands
2912

30-
---
31-
32-
## 🎉 Fun Commands
33-
34-
| Command | Description | Usage |
35-
|--------|-------------|-------|
36-
| `/8ball <question>` | Ask the magic 8-ball a question. | `/8ball Will I win?` |
37-
| `/avatar [user]` | Display a user's avatar. | `/avatar @user` |
38-
| `/meme [subreddit]` | Get a random meme. | `/meme` |
39-
| `/poll <question> <options>` | Create an emoji poll. | `/poll "Best fruit?" apples, bananas, oranges` |
40-
| `/reminder <time> <message>` | Set a reminder. | `/reminder 1h Take a break` |
41-
| `/roll <dice>` | Roll dice. | `/roll 2d6` |
42-
| `/secret` | Discover an easter egg. | `/secret` |
13+
ADB's core is a lean bot runtime + dashboard. **It ships with zero user-facing
14+
slash commands of its own.** Every command your server gets comes from an
15+
installed **plugin** — a package named `adb-plugin-*`.
4316

44-
---
17+
At startup the plugin loader discovers plugins from two places:
4518

46-
## ⚙️ General Commands
47-
48-
| Command | Description | Usage |
49-
|--------|-------------|-------|
50-
| `/banner` | Display server banner. | `/banner` |
51-
| `/birthday <subcommand>` | Manage birthdays. | `/birthday set 1990-01-01` |
52-
| `/botstats` | Bot performance statistics. | `/botstats` |
53-
| `/calculate <expression>` | Perform arithmetic. | `/calculate 5 + 7` |
54-
| `/dm <message>` | Send yourself a DM. | `/dm Remember the meeting!` |
55-
| `/feedback` | Submit feedback. | `/feedback This bot is useful!` |
56-
| `/help` | List bot commands. | `/help` |
57-
| `/joindate [user]` | Show when a user joined. | `/joindate @user` |
58-
| `/ping` | Bot and API latency. | `/ping` |
59-
| `/resetnick` | Reset your nickname. | `/resetnick` |
60-
| `/reverse <text>` | Reverse a message. | `/reverse hello` |
61-
| `/serverinfo` | Display server info. | `/serverinfo` |
62-
| `/setnick <nickname>` | Change your nickname. | `/setnick Hero` |
63-
| `/spoiler <text>` | Hide text as spoiler. | `/spoiler secret text` |
64-
| `/uptime` | Bot uptime info. | `/uptime` |
65-
| `/userinfo [user]` | Detailed user info. | `/userinfo @user` |
19+
- `node_modules/` — anything matching `adb-plugin-*` with a `plugin.json` + entry file
20+
- the local `plugins/` directory — the only in-repo plugin is `plugins/administration` (the dashboard itself)
6621

67-
---
22+
Because the command set depends entirely on which plugins you install, this repo
23+
does **not** maintain a central slash-command list. Each plugin documents its own
24+
commands in its own README.
6825

69-
## 🛡️ Moderation Commands
26+
### The flow: install → enable → deploy → commands appear
7027

71-
| Command | Description | Usage |
72-
|--------|-------------|-------|
73-
| `/ban <user> [reason]` | Ban a user. | `/ban @user spamming` |
74-
| `/kick <user> [reason]` | Kick a user. | `/kick @user offensive language` |
75-
| `/purge <amount> [user]` | Bulk delete messages. | `/purge 50` |
76-
| `/ticket <title> <description>` | Create a support ticket. | `/ticket "Bug Report" "Feature not working"` |
77-
| `/ticketdashboard <subcommand>` | Manage tickets. Mods only. | `/ticketdashboard list` |
28+
1. **Install** a plugin — from the dashboard marketplace, or `npm install adb-plugin-<name>` in the bot's root.
29+
2. **Enable** it from the dashboard (writes it into the plugin config the loader reads).
30+
3. **Deploy** the commands to Discord:
31+
```bash
32+
npm run deploy
33+
```
34+
This runs `node scripts/build-plugins.js && node deploy-commands.js`, which
35+
gathers every enabled plugin's slash commands and registers them with Discord.
36+
4. **Commands appear** in your server. Plugin *logic* hot-reloads, but adding or
37+
changing a slash command definition always needs a fresh `npm run deploy`.
7838

7939
---
8040

81-
## 📈 XP & Leveling Commands
82-
83-
| Command | Description | Usage |
84-
|--------|-------------|-------|
85-
| `/daily` | Claim daily reward. | `/daily` |
86-
| `/points <subcommand>` | Manage or view points. | `/points view` |
87-
| `/profile [user]` | View profile and stats. | `/profile @user` |
88-
| `/roles <subcommand>` | View or claim role rewards. | `/roles claim` |
89-
| `/xpconfig <subcommand>` | Configure XP and leveling. Admin only. | `/xpconfig set multiplier 2x` |
41+
## 🔌 Official plugins
42+
43+
From the registry at [AdvancedDiscordBot/registry](https://github.com/AdvancedDiscordBot/registry).
44+
The commands below are indicative — see each plugin's own README for the full, current reference.
45+
46+
| Plugin | What it adds |
47+
|---|---|
48+
| [`adb-plugin-moderation`](https://github.com/AdvancedDiscordBot/adb-plugin-moderation) | Moderation + tickets: `/ban`, `/unban`, `/kick`, `/timeout`, `/warn`, `/warnings`, `/purge`, `/slowmode`, `/lock`, `/case`, `/history`, `/ticket …`. Numbered case log with auto-escalation. |
49+
| [`adb-plugin-levels`](https://github.com/AdvancedDiscordBot/adb-plugin-levels) | XP & leveling from message activity: `/level`, `/leaderboard`, plus `/level-config` and `/level-roles` for admins. Role rewards on level-up. |
50+
| [`adb-plugin-aegis`](https://github.com/AdvancedDiscordBot/adb-plugin-aegis) | Server protection: anti-raid, anti-spam, link filtering, and alt/join-gate detection. |
51+
| [`adb-plugin-automod`](https://github.com/AdvancedDiscordBot/adb-plugin-automod) | Rule-based auto-moderation: `/automod rule add|remove|edit`, `/automod list`, `/automod whitelist`, `/automod action`. |
52+
| [`adb-plugin-autorole`](https://github.com/AdvancedDiscordBot/adb-plugin-autorole) | Automatically assigns roles to members on join. |
53+
| [`adb-plugin-confessions`](https://github.com/AdvancedDiscordBot/adb-plugin-confessions) | Anonymous confessions with optional approval: `/confess text`, `/confess-admin …`. |
54+
| [`adb-plugin-counting`](https://github.com/AdvancedDiscordBot/adb-plugin-counting) | Counting game channel: `/counting channel|stats|reset`. |
55+
| [`adb-plugin-custom-commands`](https://github.com/AdvancedDiscordBot/adb-plugin-custom-commands) | Lets admins define their own custom text/response commands. |
56+
| [`adb-plugin-giveaways`](https://github.com/AdvancedDiscordBot/adb-plugin-giveaways) | Giveaways: `/giveaway start|end|reroll|list`. |
57+
| [`adb-plugin-invite-tracker`](https://github.com/AdvancedDiscordBot/adb-plugin-invite-tracker) | Invite tracking + leaderboard: `/invites me|user|leaderboard`, `/invites-admin …`. |
58+
| [`adb-plugin-reaction-roles`](https://github.com/AdvancedDiscordBot/adb-plugin-reaction-roles) | Self-assignable roles via reactions/buttons. |
59+
| [`adb-plugin-reminders`](https://github.com/AdvancedDiscordBot/adb-plugin-reminders) | Personal reminders: `/remind set|list|cancel`. Bot DMs you when due. |
60+
| [`adb-plugin-server-logs`](https://github.com/AdvancedDiscordBot/adb-plugin-server-logs) | Audit logging by category: `/log set|remove|list|enable|disable|ignore|retention`. |
61+
| [`adb-plugin-tempvoice`](https://github.com/AdvancedDiscordBot/adb-plugin-tempvoice) | Temporary "join-to-create" voice channels with owner controls (lock, limit, rename, permit/deny, claim). |
62+
| [`adb-plugin-todo`](https://github.com/AdvancedDiscordBot/adb-plugin-todo) | Personal to-do lists: `/todo add|list|done|remove|edit|clear`. |
63+
| [`adb-plugin-welcome`](https://github.com/AdvancedDiscordBot/adb-plugin-welcome) | Configurable welcome / goodbye messages and cards. |
64+
65+
> Command names above were taken from each plugin's README/source where verified.
66+
> Exact options and subcommands can change between versions — the plugin's own
67+
> README is always the source of truth.
9068
9169
---
9270

93-
## 🤖 AI & Plugin Commands
71+
## 🔗 Where to look next
9472

95-
| Command | Description | Usage |
96-
|--------|-------------|-------|
97-
| `/aiassistant ask <question>` | Ask the AI assistant. | `/aiassistant ask What can you do?` |
98-
| `/config-ai` | Configure AI plugin behavior. | `/config-ai` |
99-
| `/faq` | Use FAQ assistant features when the AI plugin is enabled. | `/faq` |
100-
| `/antiraid <subcommand>` | Manage anti-raid system. | `/antiraid enable` |
101-
| `/truthordare <subcommand>` | Play Truth or Dare. | `/truthordare start` |
73+
- **Per-plugin command reference** — each plugin's `README.md` (linked in the table above) lists its full, current command set.
74+
- **Marketplace / registry** — browse and install plugins from the dashboard, or see the registry: [AdvancedDiscordBot/registry](https://github.com/AdvancedDiscordBot/registry).
75+
- **Building your own plugin** — [CREATE-PLUGIN.md](./CREATE-PLUGIN.md).
76+
- **Getting started with the bot** — [README.md](./README.md).
10277

10378
---
10479

105-
Plugins can add more slash commands at runtime. Re-run `npm run deploy` after adding or changing slash command definitions so Discord receives the updated command list.
80+
Adding or changing a plugin's slash commands? Re-run `npm run deploy` so Discord
81+
receives the updated command list.

0 commit comments

Comments
 (0)